开发 Claude Code 的启示：技能使用宝典（Skills）

神译局是36氪旗下编译团队，关注科技、商业、职场、生活等领域，重点介绍国外的新技术、新观点、新风向。

编者按：别把智能体当万能药：Anthropic拆解数百个内部技能，真正的提效密码藏在这9类底层框架里。文章来自编译。

技能已成为 Claude Code 中最常用的扩展点之一。因为技能灵活、易于制作且易于分发。

但这种灵活性也让人很难确定什么才是最佳实践。什么样的技能才值得制作？如何组织一个技能的架构？什么时候应该与他人分享这些技能？

在 Anthropic，我们一直在广泛使用 Claude Code 中的技能，目前有数百个技能处于活跃使用状态。以下是我们学到的关于利用技能加速开发的经验。

什么是技能？

技能是包含指令、脚本和资源的文件夹，智能体（Agent）可以发现并利用它们来更准确、更高效地执行任务。本篇博文假设您已了解技能的基础知识。

我们经常听到一个关于技能的误解，认为它们“只是 Markdown 文件”。实际上，它们是文件夹，可以包含脚本、资产、数据等，智能体可以去发现、探索和操作这些内容。

在 Claude Code 中，技能还拥有丰富的配置选项，包括注册动态钩子（Hooks）。

我们发现，Claude Code 中一些最高效的技能都充分利用了这些配置选项和文件夹结构。

技能的类型

在对 Anthropic 内部的所有技能进行归类编目后，我们发现它们可以归纳为九大类。最优秀的技能往往很纯粹，就属于其中某一类；而那些试图做太多的技能则会横跨多个类别，从而让智能体感到困惑。这并不是一个绝对的清单，但它是一个非常有用的框架，可以用来发现你自己的技能库中还缺少什么。

Claude Code 团队对我们的内部技能进行了分类，发现它们可以被归入九个不同的类别。

1. 库与 API 参考

这类技能用于解释如何正确使用某个库、CLI 或 SDK。它们既可以针对内部库，也可以针对 Claude Code 有时难以处理的公共库。这些技能通常包含一个参考代码片段文件夹，以及一份供 Claude 在编写脚本时需要注意的避坑指南（Gotchas）。

示例包括：

• `billing-lib` —— 你的内部计费库：边缘情况、容易踩坑的地方等。

• `internal-platform-cli` —— 内部 CLI 封装器的每个子命令，并附带何时使用的示例。

• `sandbox-proxy` —— 为开发工作配置组织的出口网关：哪些主机是可达的、如何调试“连接被拒绝”错误、如何添加白名单条目。

2. 产品验证

这类技能描述了如何测试或验证你的代码是否正常工作。它们通常与 Playwright、Tmux 或其他外部验证工具配合使用。

在内部，验证技能对提升 Claude 的输出质量有着最明显的量化效果。让一名工程师花上一周时间专门把验证技能做到极致是非常值得的。

可以考虑采用一些技术，比如让 Claude 录制其输出的视频，以便你能准确看到它测试了什么，或者在每一步对状态强制执行程序化断言。这些通常是通过在技能中包含各种脚本来实现的。

示例包括：

• `signup-flow-driver` —— 在无头浏览器中运行“注册 → 邮箱验证 → 新手引导”流程，并带有在每一步断言状态的钩子。

• `checkout-verifier` —— 使用 Stripe 测试卡驱动结账 UI，验证发票是否真正进入了正确的状态。

• `tmux-cli-driver` —— 用于交互式 CLI 测试，适用于你所验证的对象需要 TTY（终端）的情况。

3. 数据获取与分析

这类技能可以将智能体连接到你的数据和监控技术栈。这些技能可能包括带有凭证的数据获取库、特定的仪表盘 ID 等，以及关于常见工作流或数据获取方式的指令。

示例包括：

• `funnel-query` —— “我需要关联哪些事件才能看到 注册 → 激活 → 付费 流程”，以及实际包含标准 `user_id` 的表格。

• `cohort-compare` —— 比较两个群组（Cohorts）的留存率或转化率，标记具有统计学显著差异的偏差，并链接到细分群体定义。

• `grafana` —— 数据源 UID、集群名称、“问题 → 仪表盘”的查找表。

• `datadog` —— 字段参考（如 `@request_id` 与 `trace_id` 的区别）、服务列表、指标前缀规范。

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

这类技能可以将重复的工作流自动化为一条命令。这些技能的指令通常相当简单，但可能对其他技能或 MCP（模型上下文协议）有更复杂的依赖。对于此类技能，将之前的结果保存在日志文件中可以帮助模型保持一致性，并对工作流的往期执行进行反思。

示例包括：

• `standup-post` —— 聚合你的工单追踪器、GitHub 动态以及之前的 Slack 信息 → 生成格式化的每日站会报告（仅限增量变化）。

• `create-<ticket-system>-ticket` —— 强制执行 Schema 规范（合法的枚举值、必填字段）以及创建后的工作流（提醒评审人员、在 Slack 中发链接）。

• `weekly-recap` —— 已合并的 PR + 已关闭的工单 + 已部署的内容 → 生成格式化的周报帖子。

5. 代码脚手架与模板

这类技能用于为代码库中的特定功能生成框架样板代码。你可以将这些技能与可组合的脚本结合使用。当你的脚手架包含无法纯粹用代码表达的自然语言要求时，它们尤其有用。

示例包括：

• `new-<framework>-workflow` —— 带有你的自定义注解，为新服务/工作流/处理器生成脚手架。

• `new-migration` —— 你的数据库迁移文件模板以及常见大坑。

• `create-app` —— 创建新的内部应用，并预先配置好你的认证、日志和部署设置。

6. 代码质量与评审

这类技能用于在组织内部强制执行代码质量标准并辅助代码评审。它们可以包含确定性的脚本或工具，以实现最大的鲁棒性。你可能希望将这些技能作为钩子的一部分或在 GitHub Action 内部自动运行。

• `adversarial-review` —— 派生出一个扮演“挑剔旁观者”的子智能体来进行批判、实施修复，并不断迭代，直到发现的问题只剩下细枝末节的挑剔。

• `code-style` —— 强制执行代码风格，尤其是 Claude 默认做得不够好的风格。

• `testing-practices` —— 关于如何编写测试以及应该测试什么的具体指南。

7. CI/CD 与部署

这类技能可以帮助你在代码库中拉取、推送和部署代码。这些技能可能会引用其他技能来收集数据。

示例包括：

• `babysit-pr` —— 盯紧某个 PR → 重试不稳定的 CI → 解决合并冲突 → 启用自动合并。

• `deploy-<service>` —— 构建 → 冒烟测试 → 结合错误率对比进行渐进式流量分发 → 出现回退时自动回滚。

• `cherry-pick-prod` —— 隔离的工作区（Worktree） → Cherry-pick → 冲突解决 ——> 使用模板提交 PR。

8. 运维手册（Runbooks）

这类技能以某种异常现象（如 Slack 讨论串、告警或错误特征）作为输入，通过多个工具进行逐步排查，并最终生成一份结构化的报告。

示例包括：

• `<service>-debugging` —— 针对流量最高的服务，将异常现象映射到对应的工具和查询模式。

• `oncall-runner` —— 获取告警 → 检查常见排查点 → 格式化输出发现的问题。

• `log-correlator` —— 给定一个请求 ID，从每一个可能接触过该请求的系统中提取出匹配的日志。

9. 基础设施运维

这类技能用于执行日常维护和操作流程，其中一些涉及破坏性操作，能从设置的护栏（Guardrails）中受益。这使得工程师在进行关键操作时更容易遵循最佳实践。

示例包括：

• `<resource>-orphans` —— 寻找孤儿 Pod/卷 → 发布到 Slack → 观察期 → 用户确认 → 级联清理。

• `dependency-management` —— 组织内的依赖项审批工作流。

• `cost-investigation` —— “为什么我们的存储/出站流量费用激增”，并附带特定的存储桶和查询模式。

制作技能的技巧

一旦你决定了要制作什么技能，该如何编写它呢？以下是 Claude Code 团队在制作技能时总结出的一些最佳实践、提示和诀窍：

不要陈述显而易见的事实

Claude 已经懂得如何编写代码并且能够阅读你的代码库。一个只是重申 Claude 默认就会做的事情的技能，只会增加上下文的负担而无法带来任何价值。如果你要发布一个以知识为主的技能，请把焦点放在那些能把 Claude 拽出其常规思维模式的信息上。

前端设计技能就是一个极好的例子；它是由 Anthropic 的一位工程师通过与客户反复迭代构建的，旨在提升 Claude 的设计品味，避免像 Inter 字体和紫色渐变这类陈旧的设计套路。

建立一个“踩坑指南”章节

任何技能中信息密度最高的内容都是“踩坑指南（Gotchas）”部分。这些章节应当根据 Claude 在使用该技能时遇到的常见失败点来逐步构建。理想情况下，你应该随着时间的推移不断更新你的技能，以捕获这些新出现的大坑。

比方说：

“订阅表是只增不改（Append-only）的。你需要的行是版本号（version）最高的那一行，而不是最近创建的 `created_at`。”

“这个字段在 API 网关中被称为 `@request_id`，而在计费服务中被称为 `trace_id`。它们是同一个值。”

“即便 Stripe 的 Webhook 实际上并没有执行处理，暂存环境（Staging）也会返回 200。请检查 `payment_events` 来获取真实状态。”

利用文件系统和渐进式呈现

`SKILL.md` 文件可以指向 Claude 在特定情况下可以参考的其他几个文件。比方说，如果某个作业处于挂起状态，它应该引用 `stuck-jobs.md`。正如我们之前所说，技能是一个文件夹，而不仅仅是一个 Markdown 文件。你应该将整个文件系统视为一种上下文工程和渐进式呈现（Progressive Disclosure）的形式。告诉 Claude 你的技能中有哪些文件，它就会在合适的时间去阅读它们。

渐进式呈现最简单的形式就是指向供 Claude 使用的其他 Markdown 文件。比方说，你可以将详细的函数签名和使用示例拆分到 `references/api.md` 中。

另一个例子：如果你的最终输出是一个 Markdown 文件，你可以在 `assets/` 中包含一个模板文件供其复制和使用。

你可以拥有包含参考资料、脚本、示例等的文件夹，这些都能帮助 Claude 更有效地工作。

避免死板地限制 Claude

Claude 通常会尽力遵循你的指令，正因为技能的复用率极高，你需要小心避免在指令中写得过于死板。给 Claude 它所需的信息，但要赋予它根据具体情况进行变通的灵活性。

比方说：

上面的规定得太细了

通盘考虑初始化设置

上面的技能在编写时设定为：如果配置中未包含 Slack 频道，则提示用户输入

某些技能在设置时可能需要来自用户的上下文信息。比方说，如果你正在制作一个将站会内容发布到 Slack 的技能，你可能希望 Claude 询问应该发布到哪一个 Slack 频道。

实现这一点的一个好模式是将这些设置信息存储在技能目录下的 `config.json` 文件中，就像上面的例子一样。如果配置尚未设置，智能体随后就可以向用户询问相关信息。

如果你希望智能体提出结构化的多选题，可以指示 Claude 使用 `AskUserQuestion` 工具。

给模型写描述，而不是给人写

当 Claude Code 启动一个会话时，它会构建一个包含所有可用技能及其描述的列表。这个列表正是 Claude 用来浏览并决定“是否有适合这个请求的技能？”的依据。这意味着描述字段不是一个摘要，而是对何时触发该技能的说明。

在描述中包含技能的触发词（比方说 “babysit”）会非常有帮助。

帮助 Claude 记忆

这个文本日志文件可以帮助 Claude 记住过去的事件，比如评审过 Sarah 的认证 PR。

某些技能可以通过在内部存储数据来实现某种形式的记忆。你可以将数据存储在任何东西中，简单的可以是只增不改的文本日志文件或 JSON 文件，复杂的则可以是 SQLite 数据库。

比方说，一个 `standup-post` 技能可能会维持一个 `standups.log` 文件，记录它写过的每一篇帖子。这意味着下一次你运行它时，Claude 会读取自己的历史记录，并能分辨出从昨天以来发生了哪些变化。

存储脚本并生成代码

你能给 Claude 的最强大的工具之一就是代码。把脚本和库交给 Claude，可以让它把交互轮次花在逻辑组合与决定下一步做什么上，而不是浪费在重新构建样板代码上。

比方说，在你的数据科学技能中，你可能有一个从事件源获取数据的函数库。为了让 Claude 能够进行复杂的分析，你可以给它一组如下的辅助函数：

随后，Claude 就可以动态生成脚本来组合这些功能，从而针对诸如“周二发生了什么？”之类的提示词进行更高级的分析。

使用即需即用型钩子（On-demand hooks）

技能可以包含仅在调用该技能时才激活、且仅在当前会话期间持续的钩子。这适用于那些带有强烈主观偏向、你不想让它一直运行、但在某些时候又极其有用的钩子。

比方说：

• `/careful` —— 通过 Bash 上的 `PreToolUse` 匹配器来拦截 `rm -rf`、`DROP TABLE`、`force-push`、`kubectl delete`。你只会在明确知道自己正在动生产环境时才需要它 —— 如果让它一直开着，会把你逼疯的。

• `/freeze` —— 拦截任何不在特定目录下的修改/写入操作。在调试时非常有用：“我想添加一些日志，但我总是会不小心‘修复’不相关的代码。”

分发技能

技能最大的好处之一就是你可以将它们与团队的其他成员分享。

你可以通过以下两种方式与他人分享技能：

• 将你的技能签入到你的代码库中（存放在 `./.claude/skills` 下）

• 制作成插件，并通过 Claude Code 插件市场让用户上传和安装插件（在此处阅读文档了解更多信息）

对于在相对较少的代码库中工作的小型团队，将技能签入到代码库中效果很好。但每个签入的技能也会增加一点模型的上下文负担。随着规模的扩大，内部插件市场允许你分发技能，并让你的团队决定安装哪些技能，同时还可以包含一个初始化设置流程。

管理技能市场

你如何决定哪些技能可以进入市场？人们又是如何提交它们的？

在 Anthropic，我们并没有一个中心化的团队来做决定；相反，我们倾向于让最实用的技能自然而然地脱颖而出。如果有人做了一个技能想让大家试用，他们可以将其上传到 GitHub 的沙盒文件夹中，并在 Slack 或其他论坛上推荐给大家。

一旦某个技能获得了足够的关注（这由技能所有者自行判断），他们就可以提交一个 PR，将其移入官方市场。

组合技能

你可能希望技能之间能够相互依赖。比方说，你可能有一个用于上传文件的技能，以及一个用于生成 CSV 并将其上传的技能。这类依赖关系管理目前还没有原生内置到市场或技能系统中，但你只需按名称引用其他技能，只要安装了这些技能，模型就会自动调用它们。

评估技能

为了了解技能的表现如何，我们使用了一个 `PreToolUse` 钩子，它允许我们在公司内部记录技能的使用情况。这意味着我们可以发现哪些技能很受欢迎，或者哪些技能的触发频率低于我们的预期。

开始行动

技能的最佳实践仍在不断演进之中。我们绝大多数最优秀的技能在起步时都只有寥寥几行和一个小小的避坑提示，随后因为大家在 Claude 撞上新的边缘情况时不断往里添加内容，才变得越来越完善。

理解技能的最佳方式就是立即动手、不断实验，并寻找最适合你的方案。

译者：boxi。