Vol. X · Field Operations · X.2
Writing Skills That Trigger
A skill that does not trigger is documentation nobody opened. The description is a search query the model will match against the user's request. Write it as if under-triggering were the only bug — because it is.
8 min read
anthropics/skillsaddyosmani/agent-skillsopenai/skillsmuratcankoylan/Agent-Skills-for-Context-Engineering
Doctrine
- Frontmatter description: what it does and when to use it, with concrete trigger contexts. Pushy beats polite.
- Body under ~500 lines, imperative, with a why. scripts/ for deterministic work. references/ for depth.
- One skill, one job. Overlap makes the model pick none.
Author like a search engineer
Anthropic's spec, Addy Osmani's engineering pack, and OpenAI's skills catalog agree: the description is always in context and must earn the load. Include synonyms the user will say. Include the negative ('not for CSS-only tweaks'). Then write the body as a playbook, not a blog post.
If a skill keeps failing to fire, the description is wrong. If it fires and rambles, the body is wrong. Distill from traces (see Distill Traces into Skills) rather than inventing more prose.
Anti-patterns
- Descriptions that only name a domain ('frontend') without situations.
- ALWAYS/NEVER wallpaper that the model learns to skip.
- Skills that duplicate the constitution.