【Claude Code Skill |入门与进阶实践】-CSDN博客

🌈个人主页:一条泥憨鱼(欢迎各位大佬莅临)

🎬精选专栏:数据结构与算法，Java ,AI与Agent

前言：

用 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/<your-user>/.claude/skills。

七、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 等等。不用一开始就追求完美——先用起来，边用边改。