Claude Code Skill的入门与进阶实践指南

前言

用 Claude Code 时间一长，你就会发现一件事：很多话你翻来覆去地说。

写 PR 描述要固定格式，做代码审查得先看风险，文档得按团队模板来。头一回多讲几句还能接受，但每次都得重新解释一遍，这就成纯体力活了。

你可以把它看作是一份给 Claude 的"工作说明书"——把你平时常用的规则写进去，往后碰到类似的活，它自己就按规矩来，不用你手把手再教一遍。

所以 Skill 的核心逻辑其实一句话就能讲清楚：

一、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 容易撞车，后面维护起来也麻烦。

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 放哪里

两个位置：

只属于你个人，跨项目都能用。适合放你喜欢的 PR 格式、commit message 风格、文档结构偏好、代码解释习惯。

放在代码仓库里，团队共享。适合放团队代码规范、项目架构说明、测试流程、UI 设计规范、代码审查标准。克隆项目的人自动获得同一套规则。

Windows 下个人 Skill 的位置在 C:/Users//.claude/skills。

七、Skill 怎么自动生效

Claude Code 在启动时扫描所有 Skill，但不会一次性全部读进去。

当你发出请求（比如“帮我写个 PR 描述”），Claude 会拿这句话去匹配所有 Skill 的 description。

这样做的好处很明显：平时不占上下文，需要时再加载，完全不需要你手动敲一大段提示词。

这就像手机通讯录。你不会每次打电话前把所有联系人详情看一遍，而是搜个名字，找到匹配的，再点进去看详情。

八、Skill 和 CLAUDE.md 的区别

很多人刚开始容易把这两个东西搞混。

CLAUDE.md 是“

”——比如你希望所有任务都默认用 TypeScript 严格模式，那就写进 CLAUDE.md。

而 Skill 是“

”——比如你只希望在写 PR 描述时用某个模板，那就写成 Skill。

简单总结：

九、什么时候该写 Skill

判断标准就是一句话：这件事我是不是经常重复解释？

比如你经常说“帮我 review 代码，先找风险，再给建议，最后总结”——那就写个 code-review Skill。

你经常说“帮我写 commit message，格式用 type(scope): summary”——那就写个 commit-message Skill。

Skill 的意义，不是让你去写更多的配置，而是让你以后少说重复的话。当你脑子里冒出“以后都按这个格式来”这个念头时，就说明该动手写了。

十、怎么写一个好 Skill

不需要复杂，但一定要清楚。

别叫 review，得叫 frontend-review、backend-review、security-review 这类。

这个 Skill 是干什么的？用户在说什么的时候应该触发它？

“请写得好一点”这种话没用。写“先总结主要变化，再列出风险，最后给出修改建议”——Claude 才能执行具体动作。

比如固定的 ## Summary / ## Risks / ## Suggestions 结构。输出稳定了，你复制粘贴也方便。

先写一个 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 的优先级

不同位置有同名 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、代码审查——写个简单版，用起来，然后慢慢迭代。

等你脑子里再次冒出那句“以后都按这个格式来”的时候，你就已经知道该怎么办了。