Defame1297
ede3f06689
Diffing each retrofitted SKILL.md against its replacement references/ files found rules that existed on main and now existed nowhere — relocated in intent, deleted in fact. A trim that loses a rule is not progressive disclosure, it is data loss with a smaller word count. Three had no survivor. The least-privilege guidance for `tools` kept its mechanics and lost the "restrict to what the agent needs" half, so the remaining text read as encouragement to omit the field. The improve flow lost its regression check, so nothing compared the closing audit against the pre-edit state and a PASS quietly becoming a SUGGESTION went unnoticed — restored on both halves of the author pair, since agent-author had dropped its equivalent too. And agent bodies lost "would the agent get this wrong without it?", which mattered more than it looks: ADR-0020 deliberately sets no body word gate for agents, three of the four already sit between 933 and 1,199 words, and the delegation check only fires on procedure a skill already owns. That heuristic was the only brake left. Two more were reachable only from the wrong scope. agent-author tells the reader to load only the file for the resolved scope, but the mcp__ glob syntax for disallowedTools and the five tools no subagent ever receives had both landed in project-user-scope.md. disallowedTools is the ONLY permitted fence at plugin/APM scope, so the scope that needs the syntax most could not reach it, and a plugin-scope run could write a body telling the agent to ask the user a question. Two documents were actively wrong rather than merely thin. agent-audit told auditors that validate.sh resolves boundary targets for skills only; it runs at both scopes, so the auditor was hand-resolving what the script had already decided and could contradict it. And skill-audit routed to its script-troubleshooting reference whenever validate.sh "fails" — but it exits 1 on ordinary content FAILs, the normal outcome for the whole #99 population, so 1,302 words loaded on nearly every audit. A context-budget regression inside the skill that enforces the context budget. Finally, two illustrations taught the shape the gate ERRORs on, unfenced, while an adjacent rubric called it a hard ERROR. LESSONS.md records the reference-chain depth rule flipping from "one level deep" to "two hops, never three". ADR-0020 is silent on it and the reversal rode entirely on the diff; the looser rule is what mandatory dispatch requires. Refs: #99 ADR: 0020 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_015W3iwF9ncfRZddGBxsMCYi
agent-author
Creates and improves agent definition files for Claude Code and GitHub Copilot CLI.
What it does
Scaffolds and fills in agent definition files at plugin/APM, project, or user scope. Project and user scope always generate a Claude Code + Copilot CLI file pair (.md + .agent.md) in one pass. Plugin/APM scope generates a single vendor-neutral .apm/agents/<name>.agent.md file instead — no separate Claude Code / Copilot split, since apm compile has no per-target field integrator (see ADR-0016). Also applies improvement signals — grill output, inline feedback, session context — to existing agent files. Bumps the version after every change: the resolved package's apm.yml at plugin/APM scope (minor for new agents, patch for improvements); project/user scope has no manifest to bump.
Before you start
Have ready: the agent's name (kebab-case), the root directory (plugin root, project root, or ~), a one-sentence purpose, and the triggering condition (when should the runtime delegate to this agent?).
Usage
/agent-author
Manual scaffold (human workflow):
bash scripts/new-agent.sh <agent-name> <root>
# Examples:
bash scripts/new-agent.sh code-reviewer packages/my-package/ # plugin/APM scope if packages/my-package/apm.yml has a type: field
bash scripts/new-agent.sh deploy-assistant .
bash scripts/new-agent.sh security-reviewer ~
Files
| File | Purpose |
|---|---|
SKILL.md |
Skill instructions for agents — gotchas, the create/improve dispatch table, the scope dispatch table, the shared gates, and validation/close |
scripts/new-agent.sh |
Scaffolds agent definition file(s) from templates — a single .apm/agents/<name>.agent.md at plugin/APM scope, or a Claude Code + Copilot CLI pair at project/user scope |
references/create.md |
Create flow: prerequisites, scaffold and scope walk-up, what to fill in, package-root sources.md |
references/improve.md |
Improve flow: signal verification, root-cause grouping, generalizing, delegation over growth, ADR-0020 retrofit |
references/contract.md |
Description and body contract: three-part description shape, 250/400 tiers, delegation rule in place of a body word gate, invocation axis |
references/plugin-scope.md |
Plugin/APM scope field rules for the single vendor-neutral file, plus its pre-audit checklist |
references/project-user-scope.md |
Project/user scope field rules for the Claude Code + Copilot pair, both Copilot formats, plus its pre-audit checklist |
references/deployment-modes.md |
Scope hierarchy and precedence, scoped identifiers, cache isolation, path conventions |
references/scripts.md |
Conventions for new-agent.sh and the templates it copies: contract, template variables, file placement, error messages |
references/sources.md |
Research provenance — sources that informed this skill |
assets/templates/claude-code.md |
Annotated Claude Code agent definition template (project/user scope) |
assets/templates/copilot.agent.md.template |
Annotated Copilot CLI agent definition template (project/user scope) |
assets/templates/apm-agent.md |
Annotated vendor-neutral APM agent definition template (plugin/APM scope) |
tests/new-agent.bats |
(source-only) bats tests for scripts/new-agent.sh |
assets/README.md |
Directory meta-documentation for assets/ |
references/README.md |
Directory meta-documentation for references/ |
scripts/README.md |
Directory meta-documentation for scripts/ |
tests/README.md |
(source-only) bats dependency instructions and run command |
Rows marked (source-only) exist in the authoring source (.apm/skills/agent-author/) but are
not present in an installed plugin: scripts/sync-plugin-content.sh strips
<category>/<name>/tests when it generates the flat mirror, because these are dev-time fixtures no
plugin host needs to discover (ADR-0017). Run them from a repo checkout, not from an install. The
assets/templates/ rows above are unaffected — the exclusion is depth-scoped to
<category>/<name>/tests, so template trees that themselves contain a tests/ directory ship
intact.