Claude Code Skills 实战：用 SKILL.md 打造团队工作流与自动化检查

更新日期：2026-09-27

Claude Code 装好之后，多数人只用它做"对话式改代码"，这其实只用到了一半能力。另一半在于 Skills：把团队的规范、流程、检查清单写成模型可复用的能力包，让 AI 在合适的时机自动按你的流程干活——而不是每次都在对话里重复交代背景。

本篇从 SKILL.md 的机制讲起，覆盖放置位置、编写要点、触发调优，以及三个可以直接抄走的实战工作流（发布前检查、事故排查、内容 SEO 自检），最后给出 Skills 与 CLAUDE.md、Slash Commands、MCP 的分工边界。前置的安装步骤见我们的 Claude Code 安装指南。

一、Skills 是什么：一个文件夹 + 一份 SKILL.md

一个 Skill 就是一个目录，核心是一份 SKILL.md 文件，用 YAML frontmatter 声明元信息，正文描述这个能力要怎么做：

---
name: release-check
description: 发布前执行完整检查：lint、类型检查、构建、迁移状态与未提交变更审查。当用户提到"发布"、"上线"、"release"时使用。
---

# 发布前检查

按以下顺序执行，任何一步失败即停止并报告：

1. 运行 `pnpm lint`，零告警才通过
2. 运行 `pnpm typecheck`
3. 运行 `pnpm build`
4. 检查是否有未执行的数据库迁移（`pnpm db:migrate:status`）
5. 汇总未提交的变更，列出本次发布将包含的内容

关键设计是渐进披露（progressive disclosure）：Claude Code 平时的上下文里只有每个 Skill 的 name 和 description（几十个词），只有当对话内容命中 description 描述的场景时，才会把 SKILL.md 正文加载进来执行。这意味着你可以放几十个 Skill 而不撑爆上下文——代价是 description 写得好不好直接决定 Skill 会不会被触发。

二、放在哪里：个人、项目与插件三个层级

个人级 ~/.claude/skills/<skill-name>/SKILL.md：只对你自己生效，跨所有项目可用。适合个人偏好类能力（比如你专属的提交信息格式）。

项目级 <project>/.claude/skills/<skill-name>/SKILL.md：随仓库提交，团队所有人可用。这是团队工作流的正解——Skill 变更走 code review，规范演进有记录、可回滚。

插件分发：Skill 也可以打包进 Claude Code 插件通过 marketplace 分发，适合开源社区或跨多个仓库复用的场景。

同名冲突时，项目级优先于个人级。团队落地时建议约定：项目级只放"这个仓库需要的流程"，个人习惯放个人级，避免互相覆盖。

三、description 写不好，Skill 就是摆设

触发机制决定了 description 是整个 Skill 最重要的 40 个词。写它的时候回答三个问题：这个 Skill 做什么？什么情况下应该用它？什么情况下不该用？

反例（太抽象，模型无从判断）：

description: 代码检查工具

正例（场景明确，边界清晰）：

description: 对当前分支执行发布前检查（lint、typecheck、build、迁移状态），在用户要求发布、上线、打 tag 或创建 release 分支时使用。日常开发中的单文件问题排查不适用。

两个实用技巧：一是在 description 里放用户实际会说的话（"发布""上线""release"），触发本质上是语义匹配；二是如果发现 Skill 该触发时没触发、不该触发时乱触发，第一反应永远是改 description 再迭代，而不是改正文。

frontmatter 里还可以用 allowed-tools 收紧这个 Skill 运行时允许的工具集合——只读检查类 Skill 限制成只能执行特定命令，是安全实践的一部分。

四、实战一：发布前检查 Skill

把团队的发布清单固化下来，上面的例子就是骨架。实战中有三个增强点：

让 Skill 幂等：每一步都写成"检查→失败即停"，不做任何修复动作。修复类操作（自动 lint --fix、自动改配置）应该显式征求确认，否则发布检查可能顺手改坏东西。

输出结构化结论：要求最后输出一个固定格式的总结（每步通过/失败、耗时、失败日志的关键行），方便贴进发布工单。

与 CI 保持同源：Skill 里的命令应当与 CI 流水线一致，否则会出现"本地 Skill 全绿、CI 红灯"的信任裂痕。命令有差异时，以 CI 为准修 Skill。

还有一条经验：给检查加时间预算。Skill 正文里写明"整套检查超过 10 分钟即中止并报告最慢的一步"——发布检查跑成二十分钟的灾难现场，通常就是某个步骤在等待一个已经挂掉的外部依赖。超时信息本身也是排障线索：卡住的位置往往就是这次发布要出问题的地方。

五、实战二：事故排查 Skill

把排障经验固化为决策树，是 Skills 最有想象力的用法。以 Web 服务的 503 排障为例：

---
name: http-5xx-triage
description: 网站返回 5xx 错误时的分层排查助手。当用户报告"网站打不开"、"503"、"502"、"5xx 错误"时使用。按 CDN→网关→应用→容器四层引导排查。
---

# 5xx 分层排查

先收集信息，不要猜：
1. 用 curl -sI 看原始响应头（Server 头、Retry-After、CDN 追踪头）
2. 确认影响面：全站还是单接口；从什么时候开始
3. 按 503/502/504 的语义差异分流：
   - 503 → 检查是否限流（Nginx limit_req 日志）、上游是否全部不健康、
     FPM 是否 pm.max_children 打满
   - 502 → 上游进程是否存活、返回是否异常
   - 504 → 上游耗时与超时配置
4. 每层给出对应日志位置和 grep 关键词，只读操作直接执行，
   涉及重启/改配置的操作先列出方案等确认

这个 Skill 的价值在于：新同事遇到事故时，AI 引导的排查顺序就是团队沉淀过的顺序，而不是临场发挥。排障决策树本身可以参考我们的 503 Service Unavailable 排障实战一文。

六、实战三：内容 SEO 自检 Skill

内容型项目可以把 SEO 检查清单做成 Skill：检查每篇文章的 description 长度、标题结构、内链数量、结构化数据字段是否完整、图片是否有 alt。这个场景的 Skill 特别适合附带脚本——SKILL.md 里引用同目录下的 Node 脚本，让 Claude 执行脚本拿结构化结果，再按结果解读，比让模型逐段读文章可靠得多：

---
name: blog-seo-audit
description: 对博客文章执行 SEO 自检：标题与描述长度、内链与外链、结构化数据完整性。当用户要求"检查文章 SEO"、"发布前内容体检"时使用。
---

# 内容 SEO 自检

1. 运行 `node ./scripts/audit.mjs <文章路径>`，脚本输出 JSON 结果
2. 对每个 failed 项给出具体修改建议
3. 汇总为表格：检查项 / 状态 / 建议

七、Skills、CLAUDE.md、Slash Commands、MCP 怎么分工

这四个机制经常被混用，用一张表说清边界：

机制	本质	适合放什么	触发方式
CLAUDE.md	常驻上下文	项目约定：代码风格、架构说明、禁区	每次会话自动生效
Skills	按需加载的流程包	多步骤流程、检查清单、领域方法	语义匹配自动触发
Slash Commands	用户主动调用的快捷指令	固定的快捷操作（/review、/deploy）	手动输入
MCP	外部系统实时连接	数据与动作集成（数据库、工单、监控）	工具调用

经验法则：知识放 CLAUDE.md，流程放 Skill，集成靠 MCP。如果你发现 CLAUDE.md 越写越长且大部分内容只在特定场景有用，那就是该拆成 Skills 的信号；如果你发现 Skill 里在教模型"怎么调用某个外部系统的 API"，那应该是 MCP server 的活。

八、调试：Skill 不触发的常见原因

按命中率排序：

description 与用户措辞不匹配：用户说"上线"，Skill 写的是 "deploy"。把同义词写进 description。
description 太泛：什么都能沾一点，模型反而不敢选。明确写出"什么时候用、什么时候不用"。
与内置能力撞车：Skill 名字和描述与 Claude Code 内置功能高度相似时会被内置能力截胡，改个更具体的名字。
正文过长且关键信息埋底：渐进披露会把正文整段加载，但模型对开头最敏感，把执行步骤放正文最前面。

调试手段：在对话里直接问"当前有哪些 skills 可用、你为什么没有触发 X"，Claude Code 能看到自己的技能清单并解释决策；临时验证也可以直接说"使用 release-check 这个 skill"，强制走指定 Skill 路径观察执行过程。

九、安全边界：Skill 会以你的权限执行

最后强调安全：Skill 正文里的命令会以当前用户的完整权限真实执行，第三方 Skill 和"网上抄来的 SKILL.md"应当像对待陌生脚本一样先读一遍。项目级 Skill 走 code review；涉及删除、部署、数据库变更的步骤，在 SKILL.md 里显式写上"执行前列出方案等确认"；敏感环境（生产数据库、云账号）按最小权限原则控制运行 Claude Code 的身份，相关的权限隔离与审计框架见我们的 AI Agent 服务器运维一文。

十、从成功的对话里"沉淀"出新 Skill

团队推广 Skills 最有效的路径不是坐下来凭空设计，而是从重复发生的对话里捞：当你发现同一个请求第二次向 Claude 解释同样的背景和流程时，就是沉淀信号。

具体做法：把上次最顺利的那次对话找出来，提炼三个要素——触发场景（用户说了什么）、执行步骤（Claude 实际做了什么）、验收标准（你怎么判断做得对）。这三要素直接翻译成 SKILL.md 的 description、正文步骤和输出格式要求。这样的 Skill 天然贴合团队真实工作流，比闭门造车的完整度高。

推广节奏建议：先让两三个人用一周，收集"没触发"和"触发了但步骤不对"的反馈，迭代 description 和步骤，再全团队推广。Skill 的 description 迭代记录留在 git 里，本身就是团队知识的演化史。

十一、多文件 Skill：脚本与参考资料的分层组织

Skill 目录里除了 SKILL.md，还可以放脚本、模板和参考资料。组织原则遵循渐进披露的三级结构：

.claude/skills/blog-seo-audit/
├── SKILL.md              # 一级：触发后必读，只放流程和判定标准
├── scripts/
│   └── audit.mjs         # 确定性工作交给脚本，输出 JSON
└── references/
    └── schema-checklist.md  # 二级：只在需要时让 Claude 读取

第一原则：能用脚本就不用提示词。字数统计、链接抽取、结构化数据校验这类确定性工作，写成脚本让 Claude 执行并解读结果，可靠性远高于让它"读一遍文章检查一下"。第二原则：参考资料按需引用，SKILL.md 正文里写明"遇到 X 情况时读取 references/yyy.md"，避免把所有细节都塞进主文件。

十二、Skill 验收检查单

新 Skill 合入前，用这份检查单过一遍：

description 包含：做什么、何时该用、何时不用、用户的典型说法
冷启动测试：开全新会话，用自然说法提出需求，Skill 被触发
负向测试：说不相关的话，Skill 没有被误触发
幂等性：连跑两遍结果一致，不做未授权的修复动作
破坏性操作有确认点：删除、部署、数据库变更前列方案等确认
脚本有非零退出码处理：失败时 Claude 能拿到明确错误并报告
输出格式固定：结论可粘贴进工单或 PR 评论
已提交版本库，同事 clone 后即可使用

十三、团队治理：命名、审计与生命周期

命名规范：项目级 Skill 用领域-动作格式（release-check、incident-triage、blog-seo-audit），个人级加个人前缀（zhang-san-deploy-style），避免互相覆盖。禁止用太通用的名字（check、run）。

变更即评审：Skill 是"给 AI 的操作手册"，它的变更和代码变更同等对待——改了发布检查的步骤，等于改了发布制度。所有项目级 Skill 变更走 PR review。

定期回顾：每个季度过一遍现有 Skill，删除不再使用的，合并重叠的。过时的 Skill 不仅占上下文索引，更危险的是它会在错误场景里被触发，用旧流程处理新问题。

新人入职的隐藏收益：一套维护良好的项目级 Skill，就是一份"会执行的团队手册"。新人 clone 仓库后，Claude Code 按既有 Skill 引导他走发布、排障、审查流程，比通读文档更快建立正确的工作习惯——文档描述流程，Skill 演练流程。写 Skill 时把新人会问的问题写进正文（为什么这一步必须做），手册价值还会再上一个台阶。

企业环境：受管环境下可通过 settings 限制 Skill 来源（只允许仓库内与官方 marketplace），并对外部 Skill 的引入设置审批流程。

十四、与 Hooks 的配合：把"建议"升级为"强制"

Skills 是流程知识，模型执行时仍有裁量空间；如果某些规则必须无条件执行（比如"任何对生产数据库的写操作必须先展示 SQL"），要用 Claude Code 的 hooks 机制兜底：hooks 在工具调用前后由框架强制运行你的脚本，脚本可以拦截或修改调用，模型无法绕过。

典型组合：Skill 负责教模型"规范的做法"，hook 负责在模型越界时硬刹车——例如 PreToolUse hook 检测到 psql/mysql 写语句时直接阻断并提示走审批流程。两者的关系可以概括为：Skill 管质量，hooks 管红线。hooks 配置在 settings.json 中，具体事件类型以官方文档为准。

十五、实战四：数据库迁移审查 Skill

数据密集型项目再给一个模板——把迁移审查的清单固化。下面这个例子贴合 Drizzle/Prisma 类迁移工作流，其他技术栈替换命令即可：

---
name: migration-review
description: 审查数据库迁移文件的风险：锁表、破坏性变更、回滚方案与数据回填策略。当用户提到"迁移"、"migration"、"改表"或提交了 migrations 目录的变更时使用。
---

# 数据库迁移审查

对每个新增迁移文件依次检查：

1. 破坏性操作清单：DROP、RENAME、改列类型、收窄约束——逐项列出，
   每一项都要确认影响行数与锁表时长
2. 可回滚性：down 迁移是否存在且等价；不可逆变更（删列、删表）
   必须有数据导出或备份动作在前
3. 大表风险：行数超过阈值的表上的加列/加索引，检查是否使用
   非阻塞方式（并发建索引等）
4. 代码与迁移的一致性：全局搜索对旧列名/旧表的引用，确认没有漏改
5. 输出结论：风险等级（安全/需评审/禁止直接执行）+ 执行前置条件
   （备份、维护窗口、分批策略）

只读操作直接执行；任何"禁止直接执行"的结论，停止并等人工决策。

这类 Skill 的迁移审查结论稳定、口径统一，特别适合作为 CI 里人工评审前的第一道自动化关口。

十六、常见问题

Skill 能接收参数吗？ 可以在正文里约定"先向用户询问 X、Y、Z 三个输入再执行"；需要确定性参数解析的场景（脚本化调用），更适合封装成脚本由用户直接运行，或用 slash command 传参。

Skill 能调用另一个 Skill 吗？ 模型可以在一次会话里先后触发多个 Skill，但不建议在 SKILL.md 里设计显式的"Skill 链"——把公共步骤抽成脚本或合并成一个更大的 Skill，比链式依赖更可靠。

怎么跨项目复用？ 个人级目录放通用能力；跨仓库的团队 Skill 目前用插件或"初始化脚本把 .claude/skills 拷进新仓库"的方式分发，后者简单粗暴但版本管理弱，团队规模上来后建议收敛到插件市场。

Skill 越多越好吗？ 不是。每个 Skill 的 description 都常驻上下文，几十个描述会让模型选择困难，误触发率上升。超过 15–20 个时就该合并或清理了。

Skill 失效的高发时刻？ 换模型版本之后。不同代次的模型对同类 description 的敏感度有差异，升级 Claude Code 或切换模型后，把核心 Skill 的冷启动测试重新跑一遍（见第十二节检查单），触发率异常的先改 description。

写英文还是中文？ 跟团队工作语言走。description 与用户实际输入的措辞一致最重要——中文团队用中文写 description，触发匹配只会更准；正文同理，除非 Skill 要交给国际社区使用。

从哪里抄好的范例？ 官方文档的示例库之外，开源社区的热门 Claude Code 配置仓库通常带一批实战 Skill，读它们的 description 写法比自己闭门造车快得多。抄结构不抄内容：别人的 Skill 步骤未经验证前不要直接在公司项目里跑，先读懂每一步再决定取舍。

十七、一页速查：最小可用的 SKILL.md 模板

抄走就能用的骨架，注释标明了每个字段的要点：

---
name: your-skill-name
# ↑ 小写连字符，全库唯一；项目级与个人级不要重名
description: 做什么 + 什么时候用（写用户的真实说法）+ 什么时候不用。
# ↑ 触发的唯一依据，40 词内写清楚三件事
---

# Skill 标题

## 执行步骤
1. 第一步（幂等、可重跑）
2. 第二步（失败即停，报告不修复）
3. 破坏性操作：先列方案，等用户确认

## 输出格式
固定结构的结论（表格/清单），方便贴进工单。

五个高频提醒：description 写用户的原话；正文前放步骤后放细节；确定性工作交给目录内的脚本；破坏性操作必须设确认点；改完先开新会话用自然语言测试触发。

官方资料与继续阅读

Anthropic 官方 Agent Skills 文档：https://docs.claude.com/en/docs/claude-code/skills
Claude Code 官方文档主页：https://docs.claude.com/en/docs/claude-code/overview
Model Context Protocol 规范：https://modelcontextprotocol.io
站内相关文章：Claude Code 安装指南、503 Service Unavailable 排障实战、把 AI Agent 接进服务器运维：权限隔离、审计与回滚边界、Cloudflare MCP 安全治理实战