让 AI 记住你的工作方式，Claude Code Skill 学习与实践白皮书
别再重复教 AI，用一个 Markdown 文件，把你的经验变成 Claude 可复用的工作能力。
开篇：为什么我们需要 Skill
使用 Claude Code 一段时间后，你很快会发现一个问题：很多要求其实是在反复说。
比如 PR 描述要按固定格式写，代码审查要先看风险，文档要符合团队模板。第一次说明很正常，但每次都重新说，就会变成重复劳动。
Skill 就是为了解决这个问题而出现的。
你可以把 Skill 理解成一份写给 Claude 的“工作说明书”。把常用规则写进去，以后 Claude 遇到类似任务时，就可以自动按这套方式执行。
一句话理解：Skill 不是让你每次都重新教 AI，而是让 AI 在合适的时候自动使用你提前写好的规则。
目录
- 一、Skill 是什么
- 二、为什么需要 Skill
- 三、Skill 适合解决什么问题
- 四、Skill 的基本结构
- 五、name 和 description 是什么
- 六、Skill 放在哪里
- 七、Skill 是怎么自动生效的
- 八、Skill 和 CLAUDE.md 有什么区别
- 九、什么时候应该写 Skill
- 十、如何写一个好 Skill
- 十一、进阶功能：allowed-tools
- 十二、进阶技巧：渐进式披露
- 十三、Skill 的优先级
- 十四、如何测试 Skill
- 十五、一个适合小白的入门 Skill 示例
- 十六、结论
一、Skill 是什么
Skill 是 Claude Code 可以发现和使用的一种“任务说明文件”。
简单来说，它就是一个文件夹，里面放着一个 SKILL.md 文件。这个文件会告诉 Claude：
遇到这类任务时，请按照这里的规则来做。
你可以把 Skill 理解成三种东西。
第一，它像一份操作手册。
比如你写了一个“PR 描述 Skill”，Claude 以后写 PR 描述时，就会按照这份手册来写。
第二，它像一个工作模板。
比如你希望文档永远按照“背景、问题、方案、结论”的结构输出，就可以把这个模板写进 Skill。
第三，它像一种长期记忆。
这里的“记忆”不是说 Claude 永远把这件事存在脑子里，而是你把规则写成文件。Claude 在需要时读取文件，然后按照里面的说明执行。
所以，Skill 的本质是：
把你经常重复说的话，变成 Claude 可以自动调用的工作规则。
二、为什么需要 Skill
在没有 Skill 的情况下，你可能经常这样对 Claude 说：
帮我写一个 PR 描述，格式是先写 What，再写 Why，然后列出 Changes，语气要简洁，不要太长。
第一次说没问题。
第二次也还能接受。
但如果你每周都要说很多遍，这就变成了重复劳动。
Skill 的作用，就是把这些重复说明固定下来。以后你只需要说：
帮我写一个 PR 描述。
Claude 就能根据 Skill 自动知道应该怎么写。
这就像你第一次带新人时，需要详细解释每一步。但如果你把流程写成一份清楚的 SOP，以后新人只要看 SOP 就能照着做。
Skill 就是给 AI 用的 SOP。
它的核心价值包括：
- 减少重复沟通
- 保证输出格式稳定
- 沉淀个人经验
- 沉淀团队规范
- 让 Claude 更懂你的工作方式
- 让复杂任务变得更容易复用
一句话总结：
Skill 可以把“我每次都要说一遍的要求”，变成“Claude 遇到任务时自动使用的能力”。
三、Skill 适合解决什么问题
只要某件事你经常重复告诉 Claude，就很适合做成 Skill。
比如：
- 你经常让 Claude 写 PR 描述
- 你经常让 Claude 做代码审查
- 你经常让 Claude 写提交信息
- 你经常让 Claude 按固定格式写文档
- 你经常让 Claude 检查代码是否符合团队规范
- 你经常让 Claude 按某个模板生成报告
- 你经常让 Claude 解释项目架构
- 你经常让 Claude 按你的风格改写内容
判断标准很简单：
如果你已经对 Claude 说过三次以上同样的要求，就可以考虑把它写成 Skill。
举个很生活化的例子。
如果你每次点奶茶都要说：“少冰、三分糖、不要珍珠、加椰果”，那你其实已经有了一个固定偏好。Skill 就像把这个偏好存成“我的默认奶茶配置”。以后你只说“按我的老样子来”，对方就知道该怎么做。
在 Claude Code 里，Skill 就是你的“老样子”。
四、Skill 的基本结构
一个 Skill 通常长这样：
~/.claude/skills/pr-description/
SKILL.md
这里的 pr-description 是 Skill 文件夹。
SKILL.md 是真正写规则的地方。
一个简单的 SKILL.md 可以这样写：
---
name: pr-description
description: Writes pull request descriptions. Use when creating a PR, writing a PR, or summarizing changes for a pull request.
---
When writing a PR description:
1. Check the current branch changes.
2. Write the description using this format:
## What
One sentence explaining what this PR does.
## Why
Brief context on why this change is needed.
## Changes
- List the main changes
- Group related changes together
- Mention deleted or renamed files if needed
不用被这段内容吓到。它其实只有两部分。
第一部分是上面的信息：
---
name: pr-description
description: Writes pull request descriptions...
---
这部分叫 frontmatter，也可以理解成“文件说明卡”。它告诉 Claude 这个 Skill 叫什么、什么时候用。
第二部分是下面的说明：
When writing a PR description:
...
这部分就是具体规则，告诉 Claude 真正该怎么做。
所以，一个 Skill 可以拆成：
- 上半部分：告诉 Claude “我是谁、什么时候用我”
- 下半部分：告诉 Claude “用了我以后要怎么做”
五、name 和 description 是什么
Skill 里最重要的是两个字段：
name: pr-description
description: Writes pull request descriptions...
name：Skill 的名字
name 是 Skill 的名字。
它最好简短、清楚，而且只使用小写字母、数字和连字符。
比如：
pr-description
code-review
commit-message
frontend-review
不要写得太泛。
不太推荐：
review
doc
work
更推荐：
frontend-review
api-doc-writing
pr-description
commit-message
名字越清楚，后面越好维护。
description：Skill 的触发条件
description 是 Skill 的说明。
它非常重要，因为 Claude 会根据 description 判断什么时候该使用这个 Skill。
你可以把 description 理解成 Skill 的“触发条件”。
如果 description 写得太模糊，Claude 可能不知道什么时候该用。
不太好的写法：
description: Helps with work.
这太宽泛了。Claude 很难判断具体是什么工作。
更好的写法：
description: Writes pull request descriptions. Use when creating a PR, writing a PR, or summarizing code changes for a pull request.
这个描述就很清楚：
- 它做什么：写 PR 描述
- 什么时候用：创建 PR、写 PR、总结代码变更时使用
写 description 时，可以想象自己正在给 Claude 贴标签：
当用户说这些话时，你就应该想到这个 Skill。
六、Skill 放在哪里
Skill 可以放在两个常见位置。
个人 Skill
路径是：
~/.claude/skills
个人 Skill 只属于你自己，会跟随你在不同项目中使用。
适合放：
- 你喜欢的 PR 描述格式
- 你喜欢的提交信息格式
- 你常用的文档结构
- 你自己的代码解释偏好
- 你个人的写作风格
比如你希望所有 PR 描述都短一点、清楚一点，就可以写成个人 Skill。
项目 Skill
路径是：
.claude/skills
项目 Skill 放在代码仓库里，可以和团队共享。
适合放：
- 团队代码规范
- 项目架构说明
- 公司品牌指南
- 项目测试流程
- UI 设计规范
- 团队代码审查标准
项目 Skill 的好处是：团队成员克隆项目后，就能使用同一套规则。
这就像项目里自带一份“团队工作说明书”。
Windows 系统的位置
如果你使用 Windows，个人 Skill 通常放在：
C:/Users/<your-user>/.claude/skills
七、Skill 是怎么自动生效的
Claude Code 启动时，会扫描可用的 Skill。
但它不会一开始就读取所有内容。
它只会先看两个东西：
- Skill 的名字
- Skill 的描述
当你发送请求时，比如：
帮我写一个 PR 描述
Claude 会拿这句话去和所有 Skill 的 description 做匹配。
如果它发现有一个 Skill 写着：
description: Writes pull request descriptions...
它就会知道：
这个任务可能需要使用 PR 描述 Skill。
然后它才会加载完整的 SKILL.md，按照里面的规则执行。
这就是 Skill 的好处：
- 平时不占用太多上下文
- 需要时才加载
- 不需要你手动输入一大段提示词
- 可以自动匹配相关任务
可以把它理解成手机里的联系人搜索。
你通讯录里有很多联系人，但你不会每次打电话前都把所有联系人详情看一遍。你只是输入一个名字，系统找到匹配的人，然后再打开详细信息。
Skill 也是类似的逻辑。
八、Skill 和 CLAUDE.md 有什么区别
Claude Code 里还有一个常见文件叫 CLAUDE.md。
很多小白容易混淆它和 Skill。
可以这样理解：
CLAUDE.md 是“每次都要看的总规则”。
Skill 是“遇到特定任务时才看的专项说明”。
比如：
如果你希望 Claude 在所有任务里都使用 TypeScript 严格模式，这适合写进 CLAUDE.md。
如果你只希望 Claude 在写 PR 描述时使用某个模板，这适合写成 Skill。
再打个比方：
所以，不要把所有东西都塞进 CLAUDE.md。
如果一条规则只在某类任务里使用，把它写成 Skill 往往更合适。
九、什么时候应该写 Skill
你可以用这个问题判断：
这件事是不是我经常重复解释？
如果答案是 yes，就适合写 Skill。
例如，你经常说：
帮我 review 代码，先找风险，再给建议，最后总结。
那就可以写一个 code-review Skill。
你经常说：
帮我写提交信息，格式用 type(scope): summary。
那就可以写一个 commit-message Skill。
你经常说：
帮我写文档，结构要包括背景、目标、方案、风险和结论。
那就可以写一个 doc-writing Skill。
Skill 的意义不是让你写更多配置，而是让你以后少说重复的话。
一个非常实用的判断方法是：
当你想对 Claude 说“以后都按这个格式来”的时候，就应该考虑写 Skill。
十、如何写一个好 Skill
一个好 Skill 不需要复杂，但要清楚。
- 名字要具体
不要叫：
review
可以叫：
frontend-review
backend-review
security-review
- description 要写清楚
它应该回答两个问题：
- 这个 Skill 做什么？
- 用户说什么时应该使用它？
- 指令要可执行
不要只写：
请写得好一点。
这太抽象。
可以写：
先总结主要变化，再列出风险，最后给出修改建议。
Claude 更容易执行具体动作，而不是理解模糊评价。
- 尽量用固定格式
比如：
## Summary
## Risks
## Suggestions
固定格式可以让输出更稳定，也方便你复制到 PR、文档或团队工具里。
- 不要一开始写得太大
刚开始可以只写一个小 Skill，比如 PR 描述 Skill。等用顺了，再慢慢扩展。
写 Skill 和整理房间很像。
不要一开始就想把整个家重新装修。先从一个抽屉开始，把最常用、最混乱的东西整理好，你马上就能感受到效果。
十一、进阶功能：allowed-tools
Skill 还可以限制 Claude 能使用哪些工具。
比如：
---
name: codebase-onboarding
description: Helps new developers understand how the system works.
allowed-tools: Read, Grep, Glob, Bash
model: sonnet
---
这里的 allowed-tools 表示：这个 Skill 只能使用指定工具。
这适合一些只读场景。
比如你只想让 Claude 阅读代码、搜索文件、解释项目结构，不希望它修改文件，就可以限制工具。
常见用途包括：
- 只读代码审查
- 项目结构讲解
- 新人 onboarding
- 安全敏感的检查流程
对于小白来说，可以先不用这个字段。等你开始写更复杂、更安全的 Skill 时，再考虑使用。
简单理解：
allowed-tools 就像给 Claude 规定“这次你只能看，不能改”。
十二、进阶技巧：渐进式披露
如果一个 Skill 内容越来越多，不建议全部写在 SKILL.md 里。
因为文件太长后，Claude 每次读取都会占用更多上下文，也不方便维护。
更好的方式是拆开：
my-skill/
SKILL.md
references/
architecture-guide.md
review-checklist.md
scripts/
validate-env.sh
assets/
template.md
可以这样理解：
- SKILL.md 放核心说明
- references/ 放详细参考资料
- scripts/ 放可以运行的脚本
- assets/ 放模板、图片、示例文件
这就像一本书：
- SKILL.md 是目录和重点摘要
- references/ 是详细章节
- scripts/ 是自动化工具
- assets/ 是配套素材
Claude 不需要一开始就读完整本书，只在需要时翻到对应章节。
这就是“渐进式披露”。
它的核心思想是：
先给 Claude 看最重要的内容，只有需要时才打开更详细的资料。
一个实用建议：
尽量把 SKILL.md 控制在 500 行以内。超过这个长度，就考虑拆分。
十三、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，就可以说：
帮我为当前分支写一个 PR 描述。
如果 Claude 正确识别，它就会按照你写的模板输出。
如果没有触发，通常可以检查两件事：
- description 是否写得太模糊
- 你的请求措辞是否和 description 差太远
比如 description 只写了：
description: Helps write documents.
但你希望它在“写 PR 描述”时触发，这就可能不够精准。
可以改成：
description: Writes pull request descriptions. Use when the user asks to write a PR description, create a PR summary, or summarize branch changes for a pull request.
这样触发概率会更高。
十五、一个适合小白的入门 Skill 示例
下面是一个最简单的 PR 描述 Skill。
---
name: pr-description
description: Writes pull request descriptions. Use when the user asks to write a PR description, create a pull request summary, or summarize branch changes for a PR.
---
When writing a PR description, use this structure:
## What
Briefly explain what this PR changes.
## Why
Explain why this change is needed.
## Changes
- List the main changes
- Keep each bullet clear and short
- Group related changes together
## Testing
Mention how the changes were tested. If there were no tests, say so clearly.
这个 Skill 的特点是：
- 名字清楚
- description 容易匹配
- 输出结构固定
- 指令简单
- 小白也容易修改
你可以先从这种简单 Skill 开始。
等熟悉之后，再继续做更多 Skill，比如：
- commit-message
- code-review
- doc-writing
- bug-debugging
- architecture-explainer
不要一开始就追求完美。Skill 最好的写法，往往是先用起来，再根据实际使用慢慢改。
十六、结论
Skill 是 Claude Code 里非常重要的一种能力。
它不是复杂的编程功能，而是一种让 AI 更懂你工作方式的方法。
如果说普通提示词是：
这次请你这样做。
那么 Skill 就是：
以后遇到这类事情，都请你这样做。
它适合个人，也适合团队。
个人可以用它沉淀自己的工作习惯。
团队可以用它统一代码规范、文档格式和审查流程。
项目可以用它保存特定的架构知识和操作步骤。
对于刚开始学习 Claude Code 的人来说，不需要一开始就写很复杂的 Skill。
最好的方式是从一个你最常重复的任务开始。
比如：
- PR 描述
- Commit message
- 代码审查
- 文档模板
- 测试检查清单
先写一个简单版本，用起来，再慢慢改进。
真正重要的不是一次写出完美 Skill，而是开始把你的经验沉淀下来。
当你发现自己又想对 Claude 说：
以后都按照这个格式来。
那一刻，其实就是 Skill 最适合出现的时候。
最后一句话
别再重复教 AI。
把你反复说的规则写成 Skill，让 Claude Code 下次自动懂你。
