Skill Description Trigger Authoring

A skill's description is its activation surface: it is matched against the task at hand by a reader who does not yet know the method. A description that summarizes content instead of naming the firing situation produces a skill that is technically available and practically never loaded.

When to use

• Authoring or revising the description: frontmatter of any skill.
• A postmortem shows a task where an existing skill should have fired and didn't.
• Two adjacent skills keep being confused for each other.

Inputs

• The moments in real workflows when the skill must load ("about to emit complete", "about to implement against a foreign schema").
• Real past tasks: several where the skill should have fired, several adjacent ones where it should not.

Steps

1. Enumerate the firing situations: what is the practitioner doing or about to do when this skill must load? Situations, not topics — "about to claim done", not "quality assurance".
2. Write from the reader's pre-skill state. They can recognize their situation; they cannot recognize the method's vocabulary. "Use when about to X" beats "a methodology for X-ing".
3. Front-load the trigger. Descriptions are scanned under time pressure; the first clause decides whether the rest is read.
4. Include the concrete cue words and symptoms as they appear in real tasks — the phrases in packets, the moment in the workflow, the observable temptation ("it should work"). Matching happens against the task's own language.
5. Add anti-triggers where siblings overlap: when NOT to use this skill, and which sibling handles that case. Disambiguation in the description is cheaper than a wrong load.
6. Keep it to one or two sentences. A trigger buried in a paragraph fires never; completeness belongs in the body's When-to-use, not the description.
7. Replay-test: take three real past tasks where the skill should have fired and two adjacent ones where it shouldn't. Reading the description alone — no body — check it routes all five correctly. A miss is a description bug; fix the description, not the tasks.

Outputs

• A one-to-two-sentence description whose first clause names the firing situation, containing real cue language, and disambiguated from siblings.
• A recorded replay-test result.

Failure modes

• Summary-not-trigger — "Guidance on verification best practices": describes the content, names no moment, never fires.
• Method leakage — the description teaches steps instead of naming situations, wasting its only job on content the body already carries.
• Over-broad trigger — fires on everything, reader learns to ignore it; a trigger that always matches carries no information.
• Post-skill vocabulary — jargon the method itself introduces; the pre-skill reader can't match terms they haven't learned yet.
• Missing anti-trigger — two siblings with overlapping triggers, so the wrong one loads and both lose trust.

Worked example

Bad: description: Describes the verification methodology for completed work. — a summary; no practitioner mid-task self-identifies as "needing verification methodology". Good: description: Use when about to claim work is complete, fixed, or passing — run the check that would falsify each claim and read its output before emitting the claim. The first clause names the exact workflow moment (emitting a completion claim); "complete, fixed, or passing" are the literal words that appear in the task's own language; the em-dash clause states the obligation compactly without teaching the method. Replay-test: fires on "flip the registry rows and confirm validators green" (should), fires on "report the fix upstream" (should), stays silent on "estimate the refactor scope" (correctly — that's scope-decomposition's trigger).

Acceptance

• The replay test routes all sampled tasks correctly from the description alone.
• The first clause states a situation the pre-skill reader can recognize.
• Length is at most two sentences; cue phrases are real task language, not method jargon.
• Overlapping siblings are explicitly disambiguated.