Writing a Good Skill
Writing a skill is not enough on its own. It becomes useful only when it loads at the right moment and can be executed without ambiguity.
Cut at One Purpose
A skill that is too large forces unused procedure into context. One that is too small multiplies the number of skills and makes selection harder.
| Granularity | Example | Assessment |
|---|---|---|
| Too large | ”Everything about content operations” | Mixes in many unused steps |
| Appropriate | ”Create a new docs article” | Complete around one purpose |
| Too small | ”Write the title in the frontmatter” | Meaningless in isolation |
A useful gauge is a unit of work you could hand to a person as a request.
Lead With When to Use It
Most unused skills fail at the opening description, not in the steps. State what it does and, just as importantly, when it applies and when it does not.
Use when creating a new docs article under src/content/docs/.
Do not use for editing existing articles or for blog posts.Avoid Wording Without Criteria
Phrases like “appropriately” or “as needed” are read differently by different readers. Replace them with concrete conditions.
# Not decidable
Add links as needed
# Decidable
Add two to four links to related pages in the same section at the end of the bodyState Completion Conditions
Without a definition of done, work either stops halfway or expands beyond what was asked.
## Completion conditions
- Both the Japanese and English versions exist
- All required frontmatter fields are filled
- Every internal link points to an existing pageSeparate Procedure From Tooling
A skill carries judgment and procedure. Deterministic work is faster and more reliable implemented as a tool. A skill that narrates a long command sequence is a candidate for tooling.
Summary
- Cut skills at a unit of work you could hand to a person
- Lead with when the skill applies and when it does not
- Replace criteria-free wording with concrete conditions
- State completion conditions to prevent stopping short and overreaching