一、Skill 是什么？
Skill 是一个可复用的触发式工作流程参考文档，帮助 AI 在特定场景下找到正确的处理方法。
Skill 适合的场景：
- 可复用的技巧、模式、工具方法
- 不是"一次性的问题解决方案"
- 不是项目专属的约定（那些放 CLAUDE.md）
二、目录结构
原则：尽量扁平，只在必要时拆分文件。
三、SKILL.md 结构
四、Frontmatter（YAML 头部）⚠️ 关键
---
name: my-skill-name # 只能有字母、数字、连字符
description: "Use when ..." # 必需，引号包裹
---注意事项：
- name 只能用 字母、数字、连字符（不能有括号、特殊字符）
- description 必须以 "Use when..." 开头
- description 只写触发条件，不写工作流程！
- 最大 1024 字符
❌ 错误示例：
description: "Use for TDD - write test first, watch it fail, write code"
# 问题：描述了工作流程，会导致AI跳过正文
✅ 正确示例：
description: "Use when implementing any feature or bugfix, before writing implementation code"
# 只说触发条件，不说怎么做
五、description 写作规范（最重要）
| 规则 | 说明 |
|---|---|
| 以 "Use when" 开头 | 明确触发条件 |
| 只写触发场景 | 不写技能的工作流程 |
| 用第三人称 | "Use when..." 而不是 "I can help when..." |
| 包含关键词 | 加入 AI 可能搜索的错误信息、症状、工具名 |
| 描述问题而非语言 | "race condition" 而非 "setTimeout" |
六、正文章节写作规范
| 内容 | 写法 |
|---|---|
| Overview | 1-2句话核心原则 |
| When to Use | 症状/场景 bullet 列表 |
| Core Pattern | 技巧步骤或代码模式 |
| Quick Reference | 表格/bullet 快速查阅 |
| Common Mistakes | 错误+修复方法 |
不要做的事：
- ❌ 叙事性故事（"2025年10月3日我们发现..."）
- ❌ 多语言示例（JS/Python/Go 都写 = 质量稀释）
- ❌ 通用标签（step1, helper2 - 要有语义）
- ❌ 代码塞进流程图
七、TDD原则（铁律）⚠️
没有测试就没有 Skill！
| 阶段 | 动作 |
|---|---|
| RED | 先跑一个 subagent 不带 skill，看它怎么失败 |
| GREEN | 写 skill 解决那些失败问题 |
| REFACTOR | 堵住 loophole，重新测试 |
Rationalization 表格要提前写好：
| 借口 | 现实 |
|---|---|
| "太简单不需要测试" | 简单代码也会挂，测试只要30秒 |
| "我手动测过了" | 手动测试≠正确测试 |
| "测完再写效果一样" | 测完是"这代码干嘛的"，测前是"这代码应该干嘛" |
八、Token 效率（重要）
频繁加载的 skill 要控制体积：
| 类型 | 目标字数 |
|---|---|
| getting-started 类 | <150 词 |
| 常用 skill | <200 词 |
| 其他 skill | <500 词 |
技巧：
- 长参考文档放到 references/ 目录
- CLI 参数用 --help 代替完整文档
- 跨 skill 引用用 **REQUIRED:** Use other-skill 形式
九、验证方法
写完后验证 YAML：
python - <<'PY'
from pathlib import Path
import yaml
for p in Path("skills").glob("*/SKILL.md"):
text = p.read_text()
if not text.startswith("---\n"):
raise SystemExit(f"missing frontmatter: {p}")
fm = text.split("---", 2)[1]
yaml.safe_load(fm)
print("ok")
PY十、快速检查清单
