如何编写高质量的 Claude Code Skill

Skill 是 Claude Code 生态里「写一次、永久生效」的能力资产。这篇指南讲清楚：它怎么被触发、怎么写才真的生效、以及 7 个最常见的失败写法。

1. Skill 到底是什么（30 秒）

一个 skill 就是一个带说明书的目录，核心是一个 SKILL.md 文件。它与三种老方式的区别：

方式问题Skill 解决了什么
每次打字交代同样的要求重复几十遍，版本漂移交代一次，永久生效
写进 CLAUDE.md所有规则常驻上下文，互相干扰，token 浪费按需加载——用到才读
MCP 工具解决「能力」，不解决「做法」skill 是「做法」：步骤、标准、禁区

一句话：MCP 给 Claude 新的手，skill 教它新的脑。

2. 解剖一个 SKILL.md

my-skill/
└── SKILL.md

SKILL.md 由两部分构成：frontmatter（机器读） + 正文（Claude 干活时读）。

---
name: code-review-checklist
description: 七维度系统化审查代码改动。MUST USE when 用户要求 review 代码、审查 PR、检查 diff、code review、"帮我看看这段代码对不对"。关键词：代码审查、review、PR、diff。
---

# 代码审查清单
## Workflow
1. 先读 diff 全貌，理解意图再挑错
2. 按七个维度逐项检查：正确性/安全/性能/契约/错误处理/测试/可维护性
3. 每个发现必须附 file:line 和具体修法
## Output
按 Blockers / Should-fix / Nits 三级输出，末尾给 Verdict
## Anti-patterns
- 禁止只说 "Looks good" 的盖章式审查
- 禁止报风格问题占用 blocker 位置

3. 最重要的一行：description 决定生死

Claude 平时不加载你的 skill 正文，它只看每个 skill 的 description 来决定「现在要不要用」。所以 description 写砸了，正文再好也永远沉睡。

公式

description: 【做什么】+ 【MUST USE when 触发场景】+ 【用户会说的原话关键词】

对照

❌ 沉睡写法✅ 会被触发
Helps with code quality七维度审查代码改动。MUST USE when 用户要求 review、审查 PR、检查 diff、看看代码有没有问题
Git commit helper拆分逻辑提交并写规范 commit message。MUST USE when 用户要提交代码、写 commit、说 "commit this"
把用户原话写进去。用户不会说「请优化我的提交工艺」，他们只会说 "commit 一下"。

4. 正文的黄金结构

经验上最有效的三段式（不是理论，是踩坑后的结论）：

  1. Workflow —— 编号步骤。Claude 拿到步骤的执行一致性远高于拿到一堆描述。
  2. Output —— 规定输出形态（分级/表格/字段）。规定形态 = 规定质量下限。
  3. Anti-patterns —— 禁止事项。这是大多数人漏掉、但杠杆最大的一段：模型对「禁止 X」的服从度极高，因为它把模糊的「要好」变成了可判定的「别这样」。
「不许盖章放行」比「要认真审查」有效十倍。

5. 七个常见错误（每个都附修法）

#错误修法
1description 含糊（"improve coding"）套第 3 节公式，写用户原话
2一个 skill 管五件事拆开。触发条件越单一，命中率越高
3正文是提示词堆砌，没有步骤改成编号 Workflow
4没有输出格式约定规定分级/表格/必填字段
5没有 Anti-patterns 段至少写 2-3 条硬禁区
6中英文关键词只写一种双语都写（说 "review" 和说 "审查" 的是同一个人）
7写完不测下一节：三个测试用例

6. 怎么测：三个用例

  1. 触发测试：新会话里用「用户原话」提需求（如 帮我看看这次改动有没有问题），看 skill 是否被加载。没触发 → 回去改 description。
  2. 反例测试：说一句相近但不该触发的话（如「帮我写个新功能」），确认它不乱入。误触发比不触发更烦。
  3. 质量测试：故意埋一个 bug（如漏掉幂等检查），看 skill 能不能按它的 Workflow 抓出来。抓不出 → 步骤不够具体。

7. 装到哪里

# 用户级（所有项目可用）
my-skill/SKILL.md  →  ~/.claude/skills/my-skill/SKILL.md

# 项目级（随仓库走，团队共享）
my-skill/SKILL.md  →  <repo>/.claude/skills/my-skill/SKILL.md

项目级是团队规范对齐的利器：skill 进了仓库，全团队的 Claude 自动同频。

8. 想直接用现成的？

本文的写法原则来自一个 15 个 skill 的工程包——pr-reviewer / bug-hunter / test-forge / feature-spec / commit-craft 这 5 个在 GitHub 上以 MIT 开源，可以直接当模板改：

Claude Skills Pro — 15 个固化资深工程师工作流的技能包

GitHub 免费样品（MIT） 看完整目录 →