Step 1: Clarify what this Skill should teach
A good Skill does exactly one thing, and the "right way" to do that thing can be summarized.
- ✅ Good examples: "write an official-account article following our brand guidelines", "review front-end code for accessibility issues"
- ❌ Bad example: "help me with everything" (too broad — AI won't know when to use it)
Step 2: Write the SKILL.md
The standard structure looks like this (feel free to copy it):
---
name: weekly-report-writer
description: Turn scattered work notes into a well-structured weekly report. Use when the user says "write my weekly report" or pastes a jumble of work logs.
---
# Weekly report generation
1. Read the user's raw notes and first sort them by "results / problems / next-week plans"
2. Order results by importance; format each item as: one-sentence result + supporting data
3. Mark missing data with [TBD]; never fabricate
4. End with 2 suggested weekly report titles
## Example
User input: "Monday I had a meeting, Tuesday I fixed a bug, Wednesday I shipped a feature."
Output:
### This week's results
1. Completed shipping feature XX (data impact [TBD])
........
name
Lowercase kebab-case, unique identifier
description
Most critical: say clearly what it does + when to use it; AI relies on this to decide whether to activate
body
Concrete steps + examples + rules — the more specific, the better
Step 3: Optional enhancement folders
scripts/— executable scripts (Python, Bash, etc.) that AI calls on demandreferences/— reference materials/docs, loaded when neededassets/— static resources such as templates and samples
Step 4: Test and polish
- Try 3 different inputs and check whether the output matches expectations
- Add "places where AI misunderstood" into the body — Skills are refined iteratively
- Make description cover every trigger scenario you expect (users phrase things in countless ways)
- Study how top-scoring community Skills are written: see the curated list (the anthropics/skills official repo is an excellent model)
Common pitfalls
- description too vague → AI never knows when to trigger, so the Skill is wasted
- Vague steps (like "analyze carefully") → replace with verifiable, concrete actions
- Padded with large irrelevant passages → violates progressive loading and slows the agent
- Forgetting to define "when NOT to use it" → it gets force-applied to unsuitable scenarios