Skills authoring patterns
A skill is only as good as its trigger. Write one badly and it either never fires (dead weight) or fires on the wrong task and derails it (worse than no skill at all). This deep dive is the authoring craft: structure, scope, and testing.
Anatomy of a skill file
--- name: weekly-client-report description: > Use this when asked to prepare or draft a weekly client status report. Triggers on phrases like "weekly report", "client update", or "status for [client]". --- # Weekly client report 1. Pull this week's closed tickets and open blockers for the named client (use the `list_tickets` tool, filter by client and date range). 2. Summarise in three sections: Shipped, In progress, Blocked. 3. Flag anything blocked for more than 5 days with @mention to the owner. 4. Use the template in `template.md` in this folder - do not invent a new format. 5. Keep it under 200 words. Clients skim; do not make them read a novel.
Three things the frontmatter has to nail
- Name - short, specific, greppable. Not "reports", but "weekly-client-report".
- Description - written as *when to use this*, in the vocabulary a real request would use, not as a summary of what the skill contains. This is the only text deciding whether the skill loads at all.
- Trigger phrases - if you know the actual words people use to ask for this ("status for Northwind", "weekly update"), put them in the description verbatim.
Scope: one job per skill
Too broad
A "client-communication" skill covering reports, emails, escalations, and onboarding in one file the agent has to parse every time.
Right-sized
Four separate skills, each triggered by its own specific description, each short enough to read in ten seconds.
Package what the instructions reference
If step 4 says "use the template in `template.md`", that file needs to actually be in the skill folder. Skills can bundle scripts too. A `validate_report.py` the agent runs, rather than re-deriving validation logic from prose every time, is faster and more reliable than instructions alone.
Testing a skill like you would test code
- 1
Positive trigger test
Ask for the task using words a real user would use. Confirm the skill actually loads (check the agent's tool/skill trace, do not just trust the output looked right).
- 2
Negative trigger test
Ask for an adjacent-but-different task. Confirm the skill does *not* fire and derail it.
- 3
Degradation test
Temporarily disable the skill and run the same task. If the output barely changes, the skill is not adding enough value to justify its upkeep.
Versioning and upkeep
Treat skill files like code: commit them, review changes, and revisit a skill the moment it misfires in production, the same way you would patch a bug. A stale skill that no longer matches how the underlying tool or process works is worse than having no skill, because it is trusted output that is quietly wrong.
Watch out
Common mistakes
- A description written as a summary ("handles reports") instead of a trigger condition ("use when asked for a weekly client report").
- One mega-skill covering five unrelated jobs.
- Referencing a template or script that is not actually bundled in the skill folder.
- Never testing the negative case, so the skill silently hijacks unrelated tasks.