前言
用 Claude Code 时间一长，你就会发现一件事：很多话你翻来覆去地说。
写 PR 描述要固定格式，做代码审查得先看风险，文档得按团队模板来。头一回多讲几句还能接受，但每次都得重新解释一遍，这就成纯体力活了。
而 Skill 要解决的，正是这个麻烦。
你可以把它看作是一份给 Claude 的"工作说明书"——把你平时常用的规则写进去，往后碰到类似的活，它自己就按规矩来，不用你手把手再教一遍。
所以 Skill 的核心逻辑其实一句话就能讲清楚：把你反复说的要求，变成 Claude 能自动调用的规则。
一、Skill 是什么
简单来说，Skill 就是一个"任务说明文件"，Claude Code 能自动发现并调用它。
具体实现上，它就是一个文件夹，里面放着一个叫 SKILL.md 的文件。这个文件的作用是告诉 Claude：碰到这类任务，按这套规则办。
可以把它理解成三样东西的合体：
- 一份操作手册。比如你写了个写 PR 描述的 Skill，Claude 以后每次写 PR 描述就照这个来。
- 一个工作模板。你希望文档永远按"背景 → 问题 → 方案 → 结论"输出，那就按这个格式写进 Skill。
- 一种外设记忆。不是 Claude 真的记住了什么，而是你把规则写成了一个文件，它需要的时候就去读，读完照着做。
二、为什么需要 Skill
没有 Skill 的时候，你可能经常需要这么说：
“帮我写个 PR 描述，格式先写 What，再写 Why，然后列 Changes，语气简洁一点，别太长。”
说一次没事。一周说五次，你自己都烦了。
Skill 就是把这些重复说明固定下来。以后你只需要说“帮我写个 PR 描述”，Claude 就知道该怎么写。
就像你带新人。第一次得把每个步骤讲清楚，但如果你写成了 SOP，以后新人自己看 SOP 就行。Skill 就是给 AI 用的 SOP。
它省掉的是：重复沟通、每次都得重新解释、以及输出格式忽好忽坏带来的不稳定感。同时，它也把你自己和团队的工作方式沉淀了下来。
三、Skill 适合解决什么问题
判断标准其实很简单：你有没有对 Claude 说过三次以上同样的话？
如果有，那就值得写成 Skill。
常见的场景包括：写 PR 描述、做代码审查、写 commit message、按固定格式写文档、检查代码规范、按模板生成报告、解释项目架构、按某种风格改写内容。
打个比方。你每次点奶茶都说“少冰、三分糖、不要珍珠、加椰果”——这其实就是你的固定偏好。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 or summarizing changes. --- When writing a PR description: 1. Check the current branch changes. 2. Write using this format: ## What One sentence on what this PR does. ## Why Why this change is needed. ## Changes - Main changes, grouped together - Deleted or renamed files if relevant
拆开来看就两块内容：
- 上半部分（frontmatter）：告诉 Claude 这个 Skill 叫什么名字，什么时候用。
- 下半部分（正文）：告诉 Claude 具体该怎么操作。
五、name 和 description
Skill 里最关键的两个字段：
name: pr-description description: Writes pull request descriptions...
name 是名字，要求简短清晰，只用小写字母、数字和连字符。一个好的命名像是 pr-description、code-review、commit-message、frontend-review。太泛的名字比如 review、doc、work 容易撞车，后面维护起来也麻烦。
description 则是触发条件。Claude 全靠它来判断什么时候该调用这个 Skill。写得太模糊，Claude 就不知道该不该用。
糟糕的例子：
description: Helps with work.
好的例子：
description: Writes pull request descriptions. Use when creating a PR, writing a PR, or summarizing code changes for a pull request.
写 description 的时候，可以想象自己在给 Claude 贴标签：当用户说出这些话时，你就该想到这个 Skill。
六、Skill 放哪里
两个位置：
个人 Skill（~/.claude/skills）：
只属于你个人，跨项目都能用。适合放你喜欢的 PR 格式、commit message 风格、文档结构偏好、代码解释习惯。
项目 Skill（.claude/skills）：
放在代码仓库里，团队共享。适合放团队代码规范、项目架构说明、测试流程、UI 设计规范、代码审查标准。克隆项目的人自动获得同一套规则。
Windows 下个人 Skill 的位置在 C:/Users/
七、Skill 怎么自动生效
Claude Code 在启动时扫描所有 Skill，但不会一次性全部读进去。它先只看 Skill 的 name 和 description。
当你发出请求（比如“帮我写个 PR 描述”），Claude 会拿这句话去匹配所有 Skill 的 description。命中之后，才把完整的 SKILL.md 加载进来，按规则执行。
这样做的好处很明显：平时不占上下文，需要时再加载，完全不需要你手动敲一大段提示词。
这就像手机通讯录。你不会每次打电话前把所有联系人详情看一遍，而是搜个名字，找到匹配的，再点进去看详情。
八、Skill 和 CLAUDE.md 的区别
很多人刚开始容易把这两个东西搞混。
CLAUDE.md 是“每次都要看的总规则”——比如你希望所有任务都默认用 TypeScript 严格模式，那就写进 CLAUDE.md。
而 Skill 是“碰到特定任务才看的专项说明”——比如你只希望在写 PR 描述时用某个模板，那就写成 Skill。
简单总结：全局习惯放 CLAUDE.md，局部规则放 Skill。别把所有东西都一股脑塞进 CLAUDE.md。
九、什么时候该写 Skill
判断标准就是一句话：这件事我是不是经常重复解释？
比如你经常说“帮我 review 代码，先找风险，再给建议，最后总结”——那就写个 code-review Skill。
你经常说“帮我写 commit message，格式用 type(scope): summary”——那就写个 commit-message Skill。
Skill 的意义，不是让你去写更多的配置，而是让你以后少说重复的话。当你脑子里冒出“以后都按这个格式来”这个念头时，就说明该动手写了。
十、怎么写一个好 Skill
不需要复杂，但一定要清楚。
1. 名字要具体。
别叫 review，得叫 frontend-review、backend-review、security-review 这类。
2. description 回答两个问题：
这个 Skill 是干什么的？用户在说什么的时候应该触发它？
3. 指令要可执行。
“请写得好一点”这种话没用。写“先总结主要变化，再列出风险，最后给出修改建议”——Claude 才能执行具体动作。
4. 用固定格式。
比如固定的 ## Summary / ## Risks / ## Suggestions 结构。输出稳定了，你复制粘贴也方便。
5. 从小开始。
先写一个 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 看看代码、搜搜文件、解释一下结构，但绝不允许它改任何东西。
新手可以先忽略这个字段，等到需要做更安全的 Skill 时再捡起来用。
十二、进阶：渐进式披露
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/ 是配套素材。Claude 先看最重要的部分，等到需要时再翻到对应位置。
一个比较实用的建议：尽量把 SKILL.md 控制在 500 行以内，超过这个数就该考虑拆分了。
十三、Skill 的优先级
不同位置有同名 Skill 时，Claude 会按优先级来选择：企业级 > 个人 > 项目 > 插件。
对个人用户来说，只要别用太泛的名字，一般不会出现冲突。别叫 review、doc、test 这种，改成 team-code-review、api-doc-writing、frontend-test-checklist。命名越具体，越安全。
十四、怎么测试 Skill
建好 Skill 后，重启 Claude Code 让它重新扫描一下。
标准测试流程：建文件夹 → 写 SKILL.md → 重启 → 查看 Skill 是否出现在可用列表 → 用真实任务触发。
比如你建了一个 pr-description Skill，直接说“帮我给当前分支写个 PR 描述”。如果正确触发，Claude 就会按照你写的模板输出。
如果没触发，那就检查两件事：一是 description 是不是写得太模糊；二是你用的措辞跟 description 差得是不是太远。description 写的是“Helps write documents”，但你想在“写 PR 描述”时触发——这肯定对不上。
十五、一个入门示例
下面是最简单的 PR 描述 Skill，可以直接拿来用：
name: pr-description description: Writes pull request descriptions. Use when the user asks to write a PR description 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.
它的特点很突出：名字清楚、description 容易匹配、输出结构固定、指令简单。新手也能直接上手改。
用熟之后，还可以继续做 commit-message、code-review、doc-writing、bug-debugging、architecture-explainer 这些 Skill。不必一开始就追求完美——先用起来，边用边改。
十六、总结
Skill 不是什么复杂的功骻，它本质上就是让你少说重复话的方法。
如果说普通提示词是“这次请你这样做”，那 Skill 就是“以后遇到这类事，都请你这样做”。
它既适合个人沉淀工作习惯，也适合团队统一规范和流程。但比所有这些更重要的是：不用一上来就写很复杂的 Skill。从你最常重复的任务开始——PR 描述、commit message、代码审查——写个简单版，用起来，然后慢慢迭代。
等你脑子里再次冒出那句“以后都按这个格式来”的时候，你就已经知道该怎么办了。
