Claude Skills 教程：给 AI 编程助手装上专业技能包

一、背景：prompt 解决不了“每次都讲一遍”的累

同样一段“我们项目的 PR 按什么标准审”，你在每个新会话里讲一遍，队友讲另一个版本，agent 今天记住明天忘。Skill 解决的就是这个：把“特定任务怎么做”写成仓库里的技能包，agent 遇到这类任务自动加载、按步骤执行，一次编写、永久复用、团队共享。

一句话定位：Skill = 按需加载的任务说明书（SOP），常载的放 AGENTS.md，低频专业的做成 Skill。

二、原理：Skill 是什么、怎么被触发

Skill 的物理形态很简单：目录 + 一份 SKILL.md。目录住在三处之一：项目级 .claude/skills/<名>/（随仓库走，团队共享）、用户级 ~/.claude/skills/<名>/（个人全局）、插件/市场级（装别人做好的）。SKILL.md 开头是一段 YAML frontmatter（name + description），这是触发器——agent 根据 description 判断“当前任务像不像这个技能管的事”，像就加载全文。

为什么 description 是最重要的一行：它不写“这是什么”，写“什么时候用”。“审 PR 的标准清单”不如“当用户要求 review PR/合入前检查时调用”。写错 description 等于技能不存在；写对了，agent 在相关任务上自动想起它。

Skill 里还能带：可执行脚本（scripts/，确定性检查比让模型肉眼靠谱）、模板（templates/，统一输出形状）、参考文档（references/，深料按需读）。渐进披露三层：frontmatter 常在 → SKILL.md 按需整篇 → 脚本/参考再按需。token 只花在刀刃上。

三、环境准备

mkdir -p .claude/skills/pr-reviewer/{scripts,templates,references}
claude --version  # 确认 CLI 可用；或在任意支持 skills 的 agent 里等价操作

目录规约：一个技能一个目录，目录名即技能名，全小写连字符；入口必须叫 SKILL.md。

四、分步实战

步骤 1：SKILL.md 三件套——frontmatter + 流程 + 禁止事项

---
name: pr-reviewer
description: 当用户要求评审 Pull Request、合入前检查、代码走查时调用。
  覆盖正确性、安全、测试与风格，按清单输出阻断/建议两级结论。
---

# PR Reviewer

## 流程（按序执行，不跳步）
1. 读 diff 全量：`git diff main...HEAD`，先说清这次改了什么（50 字内）。
2. 正确性：逐 hunk 找边界/空值/并发/错误码映射错位。
3. 安全：搜注入、密钥硬编码、越权、SSRF 模式（跑 scripts/scan.py）。
4. 测试：新增行为有无用例？跑 `npm test`，贴结果。
5. 输出：用 templates/report.md 的形状，结论只许三选一：
   APPROVE / REQUEST_CHANGES / NEEDS_DISCUSSION。

## 禁止
- 不许只报风格问题凑数；无实质问题就 APPROVE。
- 不许臆测上下文，拿不准标 NEEDS_DISCUSSION 并写需要谁确认。
- 不许重构代码，只评审，最多给最小改法示例。

三件套缺一不可：description 管触发，流程管质量下限，禁止事项管“好心办坏事”（没这节的 skill 会把每个 PR 都审成重构大会）。

步骤 2：配脚本——把“可判定的”从模型手里拿走

# .claude/skills/pr-reviewer/scripts/scan.py
import re, subprocess, sys
diff = subprocess.run(["git", "diff", "main...HEAD"],
                      capture_output=True, text=True).stdout
rules = {
    "possible secret": r"(api[_-]?key|passwd|secret)\s*=\s*['\"][^'\"]+",
    "raw SQL concat": r"execute\(.*\+.*\)",
    "TODO left": r"TODO|FIXME",
}
fail = False
for label, pat in rules.items():
    hits = re.findall(pat, diff, re.I)
    if hits:
        fail = True
        print(f"[BLOCK?] {label}: {hits[:3]}")
print("SCAN_DONE")
sys.exit(1 if fail else 0)

chmod +x .claude/skills/pr-reviewer/scripts/scan.py
python .claude/skills/pr-reviewer/scripts/scan.py; echo $?

原则：凡是正则/命令能判定的（密钥、危险函数、禁调 API、有没有跑测试），一律写脚本，不靠模型“仔细看”。模型负责需要判断力的：业务边界对不对、错误码映射对不对、测试够不够。

步骤 3：配模板与参考——统一出口形状

<!-- templates/report.md -->
## 评审结论：<APPROVE / REQUEST_CHANGES / NEEDS_DISCUSSION>
## 改了什么（50字）
## 阻断项（没有就写“无”）
- [ ] 文件:行 — 问题 — 最小改法
## 建议项
- ...
## 测试证据
`npm test` 输出粘贴：

参考文档放 references/：如 references/security-checklist.md（OWASP 速查）、references/conventions.md（本仓库 handler/错误码规约）。SKILL.md 里只给路径，审到相关类问题 agent 自己去读——又是“指向不内联”，省 token。

步骤 4：验证触发——三句话测出 description 好坏

帮我 review 下这个 PR（当前分支对 main 的 diff）

• 期望：agent 主动加载 pr-reviewer，按流程输出模板化报告。
• 若没触发：description 加触发词（review/PR/合入前/走查），再试。连续三次不触发，重写 description 第一句。
• 进阶验证：故意埋三个雷（硬编码 key、空指针边界、无测试的新分支），看报告抓到几个——这是 skill 的单元测试，每次改 skill 跑一遍。

步骤 5：发布与复用——从个人到团队到市场

• 个人：放 ~/.claude/skills/，所有仓库通用（如 commit-message 规范）。
• 团队：放仓库 .claude/skills/ 随 PR 评审合入，skill 本身也要被 review。
• 市场/插件：打包分享前删掉公司内网路径与密钥示例，版本号写进 SKILL.md 顶部注释。

一个成熟团队的技能库长这样：pr-reviewer、add-endpoint（见 AGENTS.md 上下文）、write-tests（TDD 补单测 SOP）、migrate-dep（升级依赖五步）、release-notes（按提交生成发布注记）。五个之后先停——技能也有维护成本，长期不用的归档。

五、常见坑

1. description 写成简介：“一个很棒的 PR 评审助手”永远触发不了。写“何时调用”，动词开头，带触发词。
2. SKILL.md 写成论文：超过一屏还讲不完流程，执行时必跳步。流程 5~9 步，细节扔 references。
3. 没有禁止事项：skill 会无限加戏（评审变重构、写测试变改架构）。每份 skill 至少三条“不许”。
4. 该脚本化的靠肉眼：密钥扫描这种事让模型看一百次漏五十次，正则写死。
5. 技能与 AGENTS.md 打架：两处对同一事说法不一，agent 随机听一个。单一事实源：通用放 AGENTS.md，skill 只写“这类任务专属”，重叠处 skill 引用 AGENTS.md 而不是复述。
6. 写完不测触发：自以为 hunter，agent 一次没调过。每份 skill 配三句话触发测试+埋雷测试。
7. 无版本号的共享 skill：团队 blind 更新，行为漂移无人知。SKILL.md 顶注 <!-- v1.3 2026-08-01: 加SSRF规则 -->，变更走 PR。

六、第二个完整示例：write-tests 技能与团队治理

只讲一个技能不够，再完整走一个补单测技能，证明同一套做法可以复制。描述行写当用户要求补测试、提覆盖率、给既有代码写单测时调用，流程是先读被测文件列出分支、按分支生成用例、先跑红再补实现跑绿、最后输出覆盖率前后对比，禁止事项包括不许改业务代码、不许删已有用例、不许为凑覆盖率写无断言用例。脚本配覆盖率门禁，低于阈值直接非零退出，让机器卡住凑数行为。模板固定出口形状：覆盖文件、新增用例数、覆盖率变化、测试证据粘贴。参考目录放本仓库的测试规约，比如断言风格与夹具位置。验证同样用埋雷法：给一段带三个分支的函数，看它是否每个分支都有用例、是否真跑红过一次。

团队治理层面，技能库本身要进版本控制，所有新增与修改走评审合入，评审标准与评审普通代码一致：描述行能否触发、流程是否可执行、禁止事项是否完备、脚本是否有退出码。技能顶部注释写版本号与变更日期，行为漂移时能快速定位是哪次改动引入的。长期不用的技能归档而不是删除，归档目录保留历史，万一哪天重新启用还有据可查。技能数量也要设上限，五个左右先停一停，技能本身有维护成本，技能一多就会出现两个技能管同一件事，智能体随机听一个的尴尬。重叠时的裁决原则是通用约定只住一处，技能里用引用代替复述，保证单一事实源。最后是分享规范：打包对外分享前，删掉公司内网路径与密钥示例，把写死的内部服务地址换成占位符，避免把家底随技能一起发布出去。

再讲透描述行的写作方法论，因为它是技能生效的第一关。好描述三要素：动词开头点明动作，列出触发词覆盖用户的各种说法，限定边界避免误触发。反例是名词式简介，正例是当用户说评审、走查、合入前检查任一词时调用。写完后做三轮触发测试：标准说法、口语化说法、缩写说法各一遍，三遍都中才算过关。误触发同样要测，故意在无关任务里夹带形似的词，看它会不会错误加载，误触发说明边界太宽，要加限定语收窄。多技能协同也有讲究：同一任务命中多个技能时，优先级按专属度排序，越专属的越先加载，通用技能垫后，冲突处以专属技能为准，这条规则本身可以写进团队的技能总纲里。

调试链路建议标准化：第一步确认技能目录位置与入口文件名拼写，第二步检查描述行能否被匹配，第三步看流程是否被完整执行，第四步验证脚本退出码是否被正确处理，第五步检查模板输出是否合规。五步逐项打勾，绝大多数不生效问题都落在前两步。技能上线后还要定期复测，模型版本一换，触发敏感度可能变化，每季度跑一遍触发测试集，把漂移扼杀在摇篮里。测试集本身进仓库，与技能同生共死。这样一套下来，技能才从一次性配置变成可持续维护的团队资产，每个新成员加入第一天就能用上沉淀下来的全部经验。技能的生命周期还要管到退役：确认无人使用的技能先标记废弃，保留一个版本周期再归档，归档时写清替代方案，避免有人穿越回远古文档踩坑。技能之间的依赖要显式声明，比如评审技能依赖本仓库的测试规约，规约一变，依赖它的技能要联动复测。可以用一张简单的依赖表维护在技能总纲里，每次改公共规约就查表找受影响的技能。度量也别落下：记录每个技能的触发次数、拦截的问题数、误触发次数，数据会告诉你哪个技能在创造价值，哪个只是摆设。长期零触发的技能果断归档，技能库的健康度比数量重要得多。新人上手环节建议配一份技能地图，一页纸讲清有哪些技能、各管什么、触发词是什么，贴在仓库显眼处。再配一次结对演示，老手带新人完整走一遍触发加执行的全链路，半小时就能建立体感。技能文档本身也要写给人看，注释里讲清每个流程步骤为什么存在，接手的人才敢改。定期开一次技能评审会，过一遍度量数据，归档该归档的，升级该升级的，让技能库始终处于精简好用的状态。效果评估建议每季度做一次：统计拦截的关键问题数，复盘漏网的典型案例，把漏网模式沉淀为新的检查项，技能就是这样越用越强的。投入产出比要算清楚，一个好技能的标准是新人也能稳定输出老手的质量，这笔账算得过来，技能建设就值得持续投入。记住一句话：技能写得越具体，智能体发挥越稳定，模糊的技能只能收获模糊的执行，这是全文最值得背下来的一句，贴在工位上也不过分，照着做三个月，团队的评审质量会肉眼可见地稳定下来，这就是技能复利，越早建越赚。

七、总结

Skill 的本质是把“怎么做事”从对话搬进仓库：description 决定会不会被想起，流程决定下限，禁止事项决定不翻车，脚本决定判定项零漏报，模板决定出口统一。从 pr-reviewer 起手，跑通“写→触发测试→埋雷测试→团队合入”全环，再扩展到 3~5 个高频任务。之后每个新会话，agent 第一次就像跟你合作半年的老手——因为规矩已经写进了它的技能包。 点击阅读原文

参考资料：tech-insider《How to Use Claude Skills 2026》。 点击阅读原文