前言

配套资源
源码仓库 · github.com/diguike/skill-guide
在线阅读 · inferloop.dev/claude-skill

一个团队的真实困境

我之前观察过一个五人前端团队。他们的代码评审有个固定流程：每个 PR 都要至少两个人 review，按团队规范走一遍。规范文档放在 Confluence 上，写得很认真，二十几页。

跑了半年之后，问题暴露出来了。

老张每次都在评论里写”useEffect 缺依赖数组”。这句话他写了一百多遍，因为团队里有人就是会忘。小王是新来的，他每次都漏掉 XSS 检查，不是不知道，是没养成肌肉记忆。Leader 出于无奈，把 review checklist 打印出来贴在工位上，第三天就被人摘了。

文档不是没用，是没有执行机制。它躺在 Confluence 上，没有谁的 IDE 会自动加载它，没有谁的 CI 会强制校验它，没有谁会在每次写代码前先翻一遍。规范的执行完全依赖”人类记得”，而人类的记忆力，是这套体系里最脆弱的一环。

这就是 AI Skill 想解决的问题。

Skill 是什么

Skill 是一种把”知识 + 执行规则”打包成 AI 能理解的模块的方式。形式很简单——一个 SKILL.md 文件，里面写清楚这个能力解决什么问题、什么时候触发、按什么步骤做。Claude Code 把这个文件加载进来之后，AI 在合适的场景下会自动按里面的规则工作。

你可以把它想成”会被实际执行的文档”。

回到那个五人团队的例子——如果他们把 review 规范写成一个 Skill，放到项目的 .claude/skills/code-review/SKILL.md，结果会怎样？

• 老张不用再写第 101 遍 useEffect 评论。AI 会在 review 阶段把这条规范执行掉
• 小王漏掉的 XSS 检查也不用 leader 提醒，Skill 会自动覆盖
• 新人入职的第一天，跟着 Skill 走一遍就理解了团队对代码的要求
• 规范本身可以被版本控制、被讨论修改、被持续演进，不再是 Confluence 上的死文件

这听起来像理想化的描述。书里要做的，是把这个理想拆成具体的工程实践。

这本书面向谁

写给三类人：

第一类：你已经在用 Claude Code 或类似的 AI 编程工具，知道它能完成日常任务，但还没想过用 Skill 来固化你团队的最佳实践。这本书会从认知层面带你重新理解 AI 协作的可能性。

第二类：你想构建一个团队级的 AI 能力体系。你不只想让 AI 帮你写代码，还想让它按你的方式写、按你团队的规范审、按你公司的安全策略部署。这本书会从工程层面给你一套可落地的方法论。

第三类：你想把领域知识封装成 AI 模块对外发布。Skill 在某种意义上是 AI 时代的”开源包”——用别人的 Skill 复用别人的工程经验。这本书会从设计层面教你怎么写出别人愿意装、装上之后真好用的 Skill。

不需要机器学习背景。需要的是：熟悉一门主流编程语言、用过 AI 编程工具、对工程化和团队协作有自己的看法。

这本书怎么读

全书围绕一个真实案例展开：把”代码评审”这件事，从一份死文档，一步步打磨成一个生产级的 Skill。每章对应一个版本的演进，仓库里的 skills/code-review-snapshots/ 保留了每个阶段的完整代码。

二十八章按这个工程时间线展开：

第 1-3 章 认知——理解 Skill 是什么、为什么这种形态可行、它和 MCP、Plugin、Agent 的区别在哪。如果你对 Skill 还停留在”听过没用过”的阶段，从这里开始。

第 4-15 章 创造——从最小可用的 10 行 SKILL.md 开始，一步步加上结构化输出、动态上下文、外置知识、插件化规则、脚本、日志、hooks、子代理。这部分是全书最厚的部分，对应案例的 v1 到 v9。

第 16-18 章 协作——Skill 在团队里怎么共享、怎么版本管理、怎么避免互相冲突。这部分讲的是工程化，对个人开发者可以略读。

第 19-20 章 评测——一个 Skill 好不好用，凭直觉判断不够。这两章把 evals.json、CI 流水线、grader/comparator/analyzer 三角色端到端打通，让 Skill 的质量可量化。

第 21-22 章 治理——大规模使用 Skill 之后会出现的问题：准入流程、权限、安全边界、退役机制。

第 23-25 章 规模化与分发——Skill 数量到万级时怎么动态召回（Skill Hub + Tool RAG）、Skill 的版本演进灰度回退、用 Plugin 把 Skill 分发到团队和外部。这三章是第二版新增的内容，对应这个领域过去一年最重要的工程演进。

第 26-28 章 实战——把前面所有章节的内容综合应用到三个完整案例上：前端项目全流程 review、后端 API 安全审计、毕业项目自定义 Skill。

写 SKILL.md 时常翻附录的速查表——所有 frontmatter 字段、settings 项、替换变量一张表。

关于代码版本

Skill 这个领域还在快速演进。本书第二版基于 2026 年 6 月的 Claude Code 状态和 Agent Skills 规范。一些字段（paths、when_to_use、shell 等）需要 Claude Code 2.1.x 或更新版本。原理不会变——一个 AI 能理解的可执行知识包，这件事的本质是稳定的。具体 API 的差异请以官方文档为准，仓库会跟进维护。

关于第二版

第二版的主要变化：

• 去掉了”一级目录”分组，所有章节扁平编号。GitHub / 飞书一眼可见全书目录
• 评测从 3 章合并为 1 章：去掉空泛的方法论叙述，围绕真实场景从 evals.json 写到 CI 流水线
• 新增第 3 章 Skill vs MCP vs Plugin vs Agent：每个考虑用 Skill 的工程师都会问的边界问题
• 新增第 23 章 动态 Skill 召回：当 Skill 数量到万级时，怎么用 Tool RAG 让 AI 在毫秒内找到对的那几个
• 新增第 24 章 Skill 更新与回退：版本演进、灰度发布、live change detection、auto-compaction 等工程纪律
• 新增第 25 章 用 Plugin 分发 Skill：把 Skill 装进 plugin，通过 marketplace 给团队和外部分发
• 新增第 26-27 章实战：前端全流程 review、后端 API 安全审计两个完整的 90 天工程时间线
• 附录全面合并：原来 9 个附录精简到 1 个速查表，其他内容内联到对应章节
• 第 4 章合并：5 分钟入门 + 运行前提 + 结构配置，新读者一章入门

第一版有写得不错的，也有今天回头看明显欠写或欠思考的。第二版尽量在每个被读者反馈过的点上做出改进。但写书这件事永远没”完成”，只有”暂停”——如果你读完发现哪一章应该再深、哪一章可以再短，欢迎提 issue 到 github.com/diguike/skill-guide。

一点提醒

写 Skill 跟写代码不太一样。代码追求严谨、消除歧义、把每种边界情况都列清楚。Skill 追求的是”让 AI 理解为什么”——很多时候，加上一段解释为什么这样做的话，比写 50 条 MUST 都管用。这件事书里会反复出现，因为它是这个领域最反直觉、也最重要的一条经验。

往下读，先从那个五人团队的故事开始。

本章来自《Claude Code Skill 指南》开源版 · 作者「递归客」
在线阅读完整书系：inferloop.dev
源码仓库：github.com/diguike/skill-guide