triggering-reliability
Installation
SKILL.md
Common mistakes that break triggering
This skill is the reference catalog of everything that makes Claude Code agents and skills fail to trigger. Every mistake below has been observed in real plugins. Treat this as a checklist before shipping any plugin, and as the first place to look when an existing plugin installed fine but nothing happens.
Quick triage: symptoms to likely cause
| Symptom | Most-likely cause |
|---|---|
| Skill directory exists but never loads | Missing YAML frontmatter (file starts with # not ---) |
| Agent file exists but cannot be invoked by name | Deprecated agent: true flag with no name: field |
| Agent rarely triggers despite obvious queries | Missing <example> blocks or abstract-capability description |
| Skill triggers inconsistently | Description describes WHAT it does, not WHEN to use it |
| Multiple skills fight over the same query | Trigger-phrase overlap between descriptions |
| Agent description matches generic unrelated queries | Windows/docs boilerplate inside YAML description: poisons routing |
| Agent uses wrong model | model: field missing or hard-coded instead of inherit |
Nine canonical anti-patterns (summary)
Full symptom / root cause / fix narrative for each lives in references/anti-patterns-catalog.md. Quick table: