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

本文译自 Anthropic 官方博客《Lessons from building Claude Code: How we use skills》，作者 Thariq Shihipar。原文链接见文末作者署名。

Skills 的类型

在梳理完 Anthropic 内部所有的 Skills 之后，我们发现它们大致可以归为九类。优秀的 Skill 通常能干净地归入其中一类；而那些试图做太多事情的 Skill 往往会横跨好几类，反而会让模型困惑。这并不是一份权威清单，但它是一个很有用的框架，可以帮助你发现自己 Skills 库里的空白。

Claude Code 团队把内部 Skills 归类后发现，它们可以分成九个不同的类别。

1. 库与 API 参考

这类 Skill 解释如何正确使用某个库、CLI 或 SDK。它们既可以针对内部库，也可以针对那些 Claude Code 有时处理得不够好的常见库。这类 Skill 通常会附带一个参考代码片段文件夹，以及一份让 Claude 在编写脚本时避坑的注意事项列表。

示例：

• billing-lib —— 你内部的计费库：边界情况、容易踩的坑等。
• internal-platform-cli —— 你内部 CLI 封装的每一个子命令，并附上何时使用它们的示例。
• sandbox-proxy —— 为开发工作配置组织的出口网关：哪些主机可达、如何排查 “connection refused” 错误、如何添加一条白名单。

2. 产品验证

这类 Skill 描述如何测试或验证你的代码是否正常工作。它们通常会配合 Playwright、tmux 或其他外部工具来做验证。

在内部，验证类 Skill 对 Claude 输出质量的提升最为明显。值得让一位工程师专门花上一周时间，把你的验证 Skill 打磨好。

可以考虑一些技巧，比如让 Claude 把它的输出录成视频，这样你能清楚看到它到底测了什么；或者在每一步对状态施加程序化的断言。这些通常是通过在 Skill 里包含一系列脚本来实现的。

示例：

• signup-flow-driver —— 在无头浏览器里跑完 注册 → 邮箱验证 → 引导流程 的全过程，并在每一步带上用于断言状态的 hook。
• checkout-verifier —— 用 Stripe 测试卡驱动结账界面，验证发票确实落到了正确的状态。
• tmux-cli-driver —— 用于交互式 CLI 测试，当你验证的东西需要一个 TTY 时使用。

3. 数据获取与分析

这类 Skill 连接到你的数据和监控体系。它们可能包含带凭证去获取数据的库、具体的 dashboard id 等，以及关于常见工作流或取数方式的说明。

示例：

• funnel-query —— “我要 join 哪些事件才能看到 注册 → 激活 → 付费”，以及那张真正持有规范 user_id 的表。
• cohort-compare —— 比较两个群组的留存或转化，标记出统计上显著的差异，并链接到分段的定义。
• grafana —— 数据源的 UID、集群名、从问题到 dashboard 的对照表。
• datadog —— 字段参考（@request_id vs trace_id）、服务列表、指标前缀约定。

4. 业务流程与团队自动化

这类 Skill 把重复的工作流自动化成一条命令。它们的指令通常相当简单，但可能会依赖其他 Skill 或 MCP。对于这类 Skill，把之前的结果存进日志文件，能帮助模型保持一致，并对工作流此前的执行情况进行反思。

示例：

• standup-post —— 汇总你的工单系统、GitHub 动态和此前的 Slack 内容，生成格式化的站会纪要，且只显示增量。
• create-<ticket-system>-ticket —— 强制校验 schema（合法的枚举值、必填字段），外加创建后的工作流（@ 评审人、在 Slack 里贴链接）。
• weekly-recap —— 已合并的 PR + 已关闭的工单 + 发布，生成格式化的周报。

5. 代码脚手架与模板

这类 Skill 为代码库里某个特定功能生成框架样板代码。你可以把它们和可组合的脚本结合起来用。当你的脚手架带有无法纯粹用代码覆盖的自然语言需求时，它们尤其有用。

示例：

• new-<framework>-workflow —— 用你的注解脚手架出一个新的 service/workflow/handler。
• new-migration —— 你的迁移文件模板，外加常见的坑。
• create-app —— 新的内部应用，预置好你的鉴权、日志和部署配置。

6. 代码质量与评审

这类 Skill 在组织内部强制代码质量，并帮助评审代码。它们可以包含确定性脚本或工具，以获得最大的稳健性。你可能会想把这些 Skill 作为 hook 的一部分自动运行，或放进一个 GitHub Action 里。

• adversarial-review —— 派生一个全新的 subagent 来挑刺，落实修复，反复迭代，直到发现的问题降级成吹毛求疵。
• code-style —— 强制代码风格，尤其是 Claude 默认做得不好的那些风格。
• testing-practices —— 关于如何写测试、该测什么的说明。

7. CI/CD 与部署

这类 Skill 帮你在代码库里拉取、推送和部署代码。它们可能会引用其他 Skill 来收集数据。

示例：

• babysit-pr —— 盯住一个 PR，重试不稳定的 CI，解决合并冲突，启用自动合并。
• deploy-<service> —— 构建 → 冒烟测试 → 逐步放量并对比错误率 → 出现回退时自动回滚。
• cherry-pick-prod —— 隔离的 worktree → cherry-pick → 解决冲突 → 用模板建 PR。

8. 运维手册（Runbooks）

这类 Skill 接收一个症状（比如一段 Slack 讨论、一条告警，或一个错误签名），走完一次多工具的调查，并产出一份结构化的报告。

示例：

• <service>-debugging —— 为你的高流量服务，把 症状 → 工具 → 查询模式 对应起来。
• oncall-runner —— 拉取告警，检查常见的嫌疑对象，格式化出一条发现。
• log-correlator —— 给定一个 request ID，从每一个可能接触过它的系统里拉取匹配的日志。

9. 基础设施运维

这类 Skill 执行例行维护和操作流程，其中一些涉及需要护栏的有破坏性的操作。它们让工程师在关键操作中更容易遵循最佳实践。

示例：

• <resource>-orphans —— 找出孤立的 pod/卷 → 发到 Slack → 缓冲观察期 → 用户确认 → 级联清理。
• dependency-management —— 你组织的依赖审批工作流。
• cost-investigation —— “为什么我们的存储/出口账单突然飙升”，附上具体的 bucket 和查询模式。

编写 Skill 的技巧

一旦你决定要做一个 Skill，该怎么写它？下面是 Claude Code 团队在制作 Skill 时的一些最佳实践、技巧和窍门。

别说显而易见的事

Claude 已经会写代码，也能读你的代码库。一个只是复述 Claude 默认行为的 Skill，只会增加上下文却不增加价值。如果你要发布的是一个以知识为主的 Skill，那就把重点放在那些能把 Claude 推离它惯常思维方式的信息上。

前端设计 Skill 就是一个很好的例子——它由 Anthropic 的一位工程师通过和客户反复迭代、改善 Claude 的设计品味而打造，刻意避开了 Inter 字体、紫色渐变这类老套路。

建立一个"易踩的坑"小节

任何 Skill 里信号最强的内容就是"易踩的坑（gotchas）“小节。这些小节应当从 Claude 在使用你的 Skill 时遇到的常见失败点中逐步积累起来。理想情况下，你会随着时间推移不断更新你的 Skill，把这些坑记录下来。

例如：

“subscriptions 表是只追加（append-only）的。你要找的那一行是版本号最高的那行，而不是 created_at 最近的那行。” “这个字段在 API 网关里叫 @request_id，在计费服务里叫 trace_id。它们是同一个值。” “Staging 环境即使在 Stripe webhook 没有真正处理时也会返回 200。去 payment_events 里看真实状态。”

使用文件系统与渐进式披露

SKILL.md 文件会指向若干其他文件，Claude 可以在特定情况下参考它们。例如，如果某个 job 处于 pending 状态，它就应当去参考 stuck-jobs.md。

就像我们前面说的，一个 Skill 是一个文件夹，而不只是一个 markdown 文件。你应当把整个文件系统都看作一种上下文工程和渐进式披露（progressive disclosure）。告诉 Claude 你的 Skill 里有哪些文件，它会在合适的时机去读它们。

渐进式披露最简单的形式，是让 Claude 去参考其他 markdown 文件。例如，你可以把详细的函数签名和使用示例拆分到 references/api.md 里。

另一个例子：如果你的最终产物是一个 markdown 文件，你可以在 assets/ 里放一个模板文件，供 Claude 复制和使用。

你可以有放参考、脚本、示例等的文件夹，这些都能帮 Claude 更高效地工作。

不要把 Claude 钉死在固定流程里

Claude 通常会尽量遵循你的指令，而正因为 Skill 是如此可复用，你在写指令时要小心别写得太具体。给 Claude 它需要的信息，但也要给它适应具体情况的灵活性。

例如：

把初始化流程想清楚

上面这个 Skill 被写成：如果配置里没有包含 Slack 频道，就向用户发问。

有些 Skill 可能需要用户提供一些上下文来完成初始化。例如，如果你做一个把站会发到 Slack 的 Skill，你可能想让 Claude 问一句要发到哪个 Slack 频道。

一个不错的做法，是把这类初始化信息存进 Skill 目录里的一个 config.json 文件，就像上面那个例子。如果配置还没设置好，agent 就可以向用户索要信息。

如果你想让 agent 以结构化的、多选的方式提问，可以指示 Claude 使用 AskUserQuestion 工具。

给模型写 description，而不是给人写

当 Claude Code 启动一个会话时，它会构建一份所有可用 Skill 及其 description 的清单。Claude 扫描这份清单来决定"这个请求有没有对应的 Skill？“这就意味着，description 字段不是一个摘要，而是关于"何时该触发这个 Skill"的描述。

在 description 里写上这个 Skill 的触发词是很有帮助的，比如 “babysit”。

帮 Claude 记住

这个文本日志文件帮 Claude 记住过去的事件，比如评审过 Sarah 的鉴权 PR。

有些 Skill 可以通过在自身内部存储数据，来带上一种记忆形式。你可以把数据存在简单如一个只追加的文本日志文件或 JSON 文件里，也可以复杂到一个 SQLite 数据库。

例如，一个 standup-post Skill 可以保留一个 standups.log，记录它写过的每一篇站会纪要，这意味着下一次运行时，Claude 会读自己的历史，并能说出从昨天到现在发生了什么变化。

你可以使用环境变量 ${CLAUDE_PLUGIN_DATA} 来获得一个稳定的目录用于存放数据，更多关于在 Skill 中持久化数据的内容见 plugins 参考文档。

存放脚本并生成代码

你能给 Claude 的最强大工具之一就是代码。给 Claude 脚本和库，能让 Claude 把它的回合花在组合上——决定下一步做什么——而不是重新构造样板代码。

例如，在你的 data-science Skill 里，你可能有一组函数库用来从事件源取数。为了让 Claude 做更复杂的分析，你可以给它一组像这样的辅助函数：

随后，Claude 可以即时生成脚本，把这些功能组合起来，针对"周二发生了什么？“这类提示做更高级的分析。

使用按需 hook

Skill 可以包含只在 Skill 被调用时才激活、并且只在该会话期间生效的 hook。可以用它来实现那些你不想一直运行、但有时极其好用的、更有主见的 hook。

例如：

• /careful —— 通过 Bash 上的 PreToolUse 匹配器拦截 rm -rf、DROP TABLE、force-push、kubectl delete。你只在自己知道要碰生产环境时才想要它——一直开着会让人抓狂。
• /freeze —— 拦截任何不在某个特定目录里的 Edit/Write。在调试时很有用：“我只想加日志，却总忍不住去’修’一些无关的代码。”

分发 Skills

Skill 最大的好处之一，就是你可以把它们分享给团队其他人。

你有两种方式把 Skill 分享给别人：

• 把你的 Skill 提交进仓库（放在 ./.claude/skills 下）。
• 做成一个 plugin，并搭一个 Claude Code Plugin marketplace，让用户上传和安装 plugin（详见 plugins 文档）。

对于在相对较少的仓库上协作的小团队来说，把 Skill 提交进仓库就挺好用。但每多提交一个 Skill，也会给模型的上下文增加一点点负担。随着规模扩大，一个内部的 plugin marketplace 能让你分发 Skill、让团队自己决定装哪些，并且还能带上一个初始化流程。

管理 Skills 市场

你怎么决定哪些 Skill 进入 marketplace？大家又怎么提交它们？

在 Anthropic，我们没有一支集中决定这件事的团队；相反，我们尽量以有机的方式找出最有用的 Skill。如果有人有一个想让别人试试的 Skill，他们可以把它上传到 GitHub 上的一个 sandbox 文件夹，然后在 Slack 或其他渠道里指给大家看。

一旦一个 Skill 有了些热度（这由 Skill 的所有者自己判断），他们就可以提一个 PR，把它搬进 marketplace。

组合 Skills

你可能想要彼此依赖的 Skill。例如，你可能有一个上传文件的 Skill，以及一个生成 CSV 并把它上传的 Skill。这种依赖管理目前在 marketplace 或 Skill 里还不是原生内建的，但你可以直接按名字引用其他 Skill，只要它们已安装，模型就会调用它们。

度量 Skills

为了了解一个 Skill 用得怎么样，我们用一个 PreToolUse hook 把公司内部的 Skill 使用情况记录下来（原文附有示例代码）。这意味着我们能找出那些很受欢迎的 Skill，或者那些与我们的预期相比触发不足的 Skill。

开始上手

Skill 的最佳实践仍在演进。我们最好的那些 Skill 大多起步于寥寥几行和单个坑，然后随着 Claude 不断撞上新的边界情况，被人们持续补充而变得更好。

理解 Skill 最好的方式，就是动手开始、去实验、看看什么对你有效。

• 看看我们的 Skills 文档。
• 找一些示例 Skill 来做定制。

本文作者为 Thariq Shihipar，Anthropic 技术团队成员，从事 Claude Code 相关工作。