--- source_keys: - context7-websites-code-claude - claude-code-plugins-docs - claude-code-subagents-docs - context7-github-en-copilot - github-custom-agents-configuration --- # Body, Delegation and Comment Discipline Reference Upstream source: Claude Code subagent and plugin references, GitHub Copilot custom-agents configuration. House contract: the context budget. Read this when judging the **body**, **delegation** and **comment-discipline** dimensions. ## The core test For every sentence in the body, ask: **"Would the agent get this wrong without this instruction?"** If no — cut it. The agent already knows it from general training. Adding it wastes tokens and dilutes the signal of what matters. ## Agents take no body word gate A skill body is gated at 600 words SUGGESTION / 900 FAIL; an agent body is deliberately gated at nothing. The two are not the same construct: a skill body is loaded into the caller's live context and competes with the conversation already there, while an agent body *becomes* the system prompt of a fresh context that has nothing else in it. The rationale for the 900-word ceiling does not transfer, so: - **Never report an agent body as too long on a word count.** There is no number to cite. - **Never add such a gate to `scripts/validate.sh`.** `tests/validate-agent.bats` pins its absence with a body far past 900 words that must still pass, and adding one would contradict the ADR. - The one length signal that does apply is the Copilot runtime's 30,000-character body limit, which `validate.sh` already reports as a SUGGESTION because content past it is silently truncated. Length is judged through the delegation check below instead, which is the defect a word count was standing in for anyway. ## The delegation check A plugin-scope agent is a single `.apm/agents/.agent.md` file with no sibling `references/` directory. It cannot progressively disclose to itself — it can only delegate to skills. So a procedure spelled out in an agent body that a skill the agent invokes already owns is not a shortcut: it is a second copy of that procedure, and the second copy drifts. This is the characteristic agent defect, the way a `SKILL.md` naming a `references/` file that is not there is the characteristic skill defect. **An agent body that restates a procedure owned by a skill it can invoke is a FAIL.** The Fix is always the same shape: invoke `` instead. How to apply it: for each procedural block in the body — a rule list, a numbered sequence, a constraint table — ask which skill owns that procedure. If the agent names that skill anywhere (its dispatch table, its routing prose, its frontmatter), the block is a restatement and the skill is already there to be invoked. Worked example. The three `*-orchestrate` agents exist to compose domain skills — `git-orchestrate` (933 body words), `gitea-orchestrate` (1,199) and `apm-orchestrate` (1,080) — so any step they spell out that the composed skill already owns is the defect. `git-orchestrate:24-31` carries a "Hard rules" list (Conventional Commits types, atomic commits, never commit secrets, git trailers) that `git-commits` owns and that `git-orchestrate:44` routes to by name; `:39` concedes the point outright, noting the sub-skills "carry their own local copies of these rules". Two copies, one authority, and nothing keeping them in step. What is **not** a finding under this rule, because no skill owns it: - The dispatch table itself — which operation routes to which skill. - Safety gates the agent enforces before dispatching, and refusals it makes on its own authority. - The input contract and the structured output the agent's caller consumes. - Session state the agent carries across skill invocations. ## What the body is for Include what the fresh context lacks: - A direct role instruction opening the prompt: `You are a [role]. When invoked, [action].` - One bounded job, stated so the agent knows what it must refuse. - The dispatch, gates, inputs and outputs listed above. - **Error handling** — what the agent does on malformed, missing or contradictory input: stop and report, or degrade to a named fallback. Absent it, the agent invents a recovery, and a subagent's invented recovery is invisible to its caller until the output is wrong. - Non-obvious environment facts and project-specific conventions it cannot infer. - One default per decision point with one escape hatch. Do not include at all: - Concepts the agent already knows (what JSON is, how HTTP works, what a CSV is) - Exhaustive option lists — pick a default; the agent does not benefit from choosing - Steps the agent handles independently — over-specifying leads to unproductive paths - Restatements of the description, which is already in context ## Comment discipline Inspect every comment block in the YAML frontmatter and apply the core test to each: *would the agent get this wrong without this comment?* Template scaffolding — `# Optional. `, more than a line or two of inline guidance per field — belongs to development, not to a shipped file. At plugin/APM scope the stakes are higher than tidiness: `apm compile` copies frontmatter verbatim to every target, `` is not valid YAML, and `validate.sh` FAILs a frontmatter block that still contains one. ## Where the criteria live Every FAIL and SUGGESTION criterion for these dimensions is in `references/agent-finding-criteria.md`, which Step 3 reads on every run. This file is the reasoning behind them, loaded only when that file puts the body, delegation or comment-discipline dimension in play.