{
  "markdown": "# briefing\n\n> **Programmatic briefing beats prompt stuffing.**\n\nA subagent declares the skills it needs. `briefing` guarantees those skills are\nin its context *before it thinks its first thought* — no \"MANDATORY: load X\nfirst\" pleading in the body, no silent skips.\n\nWorks in **Claude Code** and **Codex**, from one set of files.\n\n## The problem this solves\n\nEvery agent harness that has both subagents and skills has the same gap, and it\nfollows from two design decisions that are individually correct:\n\n**Subagents start fresh.** A subagent gets its own context window — that is the\npoint of it. Whatever the main agent had read, the subagent has not.\n\n**Skills load lazily.** Skills use progressive disclosure: what sits in the\ncontext window is a *list* — each skill's name, description, and where to find\nit. The instructions themselves are only read once the agent decides it needs\nthem. That keeps the context small, and it works well for an agent browsing a\nmenu.\n\nPut the two together and you get an agent that was spawned *because* it needs\nparticular expertise, and that must nonetheless discover that expertise on its\nown, from a one-line description, in the middle of a task. Sometimes it does.\nSometimes it decides the description does not match closely enough and does the\nwork uninformed — and nothing in the output says so.\n\nThe usual workaround is to write the instruction into the agent's body: *\"You\nMUST invoke the getty-perl-core skill before doing anything.\"* That is prompt\nstuffing. It competes for attention with everything else in the prompt, it\nduplicates content that already exists in a skill, and it degrades quietly.\n\nCodex sharpens the problem. Its own system prompt tells the main agent:\n\n> *\"Do not delegate reading, summarizing, or interpreting skill instructions to\n> a subagent.\"*\n\nSo the subagent is not supposed to read the skill — and nothing hands it over\neither.\n\n`briefing` closes the gap mechanically: at spawn time, a hook reads the agent's\ndeclaration, resolves each skill, and puts the full text into the agent's\ncontext. The agent wakes up already briefed. If a declared skill cannot be\nfound, nothing proceeds on a partial briefing.\n\n## How it works\n\n| | Claude Code | Codex |\n|---|---|---|\n| Hook event | `PreToolUse` on the `Agent` tool | `SubagentStart` |\n| Agent definition | `.claude/agents/<name>.md` | `.codex/agents/<name>.toml` |\n| Declaration | `briefing.skills` in frontmatter | `[briefing] skills` table |\n| Injection | rewrites the agent's prompt | `additionalContext` |\n| Missing skill | spawn is **denied** | agent starts, told to abort |\n\nThe last row is not a choice. A `SubagentStart` hook cannot stop a spawn — Codex\nparses `continue: false` for compatibility but ignores it. So under Codex the\nnearest honest equivalent is an agent that starts and refuses: instead of skills\nit receives an instruction not to attempt the task and to report the failure.\n\n## Declaring skills\n\n**Claude Code** — under a `briefing:` block in the agent's frontmatter:\n\n```yaml\n---\nname: my-agent\ndescription: ...\nallowed-tools: Read, Edit, Bash\nbriefing:\n  skills:\n    - getty-perl-core\n    - getty-perl-moose\n    - superpowers:brainstorming\n---\n\nYou are my-agent. Do the thing.\n```\n\n**Codex** — as a `[briefing]` table in the agent's TOML:\n\n```toml\nname = \"my_agent\"\ndescription = \"...\"\ndeveloper_instructions = \"\"\"\nYou are my_agent. Do the thing.\n\"\"\"\n\n[briefing]\nskills = [\"getty-perl-core\", \"getty-perl-moose\", \"superpowers:brainstorming\"]\n```\n\nSame names, same resolution rules, same namespacing — only the file format\ndiffers, because the two harnesses define agents differently.\n\nEverything lives under a `briefing` namespace so nothing collides with keys the\nharness owns. Two are left alone on purpose: a bare top-level `skills:` in\nClaude Code frontmatter, and Codex's own `[[skills.config]]`. The latter means\n*\"this skill is visible to the agent\"*, which is not the same as *\"preloaded\"* —\nreinterpreting it would take away your ability to say one without the other.\n\nSkill names resolve the same way in both worlds:\n\n- **bare** (`getty-perl-core`) — project skills, then user skills, then plugin caches.\n- **namespaced** (`superpowers:brainstorming`) — straight to that plugin's skills.\n\nOnly the roots differ, and each side searches exactly where its own harness\nlooks: `.claude/skills/` for Claude Code, `.agents/skills/` for Codex.\n\n## Install\n\n**Claude Code**, via the shared marketplace that carries every Getty plugin:\n\n```\n/plugin marketplace add Getty/marketplace\n/plugin install briefing@getty\n```\n\nThis repo is *also* a one-plugin marketplace for Claude Code. That one is legacy —\nit serves the people who installed briefing before the shared catalog existed, and it\nstays maintained so nobody has to migrate:\n\n```\n/plugin marketplace add Getty/briefing\n/plugin install briefing@briefing\n```\n\nBoth paths install the same plugin from the same repo and both keep receiving\nupdates. If you installed the old way, a `SessionStart` hook mentions the shared\nmarketplace once and then never again.\n\n**Codex**, from the shared marketplace — the only route there:\n\n```\ncodex plugin marketplace add Getty/marketplace\ncodex plugin add briefing@getty\n```\n\nCodex asks you to trust a plugin's hooks before it runs them. Until you do,\n`briefing` is installed but silent — no error, no injected context, agents simply\nspawn unbriefed. If skills are not arriving, check the hook trust prompt first.\nNon-interactive runs (`codex exec`) cannot grant that trust at all.\n\n## Authoring briefing-aware agents\n\nThe plugin ships a `briefing` skill documenting how to write agents that use it\ncorrectly — both declaration formats, the anti-pattern of restating skills in the\nagent body when they are already injected, and a recipe for migrating\nprompt-stuffed agents. Invoke it as `/briefing`, or let the agent pick it up when\nit works on agent files.\n\n## Try it\n\n```sh\ncp examples/agents/briefing-demo.md       /your/project/.claude/agents/\ncp -r examples/skills/briefing-demo-skill /your/project/.claude/skills/\n```\n\nSpawn the `briefing-demo` subagent — it echoes a magic phrase from the skill,\nproving the body was in its context before its first turn.\n\n## Develop\n\n```sh\npython3 -m py_compile hooks/briefing-preload\npython3 -m unittest discover tests -v\n```\n\nStdlib only, no dependencies. CI runs Python 3.10 / 3.11 / 3.12 — the Codex\nbranch parses TOML with `tomllib` where it exists and falls back to a small regex\nparser on 3.10, so both paths are exercised across the matrix.\n\n## Status\n\nWorking in both harnesses, verified end to end: a Codex subagent declaring\n`[briefing] skills` answered from skill content it was never told to read, while\nthe identical agent without the declaration did not. See `CHANGELOG.md` and\n`TODO.md`.\n\n## License\n\nCopyright (c) 2026 Torsten Raudssus.\n\nThis is free software; you can redistribute it and/or modify it under the\nterms of the [Artistic License 2.0](LICENSE).\n",
  "bytes": 6955,
  "sha": "33738f26f9c74f4b022a356d14c84c8391f7f1d46eac20b7da49a1933ebc24a9",
  "repo_slug": "getty/briefing",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_getty_briefing_briefing_02b90b65/readme"
}