我想用最容易理解的方式解释 Claude Code Skills

开始之前#

刚开始使用 Claude Code 的时候，常常会有一种感觉。它明明很聪明，但有些任务完成得非常漂亮，有些任务却又要你从头重新解释一遍。于是你会开始想，同样是一个代理，为什么结果的稳定度会差这么多。

在我看来，造成这种差异的一个重要原因，就是 技能(Skills)。技能并不是什么魔法开关。它更像是一组工作标准，让代理在重复任务上能做得更稳定，也更像你的团队。

这篇文章想用尽量不费劲的方式来解释 Claude Code 的技能。我会先用木匠和厨师的比喻帮助你建立直觉，再说明技能在 Claude Code 里到底起什么作用，以及如果你准备自己做一个技能，应该从哪里开始。

为什么技能很重要#

像 Claude Code 这样的编码代理，本来就非常通用。它可以读代码、改代码、写文档，甚至提出测试方案。问题在于，通用并不等于稳定。

只要你在一个项目里待得足够久，就一定会遇到很多重复请求。比如这些：

• 按照我们项目的约定实现一个 API
• 从安全、回归和测试的角度做代码审查
• 把实现内容整理成架构蓝图文档
• 按照当前的语气和格式写博客文章

这些内容当然可以每次都用一大段 prompt 重新解释。但到了一定阶段，这种方式就会变得低效。你会不断重复同样的说明，人会累，代理的输出也会开始摇摆。

我觉得，技能的价值就在这里变得非常清楚。技能本质上就是一种 把重复解释变成结构 的方法。一旦整理好了，以后就可以用更短的指令重新调出同样的上下文。

把代理和技能想成木匠和厨师，就容易理解了#

如果你把技能这个概念放到木匠和厨师身上，会更容易理解。

代理是可以接活的专业人士#

木匠是处理木材的人。你让他做一个书架，他会自己判断材料、切割、组装和打磨的顺序。

厨师也类似。你让他做一份炒饭，他会从备料、火候到调味，把整个过程承担下来。

Claude Code 也是一样。它更像是软件领域里一个可以接任务的专业人士。无论是修 bug、实现 API、写文档，还是做重构，它都是按目标来处理工作的。

技能是专业人士在需要时调出来的细分技术#

木匠有锤钉、锯木、刨平这样的细分技术。厨师有刀工、翻炒、调味这样的细分技术。关键在于，这些技术不会永远一起启动，而是会在合适的时刻被调出来。

Claude Code 的技能也很像这样。

• 代码审查技能会告诉它应该先怀疑什么。
• API 实现技能会告诉它应该遵循什么包结构和 DTO 模式。
• 文档写作技能会告诉它应该用什么格式和语气。

也就是说，如果代理回答的是「谁来做这件事」，那么技能回答的就是「这件事在我们的方式里应该怎么做」。

技能在 Claude Code 里实际做了什么#

如果你只是把技能理解成「保存起来的 prompt」，其实有点可惜。它在实践中的作用比这更重要。

1. 它减少重复说明#

每个项目的规则都不同。目录结构不同，响应格式不同，审查标准也不同。技能会把这些重复说明集中到一个地方，所以代理不必每次都重新接受一次完整入职说明。

2. 它固定判断标准#

好的结果并不只是来自「知道很多的模型」。只有把先看什么、什么算风险、按什么顺序推进固定下来，质量才会稳定。技能就是把这些标准写下来的地方。

3. 它把相关资料一起打包#

真实工作里，只有正文说明往往不够。你还需要模板、参考文档、检查清单，甚至脚本。技能可以把这些东西一起连接起来，像一个小型执行包一样工作。

4. 它缩小了代理必须处理的范围#

如果你让代理毫无边界地面对一个巨大的代码库，它就很容易摇摆。相反，如果你给出一个边界，比如「这个任务按这些标准处理，并参考这些文档和模式」，它就会稳定得多。我觉得这也是技能最大的优点之一。

为什么不能只靠长 prompt 硬撑#

一开始，长 prompt 看起来是够用的。实际上在早期，它往往也是最快的办法。但随着项目变大，问题会慢慢出现。

第一，你会不断复制粘贴同样的说明。
第二，只要漏掉一点点，结果就会开始偏。
第三，这些知识不会真正沉淀给团队或未来的自己。

技能在这里带来的差异非常明显。一个做得好的技能不会停留在一次性的请求上，而会留下来成为一种 可复用的工作方式。好的 prompt 可以带来一次好的结果，好的技能则会提高好结果持续出现的概率。

技能通常会这样加载#

第一次听到技能时，很多人会问：「那是不是代理平时一直把所有技能都读在脑子里？」通常并不是这样。它更接近一种按需、分阶段加载的方式。

这个结构重要的原因很简单。就算技能很多，系统也不会天然变得很重。代理会先看名称和说明，判断哪些技能可能相关；正文和参考资料只有真正需要时才会继续读取。

所以，技能并不是一个越多越乱的功能。只要拆分得好，它反而会越来越容易使用。

应该先把什么工作做成技能#

不是所有工作都需要做成技能。相反，如果什么都想技能化，管理会变得更困难。我更建议先从符合这些条件的工作开始：

• 同样的请求已经重复过三次以上
• 结果形式或质量标准相对明确
• 项目特有的规则需要反复解释
• 步骤较多，顺序容易漏掉
• 出错的代价不低

比如下面这些工作，就是很适合的候选项：

• 代码审查
• API 端点实现
• 架构蓝图文档编写
• 面向前端的 handover 文档
• 博客文章写作与翻译

相反，那些真正一次性的请求，或者标准还经常变化的工作，还太早做成技能。技能更像是 重复判断的压缩版本，而不是灵感备忘录。

亲手做一个，理解会更快#

技能的存放位置和调用规则，会因为使用环境不同而稍有差异。不过结构通常都差不多。核心还是以 SKILL.md 为中心，把需要的参考资料放在旁边。

例如，可以是这样：

my-skill/
  SKILL.md
  references/
    checklist.md
  templates/
    output-template.md

而 SKILL.md 里一般会放这样的内容：

---
name: code-review
description: 보안, 회귀, 테스트 관점으로 코드 리뷰를 수행합니다.
---

# Code Review Skill

## 우선 확인할 것
- 입력 검증 누락
- 권한 체크 누락
- 회귀 가능성이 큰 변경
- 테스트 부재

## 리뷰 방식
- 문제를 먼저 적는다
- 왜 문제인지 설명한다
- 가능한 수정 방향을 함께 제안한다

真正重要的不是一上来就做得很宏大。要是从一开始就想搭一个巨大的框架，往往很难坚持下去。先找一个最常重复的请求，只整理出「这个任务应该按什么顺序、用什么标准处理」，其实就已经足够了。

不过在真实工作里，从一份空白的 SKILL.md 开始手写，往往比想象中更低效。一个好技能并不是起了名字就自动成形了。范围要收得多窄、输出格式要固定到什么程度、该连接哪些参考资料、要放什么例子，这些都需要非常细致的判断。

所以我通常更建议，先使用已经预加载好的 技能生成器。技能生成类技能会先帮你搭起基本结构，检查那些容易漏掉的项目，并减少一开始就做出过宽或过于模糊技能的风险。懂得手写当然有必要，但在实际工作里，先站在一个做得好的生成器上，通常会更快，也更稳定。

好技能和弱技能的差别#

好的技能，一读就知道它到底想做什么。弱的技能则常常是名字很大，但实际范围太宽，输出标准也很模糊。

好的技能通常有这些特点：

• 负责的任务边界窄而清楚
• 输出格式和完成条件明确
• 只连接真正需要的参考资料
• 示例贴近真实工作

而下面这些情况，会让技能很快变弱：

• 一个技能想包办太多角色
• 充满了「做好一点」「专业一点」这种抽象指令
• 参考文档太多，不知道该从哪里读起
• 项目已经变了，技能却还停留在旧规则里

归根结底，技能也是需要维护的对象。它不是做一次就结束，而是要在真实工作中不断打磨。

结尾#

我觉得，把技能理解为「给 AI 加的附加功能」并不算最准确。它更像是 人为了更好地指挥代理工作而整理出来的一套工作标准。

Claude Code 本身当然是聪明的。但聪明的代理，并不会自动就理解你的项目。技能填补的正是这段空白。只要把重复请求、固定的质量标准、团队语气和偏好的输出格式整理进技能里，代理就会少很多摇摆，也更容易给出真正像团队产出的结果。

如果你现在在用 Claude Code，而且越来越常觉得「说明越来越长，结果却还是不够稳定」，那往往就是一个适合开始做技能的时机。不过，与其一开始就独自手工设计一个很好的技能，我更建议先调用已经预加载好的 skill-creator 或其他技能生成类技能。生成器先把基础结构和检查点搭起来，人再往上叠加项目规则和团队语气，这样通常会高效得多。很多时候，你会发现整个工作方式就是从这里开始变化的。