Skill description writer

Skill Description Writer

Crafts the description field that determines whether a skill is ever selected. A weak description means the skill never fires; an overloaded one fires on the wrong tasks. This is the highest-leverage line in any skill: the body only matters if the description gets it loaded.

Inputs to collect

1. What the skill produces (its deliverable, one sentence).
2. Three or more phrases a real user would type when they need it - in the user's words, not the author's.
3. The nearest neighbor skills a request could confuse it with.

If the author cannot supply real user phrasing, derive candidates from the body's deliverable and triggers, and mark them for validation with skill-tester.

The three-part formula

Every description contains these parts, in this order:

1. WHAT - one tight sentence naming the capability in active third person: "Generates a zero-downtime database migration plan."
2. WHEN - concrete trigger conditions, quoting real user phrasing where possible: "Use when adding columns, altering types, dropping tables, or backfilling data on a live schema" or "Triggers on 'is this term sheet fair', 'liquidation preference', 'board seats'."
3. NOT - negative scope routing to the named neighbor, whenever a plausible confusion exists: "Do NOT use for offline schema redesign - use database-schema instead."

For skills with strong, distinctive triggers, WHEN may lead ("Use when…") and WHAT follows - the order that disambiguates fastest wins. The NOT clause is mandatory when a neighbor exists and omitted only when nothing could plausibly collide.

Trigger term density

Pack the WHEN clause with the exact nouns, verbs, and phrases users type. Think: what would someone say the moment they need this? Include synonyms for the same action ("negotiate", "counter", "push back on"). Concrete verbs beat abstract nouns: "adding, altering, debugging" fires; "enhancement, improvement" never does.

Length and formatting

• Frontmatter description: 1024 chars max. Simple skills land at 150-300 chars; skills with many trigger phrases and a NOT clause legitimately run 400-700.
• Catalog card/summary field: 200 chars max - WHAT plus the strongest trigger only.
• Third person, active voice throughout ("Generates", "Reviews" - never "I will" or "Helps you").
• No backticks or markdown inside the value; no trailing period issues in YAML; no dates or versions.

Good / bad

Good: "Reviews a diff for correctness, security, and regression risk. Use before opening a PR, after writing a non-trivial change, or when asked to 'review this code'. Do NOT use for style-only formatting passes." Bad: "A helpful skill for reviewing things when you want feedback." - no trigger, no scope, vague qualifier.

Good: leads with the output - "Produces a cited research report…" Bad: leads with the method - "Uses web searches to gather information…"

Deliverable

The rewritten description string (frontmatter version, plus the 200-char catalog version when asked), with a one-line note naming which trigger phrases were added and which neighbor the NOT clause routes to.

Do NOT

• Do not stuff triggers the skill cannot serve - over-broad descriptions cause misfires, which cost more trust than silence.
• Do not describe the skill's internal method; describe the user's moment of need and the output.
• Do not use vague qualifiers ("helpful", "useful", "powerful", "better").
• Do not omit the NOT clause when a named neighbor exists; collisions are territory defects, and the description is where they are fixed.

Quality bar

Done when: WHAT, WHEN, and (where a neighbor exists) NOT are all present; at least three concrete trigger phrases appear in the user's own words; a router reading only this description would fire it on the right request and stay silent on the nearest wrong one.