Defame1297
4a5c3c0cff
Skill name+description pairs are preloaded into every session, costing ~6,200 tokens across 39 skills before any skill is invoked. The authoring rules mandated that growth: skill-author:104 and description-quality.md:21 both required padding, while skill-author:102 (the deflating rule) had no FAIL condition behind it. Gates (blocking, no baseline file): - description 250 chars SUGGESTION / 400 FAIL, measured on the folded YAML value - body-only 600 words SUGGESTION / 900 FAIL, independent of the unchanged whole-file 2770-word / 500-line spec backstop - every boundary-clause routing target must resolve to a real skill or agent; catches skill-improve, neuledge-context and gitea-labels - agents take the description gates but deliberately no body gate; a test pins that absence Vale: DescriptionOpener widened to ^This\b, new CompositionNote rule banning architecture notes from descriptions. 10 hits, 0 false positives. Kyberforge's own four skills retrofitted: descriptions 3,364 -> 938 chars (-72%), bodies 8,306 -> 2,487 words (-70%), all via the apm-workflow dispatch pattern. Fixes the skill-improve dangling route and the agent-author misroute to manual review. Also fixes a pre-existing false positive where any line-initial 'read ' was flagged as interactive input, which had already caused two scripts to be rewritten around it. Refs: ADR-0020
117 lines
5.8 KiB
Markdown
117 lines
5.8 KiB
Markdown
---
|
|
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
|