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，踩过的坑也可以慢慢沉淀下来，成为下一次任务的一部分。
参考资料
Anthropic Blog《Lessons from building Claude Code: How we use skills》
