A meta-skill for creating and optimizing skills. Skills are modular, self-contained packages that transform Claude from a general-purpose assistant into a specialized Agent equipped with procedural knowledge.
Skill Structure
skill-name/
├── SKILL.md (必需) — YAML frontmatter + Markdown 指令
└── 可选资源
├── scripts/ - 可执行脚本（Python/Bash 等）
├── references/ - 按需加载的参考文档
├── examples/ - 完整可运行示例
└── assets/ - 输出中使用的资源文件
Three-level progressive disclosure:
| Level | Content | Load Timing | Size Limit |
|---|---|---|---|
| Metadata | name + description | Always in context | ~100 words |
| SKILL.md body | Core process and instructions | When the skill is triggered | <500 lines (ideal) |
| Bundled resources | scripts/references/assets | Loaded on demand | No limit |
Scripts can be executed without being read into context.
Creation Process
Step 1: Capture Intent
First extract from the current conversation history — if the user says "turn this process into a skill", don't start from scratch by asking questions; instead extract directly from the conversation history: which tools were used, what the step order was, what corrections the user made, what the input/output format was. Have the user confirm whether these extractions are accurate, then proceed to the next step.
If it's a brand-new requirement, collect the following information (ask only one most important question at a time):
- What task should this skill accomplish?
- What words will the user use to trigger it? (Collect exact phrases, including Chinese and English variants)
- What format is the expected output?
Proceed to the next step only after grasping the scope of functionality.
Step 2: Plan Resources
Analyze which content is suitable for bundled resources:
- scripts/ — code that gets written repeatedly, or operations that need deterministic reliability (if testing reveals that the same script has to be rewritten every time, it should go in here)
- references/ — detailed specifications, API documentation, complex decision trees (provide a table of contents when >300 lines)
- assets/ — static files used for output
Only create the directories that are actually needed.
Step 3: Write SKILL.md
Description — the core of the trigger mechanism
The Description determines when the skill is triggered. Use the third person and include the specific phrases the user will say:
# ✅ 正确
description: This skill should be used when the user asks to "create a hook",
"add a PreToolUse hook", or mentions hook events. 触发方式：/hooks、「加钩子」。
即使用户没说"hook"，只要他们想在工具调用前后自动执行某些操作，也应该触发本 skill。
DO NOT trigger for general Claude API questions.
# ❌ 错误（模糊，没有触发短语）
description: Provides hook guidance.
How to handle the two types of trigger problems:
- undertrigger(Under-triggering): list more trigger phrases, including Chinese and English variants, plus intent descriptions ("even if the user doesn't say X, as long as they want Y...")
- overtrigger(Mis-triggering): use "DO NOT trigger when..." to explicitly exclude scenarios
Body Writing Guidelines
Useimperative sentences, not the second person:
| ✅ Correct | ❌ Wrong |
|---|---|
| Read the configuration file | You need to read the configuration file |
| Use Grep to search | You can use Grep to search |
Explain the reason rather than issuing forced commands — LLMs understand "why" more effectively than memorizing "what to do". Avoid all-caps MUST/NEVER; instead explain the rationale:
| ✅ Explain the reason | ❌ Forced command |
|---|---|
| Read existing files first to avoid overwriting the user's existing work | NEVER create files directly |
| Fabricated scenarios tend to appear at the beginning, so it needs separate optimization | MUST run li-opening |
If it exceeds 500 lines, move the detailed content to references/, and explicitly reference it at the end of SKILL.md:
## 附加资源
- **`references/patterns.md`** - 常见模式和详细案例
- **`scripts/validate.sh`** - 验证脚本（按需执行，无需读入上下文）
Avoid information duplication: content should exist only in either SKILL.md or references/.
Step 4: Validation Checklist
Structure:
- SKILL.md has valid YAML frontmatter (including name and description)
- Referenced files actually exist
Description quality:
- Third-person format
- Includes specific trigger phrases (Chinese and English variants)
- Includes intent description ("even if X isn't said, as long as the user wants Y...")
- Has exclusion scenarios where it should not trigger
Content quality:
- Main body uses imperative sentences
- Explains reasons rather than issuing mandatory commands
- Moderate word count (ideally <500 lines)
- SKILL.md references all bundled resources
Step 5: Testing and Iteration
Create 2-3 real test cases (what users would actually say, not abstract descriptions):
{
"skill_name": "example-skill",
"evals": [
{
"id": 1,
"prompt": "用户会说的真实请求",
"expected_output": "预期结果描述"
}
]
}
Iteration loop:
- Run the test cases and record the actual output
- Read the transcript, not just the final output — identify ineffective instructions and duplicated work
- If multiple test cases independently wrote the same script, put it into
scripts/ - Improve the skill based on feedback, then test again
If triggering is inaccurate, generate a set of 20 trigger tests (8-10 that should trigger + 8-10 that should not), focusing on edge cases rather than obvious cases.
Improvement Principles
Generalize rather than overfit — Test cases are only samples; the skill must serve countless invocations. When encountering stubborn problems, try using a different metaphor or switching to another working mode, rather than stacking more restrictive instructions.
Keep it concise — Remove content that doesn't work. Read the transcript to identify which instructions caused the model to do ineffective work, and delete them.
Reusable scripts — If testing reveals that a certain piece of code (such as format conversion or data extraction) has to be rewritten every time, this is a strong signal: put it into scripts/, saving the repetitive work of each invocation.
Additional Resources
references/testing-guide.md- Test case format, assertion design, detailed methods for Description optimization