holocron/plugins/kyberforge/skills/agent-audit/references/body-and-delegation.md

source_keys

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: ADR-0020, 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

ADR-0020 gates a skill body at 600 words SUGGESTION / 900 FAIL and deliberately gates an agent body 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.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/<name>.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 stale README row 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 <skill> 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.
• 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. <long explanation>, 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.

Auditing guidance

Flag as FAIL if:

• The body restates a procedure owned by a skill the agent can invoke — Fix: invoke <skill> instead
• A sentence answers "no" to the core test — it is padding
• A decision point presents a menu of options with no default
• An instruction repeats content already in the description
• Frontmatter comments are template scaffolding rather than instruction, or are HTML comments at plugin/APM scope
• A prescriptive sequence is used where flexibility is fine, or the reverse

Flag as SUGGESTION if:

• The body does not open with a direct role instruction
• The job the agent describes is unbounded, or bounded only implicitly
• A rationale is missing from a rule the agent is expected to enforce — present but unexplained
• Comments are useful but verbose enough to bury the field they annotate