Design useful skills, not skills nobody uses.
Ask three questions first (Drucker filter)
Before starting, answer:
Without this skill, would the result get worse? If not, don't build it.
Will this skill be used more than 5 times? One-off tasks don't need a skill.
Can't Claude answer this question directly? If it can answer directly, no skill is needed.
Only proceed once all three questions pass.
The three-layer structure of a Skill
Level 1（YAML frontmatter）：触发机制，始终加载
Level 2（SKILL.md body）：执行指令，触发时加载，控制在 500 行以内
Level 3（references/）：深度参考，按需读取
The most important thing is Level 1. If the description is poorly written, the skill will never trigger.
How to write the Description
The description determines when the skill loads. How to write it:
description: |
[一句话说清楚这个 skill 做什么]
Use when:
- 「[触发词1]」
- 「[触发词2]」
（至少10个，覆盖精确表达和模糊表达）
Use for:
- [具体场景1]
- [具体场景2]
Use other skills for:
- [相邻场景] → [用哪个 skill]
After writing, test: list 10 queries (5 that should trigger, 5 that shouldn't) and confirm accuracy exceeds 90%.
How to write the Skill Body
Examples are 10 times more effective than rules. Write examples first, then rules.
## 示例
输入：[真实的用户请求，要具体，带背景]
输出：[理想的响应]
Three criteria for a good example: specific (real scenarios), realistic (users would really say this), edge (covers easily confused cases).
Iteration loop
草稿 → 测试3个案例 → 用户看输出 → 改进 → 重复
Goal of each iteration: increase the skill's pass rate on test cases by 20%.
Three test cases: ideal input (happy path), boundary input (edge case), near input (near-miss, easy to trigger but should not trigger).
Common problems
| Problem | Symptom | Fix |
|---|---|---|
| Trigger too broad | Irrelevant requests also trigger | Narrow the description, add "Use other skills for" |
| Trigger too narrow | Obviously should trigger but doesn't | Add trigger words, cover ambiguous expressions |
| Wrong output format | Messy structure | Add a specific output template or examples |
| Trying to do everything | Skill keeps growing | Split it, each skill does only one thing |
Division of labor with skill-org
skill-org is responsible for starting from the purpose, designing the complete organizational structure and JDs, then compiling the JDs into skill files.
skill-designer is responsible for quickly assessing and iterating existing skills, focusing on trigger precision and output quality.
If you have an existing skill that needs improvement, use this. To design an Agent division-of-labor system from scratch, use skill-org.