Claude Code 实践指南（三）：组织 Skills 系统

很早之前就想写这篇关于 Skills 的介绍，但一直犹豫，Skills 的生态变化太快，我怕写完的时候，它已经又是另一副面孔了。不过想了想，核心机制是稳定的，变了的大多是表面，所以还是写吧。

上一篇我们聊了 CLAUDE.md，它是厨房操作规范，静态的规则和偏好，写一次天天生效。但你在后厨干活，光有规范还不够。炒宫保鸡丁有炒宫保鸡丁的套路，先腌肉、再调汁、最后大火爆炒，这是一套流程，不是一条规则。你没法把 ”宫保鸡丁做法” 塞进一条备忘录里，因为它不是偏好，而是一套有序的操作。

Skills，就是把这套流程打包起来。Claude 通过学习 skill 中的描述，就知道该按什么顺序、用什么标准来操作。

CLAUDE.md 的局限在哪里

CLAUDE.md 能做的事很明确，告诉 Claude 你的口味偏好和项目规矩。但它有个硬伤，只能表达静态规则，无法封装多步骤工作流 或特定领域知识 。

你可以在 CLAUDE.md 里写 ”代码提交前必须过审查”，但并不适合详细写清楚 ”审查具体分几步、每步看什么、输出什么格式的报告”。这就像告诉大厨 ”菜要好吃”，但没给他菜谱，方向对了，操作模糊。

Skills 的本质，就是将一套标准操作流程（SOP）打包成 Claude 可调用、可重复执行的 ”技能单元”。

一个 Skill 里面到底装了什么

一个 Skill 就是一个包含 SKILL.md 文件的目录。结构很简单：

.claude/skills/code-review/
├── SKILL.md
├── (可选) scripts/       # 可执行脚本，Claude 可直接调用
├── (可选) references/    # 参考文档，按需加载进上下文
└── (可选) assets/        # 模板、示例等附属资源

SKILL.md 的格式也不复杂，核心就是一段 YAML frontmatter 加正文，举个例子：

---
name: code-review
description: Execute a thorough code review following team standards
---

# Code Review Process

## Step 1: Read the diff
...

frontmatter（两个 --- 之间的 YAML）定义技能的元数据。name 是标识符，必须和目录名一致；description 是唯一触发信号，Claude 只靠它来决定是否自动调用这个 skill。写得太模糊，Claude 不知道什么时候该用；写得太窄，又可能漏掉该触发的场景。

description 的书写策略

既然 description 是自动触发的唯一依据，值得花点篇幅说说怎么写。

Claude 有一个倾向：不触发（undertrigger）。它宁可不用 skill 也不要误用，所以你的 description 得 ”推” 它一把。具体来说，description 里应该同时包含两件事：这个 skill 做什么 ，以及 什么时候该用它 。

举个糟糕的例子：

1	description: Code review skill

太简短了，Claude 不知道该在什么场景下触发。更好的写法：

1 2	description: Use when a major project step has been completed and needs review against the original plan and coding standards

这个写法明确了触发场景（”项目里程碑完成时”），Claude 就知道该在什么时候主动调用它。

还有一个常见的误区：把 ”什么时候用” 的信息写在 SKILL.md 的正文中，而不是 description 里。这是没用的，因为正文在触发之前 Claude 根本看不到。关于这一点，下一节会解释原因。

其他 frontmatter 字段

除了 name 和 description，还有一些可选字段，我挑几个常用的：

字段	用途
model	指定执行该 skill 时使用的模型，可选 haiku、sonnet、opus，默认继承当前会话的模型
allowed-tools	预授权的工具列表，减少权限弹窗。支持通配符如 Bash(git:*)
argument-hint	给用户的参数提示，比如 [pr-number] [priority]，会在斜杠命令菜单中显示
disable-model-invocation	设为 true 后，这个 skill 只能由用户手动 /skill-name 触发，Claude 不会自动调用它

其中 model 字段挺实用。如果一个 skill 只是做简单的格式化，指定 haiku 就够了，没必要动用 opus，省 Token 又快。如果是要做深度推理的代码审查，就指定 opus。

正常情况下，Claude 每次调用工具都会弹权限确认，如果你的 skill 需要频繁执行 git 命令，弹窗能把人弹崩溃。在 frontmatter 里写上 allowed-tools: Bash(git:*)，这类操作就自动放行，不再打扰你。

disable-model-invocation 适合那些必须由人主动发起的 skill。比如一个会删除分支的清理 skill，你肯定不想让 Claude 自作主张的触发，加了这个字段就锁死了，只有你亲手 /clean-branches 才会执行。

怎么让 Claude 用上 Skill

Skills 有两种触发方式。

自动触发 ：Claude 会根据你提的问题，自动判断是否需要调用某个 skill。这个判断依赖于 SKILL.md 中的 description 字段，所以我说 description 要写好。

手动触发 ：在对话中使用 /skill-name，这就是一个斜杠命令。比如你想让 Claude 用 code-review 技能来审查代码，直接输入：

1	/code-review 请审查 app.py

在 Claude 会话中输入 /skills，就会列出所有已加载的 Skills 清单。

如果你还没有安装任何 skill，这里输出就是空的。后边我会介绍如何安装 skill。

Skills 和斜杠命令的关系

在 ~/.claude/commands/ 目录，里面放的是 ”命令”，用 /command-name 触发。Skills 和 Commands 共享同一套触发机制，区别只在文件布局。.claude/commands/ 是旧格式，.claude/skills/name/SKILL.md 是新格式，两者加载方式完全一样。

对于用户来说，skill 就是一个斜杠命令。在 Claude 会话中输入 /，会出现一个命令菜单，你所有的 skill 都列在里面，description 就是菜单里显示的说明文字。所以 description 不只是给 Claude 看的触发信号，也是给人看的说明，写清楚点，两方都受益。

渐进式披露：Claude 怎么加载你的 Skill

这是 Skills 机制里最精巧的设计，也是很多人忽略的部分。

Claude 对 Skill 的加载分三层，逐层递进：

第一层：元数据（始终在上下文中）。 每次会话启动时，Claude 会加载所有 skill 的 name 和 description，组成一个可用技能清单。这一层的体积很小，每个 skill 大概 100 词左右，但它是 Claude 判断 ”该不该用这个 skill” 的唯一依据。

第二层：SKILL.md 正文（触发时加载）。 当 Claude 决定调用某个 skill，或者用户用 /skill-name 手动触发时，SKILL.md 的完整正文才被加载到上下文中。这就是为什么我说 ”什么时候用” 的信息必须写在 description 里，而不是正文里，正文 Claude 在触发之前根本看不到。

第三层：附属资源（按需加载）。 skill 目录下可以有 scripts/、references/、assets/ 等子目录，里面放脚本、参考文档、模板文件。这些内容不会自动加载，只有 SKILL.md 的正文里指示 Claude 去读的时候，才会被拉进上下文。而且脚本可以直接执行，不必先加载源码。

这个三层设计解决了一个矛盾：你想让 Claude 知道很多技能的存在，但又不想把所有技能的完整内容都塞进上下文。这就是渐进式披露。

理解了这个机制，几个最佳实践就自然浮现了：description 要写清触发场景；SKILL.md 正文控制在 500 行以内，超出的内容拆到 references/ 里；别在正文里藏触发条件，Claude 看不到。

虽然 SKILL.md 的格式并不复杂，但写一份好的技能描述需要仔细推敲，description 越精确，Claude 触发和执行的准确度也就越高。

好消息是，你不必手动写。后面我会介绍怎么让 Claude 帮你生成。

Skills 放在哪里，谁优先

Skills 有三种存放位置，同时存在时将按优先级从高到低覆盖，高优先级的同名 skill 会覆盖低优先级。

位置	路径	是否提交 Git	适用场景
项目 Skills	.claude/skills/	提交	团队共享的项目特定技能
个人 Skills	~/.claude/skills/	不提交	个人常用技能
插件 Skills	~/.claude/plugins/`	不提交	插件绑定的专用技能

个人技能跟着你走，项目技能跟着仓库走，插件技能跟着社区走。如果你在个人目录和项目目录各放了一个同名的 skill，项目级的会优先生效，这和 CLAUDE.md 的层级逻辑一致，近的覆盖远的。

有哪些现成的 Skills 可以直接用

不必什么都自己写。社区里已经有不少经过打磨的技能，拿来改改就能用：

Skill 名称	功能
code-review	按团队规范审查代码，输出结构化报告
brainstorming	是 superpower plugin 的一个 skill，在社区非常热门，它帮助你梳理技术思路和生成 spec 文档
grill-me	是 mattpocock 维护的一个 skill，它可以让 Claude 扮演任何角色，通过多次挖掘式对话来启发你的思考
find-skills	它可以帮助你找到适合你的技能，也会在交互时自动推荐社区的 skill
skill-creator	它可以帮你编写自己的 skill，下边会介绍怎么手工开发 skill
pptx	这是 Anthropic 官方的一个 skill，可以帮助你生成 PPT
frontend-design	这也是 Anthropic 官方提供的 skill，它可以帮助你设计前端界面

这些 skill 都开源在 GitHub 上。你也可以通过 find-skills 来找到自己需要的 skill 或者直接访问 skills.sh 来查看所有可用的 skill。

顺便提一嘴，插件（plugin）是对一些 skills、Hooks 等的封装，让它们可以在 Claude Code 中以插件的形式安装使用。Claude 有个命令是 /plugin，可以用它直接安装一个社区插件包。

怎么安装一个第三方 Skill

其实不需要安装器，也不需要包管理器。一个 Skill 就是一个包含 SKILL.md 的目录。所谓安装，就是把那个目录放到 Claude Code 约定好的位置。这就是整个过程。

前文提过 Skills 的三个存放位置：个人目录 ~/.claude/skills/、项目目录 .claude/skills/、以及通过插件安装。个人目录适合放通用的技能，不管打开哪个项目都能用；项目目录适合放跟项目绑定的技能，跟着仓库走。你要做的只是把 skill 文件夹复制到对应的路径下。

不过，这种手动复制粘贴的办法还是太原始了。程序员都是 “偷懒” 的一帮人，所以能用工具就不动手。

在一些插件或 skill 开源仓库中，会介绍怎么一键安装。最常见的方法是使用 skills.sh 安装器，它通过 npx 运行，比如安装 mattpocock 的 skills 包：

1	npx skills@latest add mattpocock/skills

其中 mattpocock/skills 是 GitHub 上的一个仓库 https://github.com/mattpocock/skills，包含了多个 skill。

若想要安装插件，可以在 Claude Code 中使用 /plugin 命令，比如：

1	/plugin install superpowers@claude-plugins-official

这是 superpowers 插件包，一个社区上很火的 AI Agent 扩展。

安装完毕后，重启 Claude Code 后在会话中输入 /skills，就能看到新安装的 skill 出现在列表里了。

就这样。没有编译步骤，没有依赖解析，没有注册中心。Skill 就是一份自然语言写成的操作手册，Claude Code 启动时扫描指定目录，找到 SKILL.md 就加载元数据，触发时读正文。

不过需要明确的一点是，安装第三方 skill 之前，建议先扫一眼它的 SKILL.md 内容，重点看里面有没有 Bash 命令。如果看到 curl 往外部地址发数据，就该警惕了，有可能会涉及到信息安全问题。这一点的详细讨论放在后边的文章中。

手工编写一个 skill

除了安装现成的 skill，也许有时你想要一个高度定制化的版本，比如想把公司内的一些指导经验做成 skill。

让我们来创建一个实际的 skill 来演示这个过程。

开始之前，推荐先安装 skill-creator ，它可以指导 Claude code 生成 skill，可以理解成是一种”skill 生成器”。

用自然语言描述你想要的技能

在 Claude 会话中输入：

请帮我创建一个 SKILL，
技能名称：pytest-gen
功能：给定一个 Python 函数，生成对应的 pytest 单元测试。
测试应该覆盖：正常输入、边界条件（空列表、None、零值）、异常处理。
测试文件命名为 test_<原文件名>.py，放在 tests/ 目录下。

注意这里的描述方式，我不仅说了 ”生成测试”，还具体说了覆盖哪些场景、文件怎么命名、放在哪里。描述越具体，生成出来的 skill 质量越高。

Claude 生成 SKILL.md

Claude 会分析你的描述，生成完整的 SKILL.md 文件并保存到 .claude/skills/pytest-gen/ 目录下。你可以要求它修改，比如 ”增加 mock 数据库的示例”，直到满意为止。

虽然 Claude 能帮你生成 SKILL.md，但生成的质量取决于你描述得有多精确，垃圾进，垃圾出。花时间想清楚你要什么，比生成后反复修改要高效得多。

使用 Skills 需要注意什么

优先使用已有的公共 skill，不要重复造轮子。

定制优于从头写，如果公共技能不完全符合需求，复制到本地后让 Claude 修改它。

注意安全，安装第三方技能前，快速查看其 SKILL.md 内容，确认它不会做你不想让它做的事。

另外，可以用 /skills 命令随时查看当前激活的 Skills 清单，确认你想要的技能确实已经加载。

我自己也整理维护了一套 skills 包，把一些社区热门的 skills 整合在一起，做一些本土化定制，也方便一键安装。如果你感兴趣也可以去看看：https://github.com/P2Tree/ai-agent

写在最后

其实说实话，Claude Code 本身的能力已经很强了，它在更新过程中，也在不断融合一些常用的 skill 到系统中，所以在我看来，Claude Code 自己就能做到 80 分，安装恰当的 skill 和编写合适的 CLAUDE.md 后，可以做到 95 分，这是一个锦上添花的事情。

接下来，我计划介绍下 Claude Code 这种全托管式 AI Coding，和 Chat 形式的 “传统” vibe coding 相比，最大的优势来源自哪里。当你想让它帮你查 GitHub 上的 PR、查数据库里的数据、或者写个邮件并发出去时，它是怎么做的。

下一篇，我们看看怎么用 MCP 给大厨接通连接外部世界的电话线。

封面图片来自豆包 AI。

本文同步发布在知乎账号下：Claude Code 实践指南（三）：组织 Skills 系统