Defame1297
fc305ba7d9
Five documents told authors that a prose-form dangling routing target blocks. The
gate reports it as a SUGGESTION and exits 0. Verified on fixtures: `-> name` and
`/name` are blocking ERRORs, the prose form is SUGGESTION-tier unless a second
resolving target in the same sentence corroborates it. ADR-0020 and gates.md were
right; contract.md, retrofit.md, description-quality.md, finding-criteria.md and
agent-author's contract.md were wrong — and they are what an author and an auditor
actually read. The whole 39-skill corpus was retrofitted against them.
skill-audit was also self-contradictory: it imports validate.sh's SUGGESTIONs into
the Structure dimension verbatim while its own rubric grades the same target a FAIL,
so one target got reported twice at two tiers. The script owns the grade; the rubric
now says so.
The YAML-fold trap that broke gitea-labels-milestones (#100) was warned about only
in retrofit.md, reachable only from the improve flow when a budget is exceeded. It
is now in both contract.md files, which SKILL.md mandates on the create flow too.
agent-audit loaded both rubrics unconditionally on every run — 3,323 words for a
clean audit against skill-audit's 1,636. dac9cad fixed exactly this in skill-audit
and edited agent-audit in the same commit without applying it. Same treatment: the
criteria move to a new finding-criteria.md and load per dimension. Clean run now
2,083 words, a 37% cut.
Routing: apm-workflow's description shed dependency installation while still owning
the flow, and apm-install's boundary did not exclude it, so "install my apm
dependencies" matched the CLI-binary skill with no route back. Fixed on both sides.
forge regains two of the three phrasings the retrofit deleted.
forge Step 1 called grill-with-docs unconditionally — a skill in plugins/bin, which
kyberforge does not declare as a dependency. It resolves here only because the
walk-up sweeps sibling plugins; a standalone install dead-ends. Step 1 now names
the cross-plugin dependency and gives an inline fallback. Declaring it properly in
apm.yml remains the better fix.
Also: both audit SKILL.md files now grade exit 2 as "did not run, dimension
unverified" rather than as findings; skill-audit's README row described content that
moved, which its own finding-criteria.md grades a FAIL; and body-discipline.md's
`git show <sha>:plugins/...` command is fenced, since an installed plugin cache has
no repo and file-structure.md makes a bare repo path a FAIL.
Refs: #100, #101, #125
ADR: 0020
9.2 KiB
source_keys
| source_keys | ||
|---|---|---|
|
The agent description and body contract
House contract, set by ADR-0020. The counts and the boundary targets are enforced by
agent-audit's scripts/validate.sh; the prose patterns by the Vale styles it bundles; the
judgment calls by its reference files.
Why the budget exists
An agent's name and description is loaded into every session's context at startup, whether or
not the agent is ever delegated to — the same cost a skill's description carries, so agents take
the same numbers. The body is different: it is not loaded into the caller's conversation at all,
it becomes the system prompt of a fresh context when the agent runs. That is why the body has no
word gate here and a skill body has one.
Description
A description carries exactly three things:
- Trigger clause — when to delegate, imperative: "Use when …", never "This agent …". Describe the user's intent and the triggering condition, not the agent's internal mechanics.
- At most one capability clause — what it does, one clause, no enumeration. Be specific ("reviews a diff for injected credentials", not "helps with security").
- Boundary clause — form:
Not <thing> -> <name>.Add one only where a near-miss agent or skill could steal delegations.
Banned from a description; move it to the body or to README.md:
- Capability enumeration or feature lists
- Per-scope emission mechanics — which files the author skill writes at which scope changes no delegation decision
- Output-format detail ("Produces a compact findings report with Why and Fix per finding")
- Composition or architecture notes ("composes X rather than duplicating Y", "cross-cutting")
- Implementation detail ("Self-validates via a bundled deterministic script")
- Restating the same trigger twice in two registers — a verb list, then the same verbs re-quoted as user phrasings. This is a FAIL, not a suggestion.
Do not open with an action verb. "Reviews…", "Analyzes…", "Generates…" was the old house rule
and ADR-0020 deleted it: the opener is Use when, matching every skill in this corpus, so one
router reads one shape.
"Use proactively" is Claude Code-only, and conditional even there. The phrase steers the Claude Code runtime to offer an agent unprompted and does nothing anywhere else, so where it may appear depends on the file:
| File | Rule |
|---|---|
Claude Code .md (project/user scope) |
Allowed. Add it only where the runtime should delegate without the user naming the agent — an agent invoked by name does not need it, and it costs activations elsewhere when added by reflex. |
Copilot .agent.md (project/user scope) |
Never. Inert there, and KyberforgeCopilot.ProactivePhrase grades it a hard FAIL. |
Vendor-neutral .apm/agents/<name>.agent.md (plugin/APM scope) |
Never. Same Vale rule, same hard FAIL — the file matches the **/*.agent.md glob, and it compiles to a real Copilot agent downstream. |
A pair whose Claude Code half carries the phrase and whose Copilot half omits it is correct, not
inconsistent: agent-audit checks that both halves describe the same job, not that they match
word for word.
Indirect triggers ("even if the user doesn't say X") take a similar conditional at every scope: add one only where the user's natural phrasing genuinely omits the domain word.
Boundary targets must resolve, and the notation decides how hard the gate bites. Route
notation — /name, or any arrow form (-> name, -> `name`) — is checked
unconditionally: an unresolved target there is a blocking ERROR. The prose form ("do not use
for X, use y instead") is only a SUGGESTION by default, because a bare hyphenated word in a
boundary clause is as likely to be a tool, a file format or an English compound as a route. It
is promoted to a blocking ERROR only when a second target in the same sentence does resolve,
which corroborates that the name was meant as a route. So a typo does not dangle equally
either way — write the arrow when you want the target checked. Targets resolve against a universe
built by walking up from the agent file itself: the nearest ancestor holding
plugins/*/.apm/{skills,agents} (or, failing that, the nearest ancestor holding .git) contributes
every skill and agent under <root>/plugins/*/, plus the agent's own apm package and the packages
that package declares in apm.yml under dependencies.apm. A sibling plugin in the same monorepo
therefore resolves; a skill in an unrelated repo does not. A target outside that universe sends the
router nowhere — a blocking failure in arrow or /name form, and in prose form only a SUGGESTION
nobody is forced to act on, which is the worse outcome because it ships. Verify it before writing
it — do not invent a plausible sibling.
Never let a hyphenated routing target wrap across lines in a folded > scalar. YAML folding
replaces the newline with a space, so gitea-labels- at the end of one line and milestones at
the start of the next fold into gitea-labels- milestones. The gate then reads the target as
gitea-labels, finds no such skill, and reports it dangling — nothing in the source lines looks
wrong. Reflow so the whole name sits on one line. The same applies to any backticked skill or
agent name anywhere in a description.
That universe is the apm marketplace and stops there. A host built-in is not a routing target:
/compact, /clear and /init are Claude Code slash commands with no counterpart in Copilot CLI
or Codex, and .apm/ source compiles for all three, so routing to one is a portability defect. The
gate is right to fail it and there is no allowlist. If a built-in genuinely needs mentioning, write
it un-slashed — the `compact` built-in — which makes no routing claim and is not checked.
Length. 250 characters SUGGESTION, 400 characters FAIL, counting the frontmatter value only with YAML folding resolved. Treat 250 as the target: the SUGGESTION tier is what moves the corpus average, the FAIL tier only stops outliers.
Body
Write the body as a direct role instruction, addressed to the agent:
You are a <role>. When invoked, <primary action>.
## Inputs
<what the agent is given: files, context, parameters>
## Process
<ordered steps; be explicit where ordering matters>
## Output
<what it produces: format, location, structure>
## Errors
<what to do on malformed, missing or contradictory input: report and stop, or
which fallback to take — and what to say to the caller either way>
Four required elements: inputs expected, process steps, output format, error handling. The last is the one that gets dropped, and dropping it is not neutral: an agent given a malformed input and no instruction invents a recovery, and a subagent's invented recovery is invisible to the caller until the output is wrong. Say explicitly whether the agent stops and reports, or degrades to a named fallback.
One job per agent. An agent covering two jobs gets delegated to for the wrong one.
Delegation discipline replaces the word gate. A plugin/APM agent is a single file with no
sibling references/ directory: it cannot disclose progressively to itself, so its only way to
stay short is to invoke rather than restate. A body that transcribes a procedure a skill it
can invoke already owns is an agent-audit FAIL, and the fix is one line — "invoke <skill>".
- Restating: "To commit, check the message against Conventional Commits: type, scope, description; header under 100 chars; …"
- Delegating: "Author commits with
git-commits."
The same holds for a procedure another agent owns. What belongs in the body is what no invocable skill covers: the agent's role, its boundaries, the order it works in, and the format it returns.
State a read-only boundary in prose, not only in frontmatter. disallowedTools denies the
tools it names and nothing else — never Bash, which an agent with no tools field inherits — so
an agent fenced only in frontmatter can still write through a shell redirect.
Invocation axis
Decide before writing the description whether the agent is model-delegated (the runtime picks it)
or reached only by name (@agent-<name>).
Only Copilot's cloud/IDE format expresses that in frontmatter: disable-model-invocation: true
requires explicit invocation, and user-invocable: false hides an agent from manual invocation.
Both live in .github/copilot/agents/<name>.md and are inert in the CLI format. Claude Code has
no equivalent field, and neither does the vendor-neutral plugin/APM file, so at those scopes a
name-invoked agent still needs a description precise enough not to steal delegations — the
boundary clause is doing that work.
One gate, two measurements
| Gate | SUGGESTION | FAIL | Counts |
|---|---|---|---|
| description | 250 chars | 400 chars | the description: value only |
| body (Copilot limit) | 30,000 chars | — | the body only; content past it is truncated silently |
The 30,000-character Copilot ceiling is a runtime truncation limit, not a quality target, and it applies to a plugin/APM file too — that file compiles into a real Copilot agent downstream. An agent body long enough to approach it has a delegation defect, not a length problem.