让 AI 记住你的工作方式，Claude Code Skill 学习与实践白皮书

别再重复教 AI，用一个 Markdown 文件，把你的经验变成 Claude 可复用的工作能力。

开篇：为什么我们需要 Skill

使用 Claude Code 一段时间后，你很快会发现一个问题：很多要求其实是在反复说。比如 PR 描述要按固定格式写，代码审查要先看风险，文档要符合团队模板。第一次说明很正常，但每次都重新说，就会变成重复劳动。

Skill 就是为了解决这个问题而出现的。你可以把 Skill 理解成一份写给 Claude 的「工作说明书」：把常用规则写进去，以后 Claude 遇到类似任务时，就可以自动按这套方式执行。

一、Skill 是什么

Skill 是 Claude Code 可以发现和使用的一种「任务说明文件」。简单来说，它就是一个文件夹，里面放着一个 SKILL.md 文件。这个文件会告诉 Claude：遇到这类任务时，请按照这里的规则来做。

你可以把 Skill 理解成三种东西：

• 它像一份操作手册。 比如你写了一个「PR 描述 Skill」，Claude 以后写 PR 描述时，就会按照这份手册来写。
• 它像一个工作模板。 比如你希望文档永远按「背景、问题、方案、结论」的结构输出，就可以把这个模板写进 Skill。
• 它像一种长期记忆。 这里的「记忆」不是 Claude 永远把这件事存在脑子里，而是你把规则写成文件，Claude 在需要时读取文件，再按里面的说明执行。

二、为什么需要 Skill

在没有 Skill 的情况下，你可能经常这样对 Claude 说：

第一次说没问题，第二次也还能接受。但如果你每周都要说很多遍，这就变成了重复劳动。Skill 的作用，就是把这些重复说明固定下来。以后你只需要说：

Claude 就能根据 Skill 自动知道应该怎么写。这就像你第一次带新人时需要详细解释每一步，但如果你把流程写成一份清楚的 SOP，以后新人只要看 SOP 就能照着做。Skill 就是给 AI 用的 SOP。

它的核心价值包括：

• 减少重复沟通
• 保证输出格式稳定
• 沉淀个人经验
• 沉淀团队规范
• 让 Claude 更懂你的工作方式
• 让复杂任务变得更容易复用

三、Skill 适合解决什么问题

只要某件事你经常重复告诉 Claude，就很适合做成 Skill。比如：

• 你经常让 Claude 写 PR 描述 / 做代码审查 / 写提交信息
• 你经常让 Claude 按固定格式写文档 / 检查代码是否符合团队规范
• 你经常让 Claude 按某个模板生成报告 / 解释项目架构 / 按你的风格改写内容

举个生活化的例子：如果你每次点奶茶都要说「少冰、三分糖、不要珍珠、加椰果」，那你其实已经有了一个固定偏好。Skill 就像把这个偏好存成「我的默认奶茶配置」，以后你只说「按我的老样子来」，对方就知道该怎么做。在 Claude Code 里，Skill 就是你的「老样子」。

四、Skill 的基本结构

一个 Skill 通常长这样：

这里的 pr-description 是 Skill 文件夹，SKILL.md 是真正写规则的地方。一个简单的 SKILL.md 可以这样写：

不用被这段内容吓到，它其实只有两部分。上半部分叫 frontmatter（可以理解成「文件说明卡」），告诉 Claude 这个 Skill 叫什么、什么时候用；下半部分是具体规则，告诉 Claude 真正该怎么做。

• 上半部分：告诉 Claude「我是谁、什么时候用我」
• 下半部分：告诉 Claude「用了我以后要怎么做」

五、name 和 description 是什么

Skill 里最重要的是两个字段：name 和 description。

name：Skill 的名字

它最好简短、清楚，而且只使用小写字母、数字和连字符。比如：

不要写得太泛。不太推荐 review / doc / work；更推荐 frontend-review / api-doc-writing / pr-description。名字越清楚，后面越好维护。

description：Skill 的触发条件

description 非常重要，因为 Claude 会根据它判断什么时候该使用这个 Skill。你可以把它理解成 Skill 的「触发条件」。如果写得太模糊，Claude 可能不知道什么时候该用。

不太好的写法（太宽泛）：

更好的写法：

这个描述就很清楚：它做什么（写 PR 描述）、什么时候用（创建 PR、写 PR、总结代码变更时）。写 description 时，可以想象自己在给 Claude 贴标签：当用户说这些话时，你就应该想到这个 Skill。

六、Skill 放在哪里

个人 Skill

路径是：

个人 Skill 只属于你自己，会跟随你在不同项目中使用。适合放你喜欢的 PR 描述格式、提交信息格式、常用文档结构、代码解释偏好、个人写作风格。

项目 Skill

路径是：

项目 Skill 放在代码仓库里，可以和团队共享。适合放团队代码规范、项目架构说明、公司品牌指南、测试流程、UI 设计规范、代码审查标准。好处是团队成员克隆项目后就能用同一套规则——就像项目里自带一份「团队工作说明书」。

Windows 系统的位置

如果你使用 Windows，个人 Skill 通常放在：

七、Skill 是怎么自动生效的

Claude Code 启动时会扫描可用的 Skill，但不会一开始就读取所有内容——它只会先看两个东西：Skill 的名字和描述。当你发送请求时，比如：

Claude 会拿这句话去和所有 Skill 的 description 做匹配。如果发现某个 Skill 的描述写着 Writes pull request descriptions...，它就会知道这个任务可能需要用 PR 描述 Skill，然后才加载完整的 SKILL.md，按里面的规则执行。

这就是 Skill 的好处：

• 平时不占用太多上下文，需要时才加载
• 不需要你手动输入一大段提示词
• 可以自动匹配相关任务

八、Skill 和 CLAUDE.md 有什么区别

Claude Code 里还有一个常见文件叫 CLAUDE.md，很多小白容易把它和 Skill 混淆。可以这样理解：CLAUDE.md 是「每次都要看的总规则」，Skill 是「遇到特定任务时才看的专项说明」。

比如：希望 Claude 在所有任务里都用 TypeScript 严格模式，适合写进 CLAUDE.md；只希望它在写 PR 描述时用某个模板，适合写成 Skill。所以不要把所有东西都塞进 CLAUDE.md——如果一条规则只在某类任务里使用，写成 Skill 往往更合适。

九、什么时候应该写 Skill

你可以用这个问题判断：这件事是不是我经常重复解释？ 如果答案是 yes，就适合写 Skill。例如你经常说：

那就可以写一个 code-review Skill。你经常说：

那就可以写一个 commit-message Skill。

十、如何写一个好 Skill

一个好 Skill 不需要复杂，但要清楚。

• 名字要具体。 不要叫 review，可以叫 frontend-review / backend-review / security-review。
• description 要写清楚。 它应回答两个问题:这个 Skill 做什么?用户说什么时应该使用它?
• 指令要可执行。 不要只写「请写得好一点」(太抽象),要写「先总结主要变化,再列出风险,最后给出修改建议」。
• 尽量用固定格式。 固定格式让输出更稳定,也方便复制到 PR、文档或团队工具。
• 不要一开始写得太大。 先写一个小 Skill(比如 PR 描述),用顺了再扩展。

可执行的固定格式可以是这样：

十一、进阶功能：allowed-tools

Skill 还可以限制 Claude 能使用哪些工具。比如：

allowed-tools 表示这个 Skill 只能使用指定工具，适合只读场景：你只想让 Claude 阅读代码、搜索文件、解释结构，而不希望它修改文件。常见用途包括只读代码审查、项目结构讲解、新人 onboarding、安全敏感的检查流程。对小白来说可以先不用这个字段。

十二、进阶技巧：渐进式披露

如果一个 Skill 内容越来越多，不建议全部写在 SKILL.md 里——文件太长后 Claude 每次读取都会占用更多上下文,也不方便维护。更好的方式是拆开：

• SKILL.md 放核心说明
• references/ 放详细参考资料
• scripts/ 放可以运行的脚本
• assets/ 放模板、图片、示例文件

这就像一本书:SKILL.md 是目录和重点摘要,references/ 是详细章节,scripts/ 是自动化工具,assets/ 是配套素材。Claude 不需要一开始就读完整本书,只在需要时翻到对应章节——这就是「渐进式披露」。核心思想是:先给 Claude 看最重要的内容,只有需要时才打开更详细的资料。

十三、Skill 的优先级

如果不同地方有同名 Skill，Claude 会按优先级选择，一般顺序是：

• 企业级 Skill
• 个人 Skill
• 项目 Skill
• 插件 Skill

这意味着如果公司设置了统一规范,它的优先级最高。对个人用户来说,只要避免 Skill 名字太泛就不容易冲突——不要用 review / doc / test 这类普通名字,可以用 team-code-review / api-doc-writing / frontend-test-checklist。命名越具体,越不容易撞车。

十四、如何测试 Skill

创建 Skill 后,需要重启 Claude Code 让它重新扫描技能。测试方式很简单：

• 创建 Skill 文件夹
• 编写 SKILL.md
• 重启 Claude Code
• 查看 Skill 是否出现在可用列表中
• 用真实任务触发它

比如你创建了 pr-description Skill,就可以说：

如果 Claude 正确识别,它就会按你写的模板输出。如果没触发,通常检查两件事:description 是否写得太模糊?你的请求措辞是否和 description 差太远?把模糊的 Helps write documents. 改成更精准的描述(说明在「写 PR 描述」时触发),触发概率就会更高。

十五、一个适合小白的入门 Skill 示例

下面是一个最简单的 PR 描述 Skill：

这个 Skill 的特点是:名字清楚、description 容易匹配、输出结构固定、指令简单、小白也容易修改。你可以先从这种简单 Skill 开始,等熟悉之后再做更多,比如 commit-message / code-review / doc-writing / bug-debugging / architecture-explainer。

不要一开始就追求完美。Skill 最好的写法,往往是先用起来,再根据实际使用慢慢改。

十六、结论

Skill 是 Claude Code 里非常重要的一种能力。它不是复杂的编程功能,而是一种让 AI 更懂你工作方式的方法。如果说普通提示词是「这次请你这样做」,那么 Skill 就是「以后遇到这类事情,都请你这样做」。

它适合个人,也适合团队:个人用它沉淀工作习惯,团队用它统一代码规范、文档格式和审查流程,项目用它保存特定的架构知识和操作步骤。对刚开始学 Claude Code 的人来说,不需要一开始就写很复杂的 Skill,最好从一个你最常重复的任务开始——PR 描述、Commit message、代码审查、文档模板、测试检查清单。先写一个简单版本,用起来,再慢慢改进。