Claude Code 团队上周写了一篇文章，来讲述他们在内部是如何使用 Skills 的。借着他们这篇分享，我们来讲讲 Skill 是什么，以及如何参考 Claude Code 团队的经验来打造我们自己的好用 Skill。

在 Claude Code 的 Skill 实践文章中，Skill 的定义比较接近一个给 Agent 使用的任务经验包：把一类任务里反复用到的说明、脚本、模板、配置和坑点，整理成一个可以被 Claude 发现和调用的文件夹。

而 Skills 也成了 Claude Code 最常用的扩展点之一。这不难理解，它创建起来不复杂、使用灵活，在团队里分发也很方便。Anthropic 内部在用的 Skill 已经有数百个，现在来看看他们有什么最佳实践可以分享给我们。

Skills 不是一个 Markdown 文件

第一次看到 Skills，我们容易把它理解成一份提示词，或是一个 SKILL.md 文件。但 Skill 其实是一个文件夹，里面可以放 instructions、scripts、assets、data 等内容，Claude Code、Codex、OpenClaw、Hermes Agent 这类支持 Skills 的 Agent 工具，可以在执行任务时发现、读取和使用这些资源。

真实项目中的大多数经验，我们其实很难靠一段提示词说清楚。某个内部 CLI 有哪些子命令，某个支付流程要怎么验证，某张表哪个字段才是标准 user_id，CI 挂了以后应该先看哪里，生产环境相关操作有哪些限制。这些东西往往分散在文档、代码、群聊和多个人的记忆中，人类工程师可能知道这东西是怎么样运作的，但 Agent 每次干活就要重新猜了。

Skills 能把这些分散的经验收拢到一个明确的地方。一旦 Agent 遇到类似任务，就可以先看这个 Skill 中的说明文件，再按里面的脚本、模板和排查步骤去执行。它的作用不是让 prompt 写得更漂亮，而是让 Agent 少猜一点，多复用一点已经沉淀下来的项目经验。

图注：Skill 不是单个 Markdown 文件，而是一个可以包含文档、脚本、模板和资源的文件夹

Claude 内部的 9 类 Skill

Claude Code 团队梳理了内部的 Skills，发现它们大致可以分成 9 类。当然，这不是一个最终标准，但是很适合用来理解 Skills 可以放什么内容。

第一类是 库和 API 参考。像是 Claude 内部的 billing library 有哪些边界情况、内部 CLI 支持哪些子命令、某个 SDK 应该怎么正确调用。

这类 Skill 主要解决的是“Claude 知道怎么写代码，但不知道你们这个库有什么特殊用法”的问题。很多团队内部工具都有自己的约定和历史包袱，如果不提前写清楚，Agent 很容易按照通用经验去猜，最后写出看似合理但实际不能用的代码。

第二类是 产品验证。这类 Skill 会告诉 Claude 怎么确认功能真的跑通了，像是用 Playwright 跑完整注册流程，用 Stripe 测试卡验证 checkout 状态，或是用 tmux 测试那些需要真实终端环境的交互式 CLI。

它的重点是让 Agent 不要停在“代码写完了”，而是继续走到“功能真的验证过了”。验证类 Skills 对 Claude 内部输出质量的提升是最明显的，甚至值得让工程师专门花时间把它做好。

第三类是 数据分析，这类 Skill 会告诉 Claude 如何连接数据仓库、监控系统、Grafana、Datadog，也会说明哪些表能查、字段怎么对应、dashboard 在哪里。

这类 Skill 适合沉淀团队里的数据口径，避免 Agent 查错表、看错字段，或者把不同系统里的指标混在一起解释。

第四类是 业务流程和团队自动化，像是生成例会、创建 ticket、整理每周回顾。它解决的是那些重复出现、格式相对固定，但每次又需要结合上下文整理的信息流任务。

第五类是 代码脚手架和模板，像是创建新服务、新迁移、新内部应用，把认证、日志、部署配置这些固定内容提前接好。这样 Claude 创建新项目时，就不用从零开始猜团队的工程结构。

第六类是 代码质量和 review，代码风格、测试规范，或者让一个新的 subagent 做代码审查。这类 Skill 可以把团队在 code review 里反复强调的规则，变成 Agent 执行任务时会主动参考的检查项。

第七类是 CI/CD 和部署，盯 PR、重试偶发失败的 CI、解决合并冲突、跟进灰度发布和回滚，都属于这一类。它更偏向把开发流程里的后半段交给 Agent 跟进，尤其适合那些步骤明确、但人工盯起来很耗时间的任务。

第八类是 故障处理，也就是把报警、Slack 线程、错误日志等问题现象，转成一套可排查的流程。先查哪个 dashboard，再看哪类日志，最后按什么格式输出结论。它的价值在于减少临场排查时的混乱，让 Agent 按既定顺序推进。

第九类是 基础设施运维，像是清理孤立资源、依赖管理、成本排查，以及一些需要保护规则的高风险操作。这类 Skill 尤其需要把边界写清楚，哪些命令可以自动执行，哪些操作必须先让人确认，都应该提前放进说明里。

避坑指南

Anthropic 在文章里提到，写 Skill 时不要重复 Claude 本来就知道的内容。像是“代码要可读”“测试要覆盖关键路径”“注意错误处理”这类要求， Claude 默认也知道，把它们写进 Skill 里，只会占用上下文。

对于项目而言，真正有价值的是当中的特殊情况，也就是 gotchas。

像是 subscriptions 表是 append-only，查订阅状态时要取 version 最高的那一行，而不是最近创建的那一行；API gateway 里叫 @request_id，billing service 里叫 trace_id，但它们其实指向同一个值；staging 返回 200，不代表 Stripe webhook 真的处理成功，还要去 payment_events 查真实状态…

这些内容看起来很琐碎，但正是 Agent 最容易踩坑的地方。 一个好的 Skill 不一定一开始就很复杂，它可以先从几行说明和一个坑点开始。之后每次 Claude 做错了，就把新的经验补进去。这样 Skill 会慢慢从“提醒 Claude 做什么”，变成“记录 Claude 在这个项目里曾经错过什么”。

文件结构是上下文

这里还有一个很实用的 Skill 写法：不要把所有东西都塞进 SKILL.md，可以把文件系统本身当成一种渐进式上下文。 SKILL.md 只负责告诉 Claude 这个 Skill 适合什么场景，以及不同情况应该去读哪些文件。

举个例子，你可以把详细的 API 签名放到 references/api.md，输出模板放到 assets/，排查待办 job 的方法单独放到 stuck-jobs.md。Claude 不用一开始就读取所有内容，只要在任务需要时再去看对应文件就够了。

这和 Agent 的工作方式很匹配。你给 Agent 一整本手册，它可能会抓不住重点。但你告诉它“遇到 A 情况去看 A 文件，遇到 B 情况去看 B 文件”，它就会按需使用上下文了。

写给模型看的 description

Skill 还有一个容易被忽略的细节：description 不是写给人看的说明，而是写给 Claude 判断“什么时候应该调用这个 Skill”的触发条件。

Claude Code 启动 session 时，会构建一份可用 Skills 列表，并扫描每个 Skill 的 description，判断当前请求是否匹配。description 是一个触发说明，而不是一句产品介绍。

一个负责盯 PR 的 Skill，description 里最好出现 “babysit PR”“monitor CI”“retry flaky tests” 这类具体触发词。这样用户说“帮我盯一下这个 PR”时，Claude 更容易想起它。如果 description 写成“这个 Skill 可以提高开发效率”，模型反而很难判断什么时候该用。

图注：官方给出的示例

带记忆的 Skill

有些 Skill 还可以保存历史记录。

官方举了一个 standup-post 的例子：它可以把每次生成过的站会存到 standups.log，下次再运行时，Claude 就能读取之前的记录，知道今天和昨天相比发生了什么变化。

这个设计很朴素，但有用。很多团队开会流程之一，是要和上一次的例会进行对比，看看这次新增了什么、这个 PR 上次卡在哪里、昨天的报警有没有重复出现、本周和上周相比有哪些变化。把这些历史结果存在 Skill 里，Agent 执行同类任务时就能获得一点历史记录，保持会议的连续性。

当然，这里的“记忆”不用理解得太复杂。它可以只是一个 append-only 文本日志、JSON 文件，也可以是 SQLite 数据库。重点是让 Skill 不只保存规则，也能保存这个任务过去执行过的结果。

团队如何分发 Skill

在分发方式上，Anthropic 提到两种常见路径。第一种是直接把 Skills 放进代码仓库，比如 ./.claude/skills，这适合小团队或者项目数量不多的情况。第二种是做成 plugin，通过内部 marketplace 分发。团队规模变大后，每个人不一定需要安装所有 Skills，marketplace 可以让大家按需安装，也方便做配置流程。

Anthropic 内部的做法也比较轻。他们没有一个中心团队专门决定哪些 Skills 能进 marketplace，而是先让大家把 Skill 放到 GitHub 的 sandbox 目录，再通过 Slack 等渠道让别人试用。等它真的有人用、有价值，再通过 PR 移到 marketplace。

这很有参考性。Skills 本来就是从具体任务里长出来的，不需要一开始就设计成大而全的规范。先解决一个小问题，真的有人用，再慢慢补坑点、补脚本、补模板，反而更符合它的使用方式。

小结

Skills 可以理解成 Claude Code 给 Agent 准备的任务经验包。它把一类任务里反复出现的说明、脚本、模板、配置、坑点和历史记录放在一起，让 Claude 下次遇到类似任务时，可以直接复用已有经验。

我们要创建自己的 Skill 时，可以先从很小的 Skill 开始，把 Claude 经常写错的项目规则、常用脚本、输出模板和测试方式放进去。对团队来说，Skills 更像一种轻量的经验分发方式：工程师不用每次都手把手提醒 Agent，踩过的坑也可以慢慢沉淀下来，成为下一次任务的一部分。