构建 Claude Code 的经验：我们是如何使用 Skills 的

Skills 已经成为 Claude Code 中最常用的扩展能力之一。它们灵活、易于创建、也方便分发。

但正因为够灵活，反而很难一开始就知道什么方式最好：
什么类型的 Skills 值得做？一份好的 Skill 应该怎么写？什么时候适合分享给别人？

在 Anthropic，我们已经在 Claude Code 里大量使用 Skills，内部有上百个 Skill 在持续活跃使用。下面是我们在用 Skills 提升研发效率过程中，总结出来的一些经验。

什么是 Skills？

如果你对 Skills 还不熟悉，建议先看看我们的文档，或者观看最新的 Agent Skills 课程。下面的内容会默认你已经对 Skills 有基本了解。

一个常见的误解是：Skills “只是一些 markdown 文件”。
但 Skills 真正有意思的地方在于：它不仅仅是文本文件，而是一个“文件夹（目录结构）”。它可以包含脚本、资源文件、数据等等，这些内容都可以被 Agent 发现、浏览和操作。

在 Claude Code 中，Skills 还有丰富的配置能力（config options），包括注册各种动态 hooks。

我们发现，很多最有意思、最强大的 Skills，都是在“配置 + 目录结构”上玩出了花样。

Skills 的类型

在整理了我们现有的 Skills 之后，我们发现它们大致会聚集成一些反复出现的类别。最好的 Skills 往往能非常干净地归入其中一个类别；而那些容易让人困惑的 Skills，往往是“同时踩在好几个类别上”。

这不是一个“权威分类”，但很适合用来检查：你的组织里是不是还少了一些关键的 Skills。

1. 库 & API 参考类

这类 Skills 用来说明“如何正确使用某个库、CLI 工具或 SDK”。
它们既可以是你们内部的库，也可以是 Claude Code 偶尔会用不顺手的常见第三方库。

这类 Skills 往往会包含一个“参考代码片段”的文件夹，以及一份“写脚本时要避免的坑点清单”。

示例：

• ‎billing-lib —— 你的内部计费库：边界情况、易踩坑点等
• ‎internal-platform-cli —— 你们内部 CLI 封装的所有子命令及其使用示例
• ‎frontend-design —— 让 Claude 更懂你们的前端设计体系

2. 产品验证类

这类 Skills 描述“如何测试 / 验证你的代码是否真的跑对了”。
它们通常会和外部工具配合使用，比如 Playwright、tmux 等，用来执行验证。

验证类 Skills 对提升 Claude 产出的可靠性非常有用。
让工程师花一整周时间，把验证类 Skills 打磨好，往往是非常值得的。

可以考虑一些技巧，例如：

• 让 Claude 录屏，生成一段视频，方便你回看它实际测了什么；
• 在每一步都强制做“程序化断言”，检查状态是否符合预期。

这些通常通过在 Skill 中加入各种脚本来实现。

示例：

• ‎signup-flow-driver —— 在无头浏览器中跑完整的注册 → 邮箱验证 → 引导流程，并在每一步留出断言状态的 hook
• ‎checkout-verifier —— 驱动结账界面，用 Stripe 测试卡支付，验证最终发票是否进入正确状态
• ‎tmux-cli-driver —— 适用于需要 TTY 的交互式 CLI 测试场景

3. 数据获取 & 分析类

这类 Skills 用来连接你的数据和监控系统。
它们可能包含用凭证拉取你们数据的库、具体的看板 ID 等，以及对常用数据分析工作流的说明。

示例：

• ‎funnel-query —— 说明“哪些事件需要 join 才能看注册 → 激活 → 付费漏斗”，并给出包含 canonical ‎`user_id` 的具体表
• ‎cohort-compare —— 对比两个分群的留存或转化，标记统计显著的差异，并关联到具体的分群定义
• ‎grafana —— 数据源 UID、集群名称、从问题到对应监控看板的映射表

4. 业务流程 & 团队自动化类

这类 Skills 用一个命令就能串起一整套重复的业务流程。
通常它们本身的指令并不复杂，但可能依赖其他 Skills 或 MCPs。

对于这类 Skills，把之前执行结果写入日志文件会很有帮助，可以让模型保持一致性，并在多次执行间进行反思。

示例：

• ‎standup-post —— 聚合你的工单系统、GitHub 活动和历史 Slack，对比差异后生成当天的 standup，总结“增量”内容
• ‎create-<ticket-system>-ticket —— 强制遵守工单的字段约束（枚举值、必填项），并自动执行“创建后流程”（通知评审人、发 Slack 链接等）
• ‎weekly-recap —— 合并 PR、关闭的工单和上线记录，生成格式化的周报总结

5. 代码脚手架 & 模板类

这类 Skills 用来为代码库中的特定功能生成框架代码（boilerplate）。
你可以把它们和一些可组合的脚本一起使用，特别适合那些脚手架带有较多“自然语言要求”、无法完全通过纯代码模板覆盖的场景。

示例：

• ‎new-<framework>-workflow —— 按照你们约定的注解样式，搭新服务 / 工作流 / handler 的基础框架
• ‎new-migration —— 生成迁移文件模板并附带常见注意事项
• ‎create-app —— 新建内部应用，并预置好你们的鉴权、日志和部署配置

6. 代码质量 & Review 类

这类 Skills 用来在团队内统一代码质量，并辅助代码审查。
它们可以包含高度确定性的脚本或工具，以获得更稳定的表现。你甚至可以把它们挂在 hooks 或 GitHub Action 里自动运行。

示例：

• ‎adversarial-review —— 拉起一个“挑刺子 Agent”进行审查，提出修改意见，持续迭代直到剩下的只是“吹毛求疵级别”的建议
• ‎code-style —— 强制执行代码风格，尤其是那些 Claude 默认不太擅长遵守的风格
• ‎testing-practices —— 说明应该如何写测试，以及重点应该测什么

7. CI/CD & 部署类

这类 Skills 帮助你在代码库内获取、推送、部署代码。
它们也可能引用其他 Skills 来补齐所需信息。

示例：

• ‎babysit-pr —— 监控一个 PR → 重试不稳定的 CI → 处理合并冲突 → 自动开启 auto-merge
• ‎deploy-<service> —— 构建 → 冒烟测试 → 渐进式流量切换并对比错误率 → 发现回归自动回滚
• ‎cherry-pick-prod —— 创建隔离工作树 → cherry-pick → 解决冲突 → 提交带模板说明的 PR

8. Runbook 类

这类 Skills 接收一个“症状”（比如某条 Slack 线程、告警、错误签名），然后串起一系列工具进行排查，最终输出结构化的报告。

示例：

• ‎<service>-debugging —— 针对你们流量最大的服务，把常见症状映射到对应工具和查询模式
• ‎oncall-runner —— 拉取告警 → 检查“常见嫌疑人” → 形成结论说明
• ‎log-correlator —— 给定请求 ID，抓取所有可能关联系统的日志记录

9. 基础设施运维类

这类 Skills 负责常规维护和运维操作，其中有些动作具有破坏性，因此尤其需要“护栏（guardrails）”。
它们可以让工程师在执行关键操作时，更自然地遵循最佳实践。

示例：

• ‎<resource>-orphans —— 查找孤立的 pod / volume → 发消息到 Slack → 等待缓冲期 → 用户确认 → 级联清理
• ‎dependency-management —— 实现你们组织内部对依赖升级 / 引入的审批流程
• ‎cost-investigation —— 调查“为什么存储 / 流量账单突然飙升”，并列出具体 bucket 和查询模式

如何写好一个 Skill

一旦你决定要做一个 Skill，接下来关键的问题是：该怎么写？
下面是我们自己实践中总结出的若干最佳实践、小技巧和坑位提醒。

我们最近也发布了 Skill Creator，来帮助大家在 Claude Code 里更轻松地创建 Skills。

不要讲废话

Claude Code 对你的代码库已经有不少上下文，而 Claude 对编程本身也有很多“默认认知”和“偏好”。

如果你准备发布的是“知识型”的 Skill，请尽量聚焦在那些能“改变 Claude 默认思路”的信息上，而不是重复它早就知道的东西。

例如，frontend design 相关的 Skill，就是 Anthropic 的一位工程师在和客户反复迭代中打磨出来的，主要是为了提升 Claude 的设计品味，刻意规避诸如 Inter 字体、紫色渐变这类“经典套路”。

建一个 Gotchas 小节

在任何一个 Skill 里，“Gotchas” 部分往往是信息密度最高的地方。
这个小节应该是根据 Claude 实际使用 Skill 时频繁踩中的错误、误用或边界情况一点点积累起来的。

理想情况下，你会随着时间持续更新这个 Gotchas 清单，让它真正成为“经验库”。

利用文件系统 & 逐步披露

前面说过，Skill 是一个文件夹，而不仅仅是一份 markdown。
你可以把整个目录结构当成一种“上下文工程”和“分层信息披露”的手段。

只要你告诉 Claude 这个 Skill 里有哪些文件，它就会在合适的时候主动去读。

最简单的逐步披露方式，就是把详细内容拆到其他 markdown 文件中，让 Claude 在需要时再查看。比如你可以把详细的函数签名和使用示例拆到 ‎references/api.md。

再比如：如果最终输出是一个 markdown 文档，你可以在 ‎assets/ 里放一个模板文件，让 Claude 直接复制使用。

你也可以准备一整套“参考资料、脚本示例”等文件夹，帮助 Claude 更高效地完成工作。

不要把 Claude 绑死

Claude 通常会努力服从你的指令，而 Skills 又具备高度复用性，所以你需要小心不要把指令写得太死。

给 Claude 足够的信息，但也要留出空间，让它根据具体情况做调整和判断。
比如在一些示例中，我们会对比“过度具体的指令”和“更宽松但清晰的指令”，后者往往更好用。

认真想好 Setup 过程

有些 Skills 在使用前需要用户提供一些上下文配置。
比如：一个负责把 standup 发到 Slack 的 Skill，可能需要先问清楚应该发到哪个频道。

一个常用模式是：把这些配置信息写到 Skill 目录里的 ‎config.json 里。
如果发现 config 还没配置好，Agent 就可以先向用户询问必要信息。

如果你希望 Agent 以结构化、带多项选择的方式提问，可以指示 Claude 使用 AskUserQuestion 这个工具。

Description 字段是写给模型看的

当 Claude Code 启动一个新会话时，它会先罗列所有可用的 Skills 及其 description 字段。
Claude 会浏览这份列表，然后决定：“当前请求有没有相关的 Skill 可以用？”

这意味着：description 字段并不是“简介”，而更像是一句“触发条件的说明”。
你写 description 的时候，最好尽量清晰地回答：在什么情况下应该调用这个 Skill？

Memory & 数据存储

有些 Skills 自带一种“记忆功能”，就是在 Skill 内部持久化一些数据。

你可以使用最简单的“追加写入文本日志”或 JSON 文件，也可以用更复杂的 SQLite 数据库。

例如，一个 ‎standup-post Skill 可以维护一个 ‎standups.log，记录每次生成的 standup 内容。
这样下次再运行时，Claude 就可以先读这份历史，自动判断“和昨天相比有哪些变化”。

需要注意的是：存放在 Skill 目录里的数据，在你升级 Skill 时可能会被删除。
因此，更稳妥的做法是把数据存放在一个长期稳定的目录中。当前我们提供了 ‎${CLAUDE_PLUGIN_DATA}，作为每个插件独立的稳定存储位置。

存脚本 & 用代码放大能力

代码是你能交给 Claude 的最强工具之一。

如果你给 Claude 提供了脚本和库，它就能把“回合数”花在“做决策和编排”上，而不是每次都从零写样板代码。

例如，在你的数据科学 Skill 里，你可以准备一套从事件源拉数据的函数库。
然后再补充一些辅助函数，让 Claude 更容易组合使用它们：这样当你问“周二发生了什么？”之类的问题时，Claude 就可以在此基础上动态生成脚本，完成更复杂的分析。

按需启用的 Hooks

Skills 可以包含一些“按需启用的 hooks”：
只有在这个 Skill 被调用时才会激活，并持续整个会话。
对于那种“平时不想一直开着，但在某些场景又非常有用”的 hook，这类机制尤其合适。

例如：

• ‎/careful —— 通过 Bash 的 PreToolUse 匹配器拦截 ‎rm -rf、‎DROP TABLE、强制 push、‎kubectl delete等危险操作。只有当你意识到“现在会动到生产环境”时才希望打开这个保护，如果一直开着会非常烦。
• ‎/freeze —— 阻止任何对指定目录以外的 Edit/Write 操作。
  在调试时很有用：你只想加日志，但又总是不小心“顺手修了别的地方”。

分发 Skills

Skills 的一个巨大优势在于：你可以方便地与团队其他人共享这些能力。

通常有两种方式：

• 把 Skills 直接提交到代码仓库（放在 ‎./.claude/skills 目录下）
• 做成插件，在内部的 Claude Code 插件市场中上传和安装（可以参考文档中的说明）

对于规模不大的团队、代码仓库数量相对有限的情况，把 Skills 直接提交到仓库就很好用。
但要注意：每多一个 Skill，都会一点点增加模型需要考虑的上下文负担。
随着规模变大，搭建一个内部插件市场会更灵活 —— 你可以把 Skills 分发出去，让团队成员按需安装。

管理一个 Skill 市场

那该如何决定哪些 Skills 能进入市场？又如何让大家提交自己的 Skill 呢？

我们内部没有一个“集中审批”的团队；相反，我们更倾向于“让最有用的 Skills 自然浮出水面”。

一个简单的流程是：

1. 如果你有一个希望大家试用的 Skill，可以先上传到 GitHub 里的一个 sandbox 目录；
2. 然后在 Slack 或其他内部渠道中分享链接，邀请同事试用；
3. 当这个 Skill 获得足够的“认可度”（标准由 Skill 的维护人自己把握）时，就可以提 PR，把它从 sandbox 移到正式的 marketplace 中。

需要提醒的一点是：做出“质量一般甚至有点多余的 Skills”非常容易，所以在正式发布前，最好有一套基本的“筛选与整理机制”。

组合 Skills

有时你会希望一个 Skill 依赖另一个 Skill。
比如：你可能有一个“文件上传” Skill，负责把文件上传到某个地方；
再有一个“生成 CSV 并上传”的 Skill，它就会调用前者完成上传。

目前，无论在 Skills 还是市场层面，这种依赖管理都还没有“原生机制”。
但你完全可以在 Skill 的说明里用名称引用其他 Skills —— 只要这些 Skills 已安装，模型就能按名称调用它们。

如何度量 Skills 的效果

为了解一个 Skill 的实际表现，我们会使用一个 PreToolUse hook 来记录公司内部的 Skill 使用情况。

这样我们就能：

• 找出最受欢迎的 Skills；
• 或者发现某些理论上很有用但实际“触发率偏低”的 Skills，并据此优化 description 或使用方式。

总结

Skills 是为 Agent 赋能的一组非常强大且灵活的工具，但现在仍处在一个“大家一起摸索最佳实践”的早期阶段。

你可以把上面这些内容看成一袋“随手可用的小技巧”，而不是一份“权威指南”。
理解 Skills 的最好方式，就是先动手做起来，多实验、多迭代，看看什么对你们团队最有效。

我们自己的很多 Skills 一开始都只是几行文字和一个 Gotcha，后来之所以变得越来越好，是因为大家在 Claude 不断碰到新边界时，持续地往里补充经验。

希望这些分享对你有所帮助。

原文：“Lessons from Building Claude Code: How We Use Skills”, Thariq Shihipar