holocron/docs/adr/0020-skill-description-and-body-context-contract.md

# Skills and agents are authored against a context budget, not a spec ceiling

Every installed skill's `name` and `description` sits in every agent's context from the first token
of every session, whether or not the skill is ever invoked. Across this repo's 39 skills that is
23,612 characters — roughly 6,200 tokens — and the authoring rules that produced it optimised for
triggering reliability with no counter-pressure on size. This ADR sets the budget, the shape, and the
gates that hold them.

**Status: accepted (2026-08-14).**

## Context

Measured before any change:

| | |
|---|---|
| 39 skill `name` + `description` | 23,612 chars, ~6,200 tokens, **preloaded every session** |
| 4 agent `name` + `description` | 1,325 chars, ~350 tokens, preloaded every session |
| skill bodies | median 684 words, mean 815, p90 1,349 |
| `MAX_WORDS` gate (`skill-audit/scripts/validate.sh:147`) | **2,770** — 2× p90 |

Three findings drove this, none of which is "the descriptions drifted".

**The rules mandate the bloat.** `skill-author/SKILL.md:104` requires indirect triggers ("even if the
user doesn't mention X explicitly") and `skill-audit/references/description-quality.md:21` requires
authors to "err toward being pushy". Both are enforced. The one rule that would delete the waste —
`skill-author/SKILL.md:102`, "not the skill's internal mechanics" — is judgment-only and is absent
from the FAIL conditions at `description-quality.md:45-50`. The enforced rules inflate; the deflating
rule does not bite. The result is measurable: `gitea-files` spends 147 chars listing six verbs, then
301 chars re-quoting the same six as user phrasings, in the same order. `apm-workflow` does the same
with six capability clusters. Across the twelve longest descriptions, 30.7% is capability
enumeration and 11.6% is composition or implementation detail that cannot affect a routing decision.

**Capability enumeration in a description is a correctness hazard, not only a token cost.**
`docs/research/examples/skill-write/writing-skills/SKILL.md:154-158` reports a measured failure: "when
a description summarizes the skill's workflow, an agent may follow the description instead of reading
the full skill content. A description saying 'code review between tasks' caused an agent to do ONE
review, even though the skill's flowchart clearly showed TWO reviews." `git-commits` is exactly that
shape — 74% of its description is capability enumeration, including a rules table (`header max 100
chars, lowercase subject, no trailing periods, 11 standard types`) an agent can act on without ever
loading the body.

**The upstream sources cannot settle this.** The four skill-writing references under
`docs/research/examples/skill-write/` disagree on what a description contains — when-only
(`writing-skills/SKILL.md:99`), what-and-when (`skill-creator/SKILL.md:67`,
`anthropic-best-practices.md:187`), triggers-only (`writing-great-skills/SKILL.md:28`), and
what-plus-when-plus-negative (`write-skill/SKILL-TEMPLATE.md:5-6`). `writing-skills` and the Anthropic
document it bundles contradict each other inside one skill directory. They also disagree on whether
500 lines is binding, on the inline-versus-bundle threshold, and on the TOC threshold (>100 lines vs
>300 lines). "Grounded in the research" is therefore not available as a tiebreaker; a house choice is
required and this is it.

A fourth observation shaped the body half. The best progressive-disclosure ratio in the repo belongs
to `apm-workflow` — a 554-word body dispatching to 3,006 words of references — and the worst two
belong to the skills that define the house standard: `skill-author` (2,760 body / 1,247 references)
and `agent-author` (2,758 / 1,664). Both sit within twelve words of the 2,770 gate their own plugin
enforces. A ceiling that nothing approaches is not a constraint; a ceiling that two files have grown
into is a target.

## Decision

### Descriptions

A description carries three things and nothing else: a **trigger clause**, at most one **capability
clause**, and a **boundary clause**. Capability enumeration, output-format detail, composition notes
("composes X rather than duplicating Y"), and implementation detail move to the body or to
`README.md`.

- **250 characters SUGGESTION, 400 FAIL.** The agentskills.io 1,024-character limit remains as an
  unchanged spec backstop. The SUGGESTION tier is what moves the average; the FAIL tier only stops
  outliers.
- **Boundary clauses compress** to `Not <thing> → <skill-name>.` and must name a target that
  resolves to a real skill under `plugins/*/.apm/skills/`. This is checked deterministically.
- **The blanket pushiness rules are deleted.** `skill-author/SKILL.md:104` and
  `description-quality.md:21` are replaced by a conditional: add an indirect trigger only where the
  user's natural phrasing genuinely omits the domain word — true for the `gitea-*` family, false for
  `git-commits`. Stating the same trigger twice in two registers is a FAIL.

### Bodies

The body carries the **decision procedure only**: ordered steps, decision branches, gates, and which
reference to load when. Lookup tables, spec restatements, output schemas, templates, and rationale
prose move to `references/` behind an explicit "read X when Y" trigger.

- **600 words SUGGESTION, 900 FAIL.** The 2,770-word / 500-line spec backstop is unchanged and keeps
  its existing meaning: conformance, not quality. These are two different gates measuring two
  different things, and conflating them is what produced the current state.
- **Dispatch is mandatory at two or more mutually exclusive flows.** The body carries the dispatch
  table and the gates that apply to every branch; each flow lives in its own self-contained
  `references/` file. This is `apm-workflow/SKILL.md:33-41` promoted from accident to rule.
- **Gotchas are constrained.** A Gotcha must state a fact that contradicts a reasonable default —
  something the agent gets wrong by acting sensibly. Maximum five entries. A Gotcha that paraphrases
  a step in the body below it is a FAIL. A Gotchas section exceeding 25% of the body is a
  SUGGESTION.

### Agents

Agents take the same description gates — they are preloaded identically — and **no body word gate**.
A skill body is loaded into the caller's context, competing with the live conversation; an agent body
becomes the system prompt of a fresh context. The rationale for the 900-word FAIL does not transfer.

A plugin-scope agent is a single file with no sibling `references/` directory, so it cannot disclose
to itself — it can only delegate to skills. `agent-audit` therefore gains a **delegation check**: an
agent body that restates a procedure owned by a skill it can invoke is a FAIL, with the fix being
"invoke `<skill>` instead". Length falls out of delegation rather than being gated directly.

### Invocation as a design axis

`skill-author` asks whether a skill is model-invoked or hand-invoked before writing a description. A
hand-invoked skill sets `disable-model-invocation: true` and carries one plain human-facing sentence
with no trigger list.

Verified end-to-end rather than assumed: `plugins/bin/.apm/skills/zoom-out/SKILL.md:4` carries the
flag, apm passes it through verbatim to both `.claude/skills/zoom-out/SKILL.md:4` and the flat mirror
at `plugins/bin/skills/zoom-out/SKILL.md:4`, and `zoom-out` is the one installed skill absent from
the model-visible skill listing in a live session. It remains invocable as `/zoom-out`.

### Merging siblings

Two skills that share substantial content, name each other as near-misses, and differ only in the
type of input they take should be **one skill with a dispatch table**. This catches `skill-audit` +
`agent-audit` and is scoped to them; the author pair is explicitly excluded, because
`skill-author` and `agent-author` emit genuinely different artifacts (a skill directory versus a
one-or-two-file agent pair, per ADR-0005 and ADR-0016) and their overlap is in the improve flow
rather than the core job.

### Enforcement and rollout

Gates land where the existing gates already live — no new layer:

| Check | Home |
|---|---|
| description and body counts, resolvable boundary targets | `skill-audit/scripts/validate.sh`, `scripts/skill-size-check.sh` |
| prose patterns (composition-note openers, restatement) | `plugins/kyberforge/.apm/skills/*/assets/vale/styles/Kyberforge/` |
| judgment calls | `references/description-quality.md`, `references/body-discipline.md` |

**Blocking immediately, with no baseline file.**

Three pre-existing contradictions are fixed in the same change, because they are the contract:

- `skill-audit/SKILL.md:58` asks whether the description opens with an action verb ("Audits…",
  "Reviews…") while `:101` and `DescriptionOpener.yml` require an imperative "Use when…" opener. The
  criterion is unsatisfiable against the house's own skills, both of which open with "Use when".
- `DescriptionOpener.yml`'s regex is anchored to `^This (skill|agent)\b`, so `gitea-workflow` ("This
  is the human-facing entry point…") and `gitea-labels-milestones` ("This is a cross-cutting shared
  skill…") both violate the rule and pass the linter.
- `description-quality.md:45-50` has no FAIL condition for internal-mechanics content, which is why
  `skill-author/SKILL.md:102` never bit.

## Consequences

**Editing any non-compliant skill now requires retrofitting it first.** 30 of 39 descriptions exceed
400 characters and 14 of 39 bodies exceed 900 words. With the gate hot and no baseline, a one-line
fix to `gitea-prs` cannot be committed until that skill meets the contract. This is deliberate — it
guarantees convergence and avoids a half-state — but it means the retrofit is lazy and *mandatory*
rather than deferred. The follow-up retrofit issue should be prioritised accordingly, and the risk it
carries is the ordinary one for hot gates: a gate expensive enough to be inconvenient gets bypassed
with `SKIP=` and loses its authority.

**A ceiling does not produce an average.** If every author writes to the 400-character FAIL, the
preload lands at 15,600 chars — a 34% cut, not the ~50% intended. The halving depends entirely on the
250-character SUGGESTION tier being visible and respected. That tier works here in a way it does not
elsewhere in this repo: `skill-audit` already reports `PASS (N suggestions)` as a first-class
outcome. This is explicitly **not** the failure ADR-0013 records — Vale warnings are invisible
because vale's exit code keys on `error` alone, but these gates live in `validate.sh` and
`skill-audit`, where a SUGGESTION reaches the report. Realistic landing is 34-55% down, not a
guaranteed 50%.

**A word gate cannot detect the defect it is standing in for.** `git-commits` carries thirteen
Gotchas of which four restate steps in its own Workflow (`:32` ≡ step 9, `:33` ≡ step 9, `:36` ≡ step
2, `:31` ≡ the description) — 1,217 words that pass any plausible gate. The counts are a backstop to
the dispatch rule and the Gotchas constraint, not a substitute for them, and should not be read as
the mechanism.

**Some skills legitimately need more description budget than others.** A tiered limit keyed to
sibling density was considered and rejected as too clever; the flat 250/400 pair means the `gitea-*`
and `git-*` families — where every sibling shares a keyword and boundary clauses do real routing work
— are the ones most likely to sit at the FAIL tier permanently. If the retrofit shows that family
routing degrades, the tier is the first thing to revisit.

**Four broken routing targets are live and are not fixed here.** `skill-audit` routes to
`/skill-improve` twice in its description plus `README.md:10`, and no such skill exists — the real
target is `skill-author`. `research` routes to `neuledge-context`, which exists only inside that
string. `agent-author` says "Do not use for read-only review — examine agent files manually",
routing away from `agent-audit`, the correct sibling. `gitea-issues` contains the literal string
`gitea-labels- milestones`, a stray space introduced by YAML folding, breaking the skill name in
preloaded text. The resolvable-target check added here will fail on all four the moment those files
are touched; fixing them is split into its own issue.

**Duplication between `skill-author` and `agent-author` survives un-gated.** The merge rule
deliberately excludes the author pair, so the commit-verification argument in four near-copies, the
root-cause grouping rule in four copies, and the wholesale clone of the "Improving an existing X"
flow all remain. Cache isolation makes them structurally unavoidable
(`skill-audit/SKILL.md:95` forbids cross-skill references; `LESSONS.md:107` records why), so the
options are a sync gate or continued drift. This is an input to the kyberforge-bodies follow-up
issue, not a solved problem.

**Provenance frontmatter is explicitly out of scope.** `LESSONS.md:63` asserts that non-routing
frontmatter (`source_keys`, `category`, `version`) is loaded at agent startup, which would make the
7,352 characters of it across the corpus a third again on top of the description tax. Measured
against a live session on this Claude Code version, it is not: the model-visible skill listing
contains only `name` and `description`. That is host-observed rather than spec-guaranteed and says
nothing about Copilot CLI, but it is sufficient to establish that cutting `source_keys` would break
the ADR-0009 provenance machinery for no runtime gain. The metadata was added deliberately and stays.

## Alternatives considered

- **Keep pushiness, raise the budget to ~500 chars.** Undertriggering is the worse failure mode — a
  skill that never fires is worth nothing regardless of cost — and `skill-creator/SKILL.md:67`
  explicitly recommends being "pushy" against an observed undertriggering tendency. Rejected because
  that claim is an unmeasured assertion about an older model, and because the correctness hazard in
  `writing-skills:154-158` cuts the other way: a fat description is not merely expensive, it is a
  shortcut agents take instead of reading the body. Would have landed a 35% cut.
- **A trigger-eval loop to set lengths empirically.** `skill-creator/SKILL.md:337-404` specifies 20
  queries per skill, 8-10 positive and 8-10 near-miss, with a 60/40 train/test split selecting on
  test score. This is the rigorous answer and the repo has deliberately never built it. Rejected
  because it blocks the context cut behind a substantial new subsystem.
- **A repo-level aggregate preload budget** (≤12,000 chars across all skills, checked at pre-push).
  The only option that measures the actual goal rather than a proxy. Rejected because it makes one
  skill's edit fail on account of another skill's growth, and because it is meaningless for an
  external consumer installing a subset of the plugins.
- **500-word body FAIL, matching `writing-skills/SKILL.md:217-221`.** Best-grounded in upstream and
  would align this repo with the tightest source. Rejected because it fails 30 of 39 skills, and a
  blunt gate gets satisfied by deleting content rather than relocating it.
- **A shrinking baseline file** recording each non-compliant skill's current numbers, failing only on
  growth. Would have made the retrofit a visible burn-down instead of a wall. Rejected in favour of
  hot gates.
- **A sync gate over the duplicated spans** instead of a merge rule — generalising
  `scripts/check-vale-style-sync.sh` to cover shared prose so duplication persists but drift cannot.
  Rejected for the audit pair in favour of merging, which removes the duplication rather than
  policing it, and removes a mutually-excluding near-miss pair from the router at the same time. It
  remains the only available answer for the author pair.
- **Merging `skill-author` + `agent-author` as well**, taking kyberforge from seven skills to five.
  Largest cut available. Rejected because it reopens ADR-0005, ADR-0008 and ADR-0016 together, and a
  merged author skill would carry both the skill-directory scaffold and the dual-provider agent
  scaffold behind one dispatch.
- **Demoting Gotchas** to the end of the body or into `references/gotchas.md`, removing its
  position-based exemption from the dispatch rule. Maximum saving on the largest body construct
  (6,830 words, 21% of all body text). Rejected because a gotcha read after the mistake is worthless.