## Trigger

About to author or edit a card (`ai/cards/<id>.md`) or a Skill (`SKILL.md`):
choosing its `description`/registry `summary`, deciding what goes in the body
vs stays out, or judging whether it will trigger and what it costs to keep
around.

## Why (the empirical anchor)

Context is a finite **attention budget**; it degrades **non-uniformly** as it
fills (Anthropic, *Effective context engineering*). Two robust effects:

- **Context rot** (Chroma, 18 models): recall drops as input grows — *all*
  models, gradient not cliff. Focused ~300-token prompts beat ~113k-token full
  prompts across families.
- **Lost-in-the-middle** (Liu et al., TACL 2024): U-shaped — beginning AND end
  strong, **middle drops 20–30 pts**, even in long-context models.

So: front-load only lightweight discovery metadata, load detail on demand.

## Fix

**A. The trigger surface = the one field that decides selection.**
For a Skill it's `description`; for a card it's the registry `summary`
(+ `title` + `tags`). It is the *only* thing a loading agent sees before
deciding to open the body.

| Rule | Why |
|---|---|
| State **what it does + when to load it** | selection is made from this alone |
| **Third person**, ≤1024 chars | injected into system prompt; POV drift hurts discovery |
| Use concrete trigger keywords (error strings, symptoms, tool names) | that's what a future query matches |
| Give the rule **gist**, NOT the step-by-step fix/workflow | a workflow-summary becomes a shortcut the agent follows *instead of* reading + verifying the body (CSO trap) |

**B. Token budget = 3-level progressive disclosure.**

| Level | Content | In context | Cost |
|---|---|---|---|
| L1 | `name`+`description` / registry summary | **always** | ~80–100 tok each — the real resting cost |
| L2 | body / `SKILL.md` | on trigger | keep dense; SKILL.md target <500 lines |
| L3 | bundled files/scripts | on read/exec | 0 until read |

Resting cost ≈ **N × summary length**, not N. Tighten each summary; body size
is nearly free because it loads on demand.

**C. Body density + ordering.**
- Write for machines: bullets / tables / key-value; no ceremonial prose; one
  excellent example, not many; consistent terminology; no time-sensitive lines.
- Put `## Trigger` at the top and `## Reuse Rule` at the bottom — the U-shape's
  strong ends. Don't bury the load/apply decision mid-body.
- One card/skill open at a time; references one level deep.

**D. Two myths — refuted in verification, don't follow.**
- ✗ "Front-load critical info at the very start." U-shape means **both ends**
  work; pure front-loading is unsupported. Real rule: *don't bury it in the
  middle*.
- ✗ "Decay is caused by n² pairwise attention." The effect is real; that tidy
  mechanism did **not** survive verification — don't cite it.

Applies equally to Skill `description`s. The goal — a card decidable from its
registry entry alone — is the consult-side counterpart of this authoring rule;
for the CI/format traps when this lands as a real `SKILL.md`, see
`agent-skills-validator-gotchas`.

## Reuse Rule

- **Load when**: writing or revising a card/skill — its summary/description,
  its body scope, or its token footprint; reviewing existing summaries for
  trigger accuracy.
- **Do not load when**: consulting/applying an existing card (that's the
  consult loop), or doing non-asset work.