Fix a Skill That Won't Trigger

You wrote a skill, you make a request it should catch, and the response comes back generic: no announcement, none of the skill's rules applied. Work this list top to bottom; each step isolates one failure mode, and the order matters because the early checks are the cheap ones.

1. Confirm the skill is visible at all

Ask directly: "what skills do you have available?" If yours is not in the list, triggering was never the problem: the file is in the wrong place, the frontmatter is malformed, or the session started before the skill existed. Check the path, check the YAML (three dashes above and below, valid name and description keys), and start a fresh session so the catalog is rebuilt.

2. Invoke it explicitly as a control

> Use the release-line skill on this note:
> "fixed the race condition in submitLead()"

Naming the skill bypasses intent-matching. If the explicit call works but natural phrasing does not, you have proven the body is fine and isolated the fault to the description. That is the most common case, and it is the next two checks.

3. Check the description for the words users actually say

• Too abstract: "Use for release-line formatting" matches almost nothing. Name the situation: "Use when turning a rough changelog note or commit message into a user-facing release-notes line."
• Missing vocabulary: if you say "changelog note" but the description only says "release line," the match is weaker than it should be. Include the synonyms real requests use.
• Buried trigger: lead with "Use when…". The matching surface should open with the situation, not with background.

4. Look for a look-alike skill stealing the match

If a neighboring skill covers similar ground, requests may route there instead. Add an explicit boundary to both descriptions, "Do NOT use for X (use <other-skill>)", so the border is stated rather than guessed.

5. Re-test with three phrasings

After each description change, test three different natural phrasings of the same request in a fresh session. One success can be luck; three phrasings routing correctly is a working trigger.