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

我们在 Anthropic 内部构建并扩展数百个 Skills 的过程中学到的经验。

Skills 已成为 Claude Code 中使用最广泛的扩展点之一。它们灵活、易于制作，也易于分发。

但这种灵活性也让人很难知道什么做法效果最好。哪些类型的 Skill 值得制作？如何组织一个 Skill？什么时候应该与他人分享？

在 Anthropic，我们一直在 Claude Code 中大量使用 Skills，目前有数百个 Skill 正在使用。这些是我们从中总结出的经验，讲述如何利用 Skills 加快开发。

什么是 Skills？

Skills 是由指令、脚本和资源组成的文件夹，智能体可以发现并使用它们，从而更准确、更高效地完成任务。本文假定你熟悉 Skills 的基础知识；如果你刚接触它们，可以从 Skilljar 上的《智能体 Skills 入门》课程开始。

我们经常听到一种关于 Skills 的误解：它们“不过是 Markdown 文件”。实际上，它们是文件夹，其中可以包含脚本、资源文件、数据等，供智能体发现、探索和操作。

在 Claude Code 中，Skills 还有各种各样的配置选项，包括注册动态钩子。

我们发现，Claude Code 中一些效果最好的 Skill，都有效利用了这些配置选项和文件夹结构。

Skill 的类型

在 Anthropic 对所有内部 Skill 进行分类后，我们发现它们聚集在九个类别中。最好的 Skill 能清晰地归入其中一个类别；那些试图包揽太多事情的 Skill 会横跨多个类别，让智能体感到困惑。这并非一份权威清单，但它是一个有用的框架，可以帮助你发现自己的 Skill 库中有哪些空缺。

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

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——在无头浏览器中跑完整个注册 → 邮件验证 → 引导流程，并提供钩子以便在每一步断言状态。

checkout-verifier——使用 Stripe 测试卡操作结账界面，验证发票是否确实进入正确状态。

tmux-cli-driver——用于交互式 CLI 测试，适合需要 TTY 的待验证对象。

3. 数据获取与分析

这类 Skill 会连接到你的数据和监控技术栈。它们可能包含用于凭据认证后获取数据的库、特定的仪表板 ID 等，也可能包含常见工作流或获取数据的方法说明。

例如：

funnel-query——“要查看注册 → 激活 → 付费，需要关联哪些事件”，以及实际包含规范 user_id 的那张表。

cohort-compare——比较两个队列的留存率或转化率，标记具有统计显著性的差异，并链接到细分定义。

grafana——数据源 UID、集群名称，以及问题 → 仪表板查找表。

datadog——字段参考（@request_id 与 trace_id）、服务列表、指标前缀约定。

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

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

例如：

standup-post——汇总工单跟踪器、GitHub 活动和之前的 Slack 消息 → 生成格式化的站会报告，只列出变动。

create-<ticket-system>-ticket——强制符合架构（有效的枚举值、必填字段），并执行创建后的工作流（通知审查者、在 Slack 中添加链接）。

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

5. 代码脚手架与模板

这类 Skill 会为代码库中特定功能生成框架样板。你可以将这类 Skill 与可组合使用的脚本结合起来。当脚手架还包含无法仅靠代码完全表达的自然语言要求时，它们尤其有用。

例如：

new-<framework>-workflow——根据你的注解，为新服务、工作流或处理程序搭建脚手架。

new-migration——你的迁移文件模板以及常见注意事项。

create-app——创建新的内部应用，并预先配置好你们的身份验证、日志记录和部署设置。

6. 代码质量与审查

这类 Skill 会在组织内部确保代码质量，并帮助审查代码。为了尽可能可靠，它们可以包含确定性脚本或工具。你可能希望通过钩子或 GitHub Action 自动运行这些 Skill。

adversarial-review——启动一个全新的子智能体，以全新视角进行批评，落实修复，然后反复迭代，直到发现的问题都只剩细枝末节。

code-style——执行代码风格规范，尤其是 Claude 默认表现不佳的风格要求。

testing-practices——关于如何编写测试以及应该测试什么的说明。

7. CI/CD 与部署

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

例如：

babysit-pr——监控 PR → 重试不稳定的 CI → 解决合并冲突 → 启用自动合并。

deploy-<service>——构建 → 冒烟测试 → 逐步放量，并比较错误率 → 出现回归时自动回滚。

cherry-pick-prod——隔离的 worktree → cherry-pick → 解决冲突 → 使用模板创建 PR。

8. Runbook

这类 Skill 会接收一种症状（例如 Slack 讨论串、告警或错误特征），逐步开展多工具调查，并生成结构化报告。

例如：

<service>-debugging——为流量最高的服务整理症状 → 工具 → 查询模式的映射。

oncall-runner——获取告警 → 检查常见嫌疑项 → 整理调查结果。

log-correlator——给定一个请求 ID，从所有可能处理过该请求的系统中提取匹配日志。

9. 基础设施运维

这类 Skill 执行常规维护和运维流程，其中有些操作具有破坏性，因此适合设置护栏。它们能让工程师在关键运维操作中更容易遵循最佳实践。

例如：

<resource>-orphans——查找孤立的 Pod/卷 → 在 Slack 中发布 → 等待观察期 → 用户确认 → 级联清理。

dependency-management——你们组织的依赖审批工作流。

cost-investigation——“为什么我们的存储/出口流量账单突然增加”，以及对应的具体分桶和查询模式。

制作 Skill 的建议

决定好要制作哪种 Skill 之后，应该怎么写？以下是 Claude Code 团队制作 Skill 的一些最佳实践、建议和技巧。

不要陈述显而易见的内容

Claude 已经知道如何编程，也能读取你的代码库。重复 Claude 默认做法的 Skill 只会增加上下文，却没有增加价值。如果你要发布的 Skill 主要提供知识，就应聚焦于那些能让 Claude 跳出常规思路的信息。

前端设计 Skill 就是一个很好的例子；Anthropic 的一位工程师与客户一起迭代改进 Claude 的设计品味，打造了这个 Skill，帮助 Claude 避免 Inter 字体和紫色渐变等经典套路。

建立 Gotchas 部分

任何 Skill 中信号最强的内容就是 Gotchas（常见陷阱）部分。这些部分应该根据 Claude 使用 Skill 时遇到的常见失败点逐步积累。理想情况下，你会随着时间推移不断更新 Skill，把这些陷阱记录下来。

例如：

“subscriptions 表只追加数据。你要找的那一行是版本号最高的，而不是 created_at 最新的那一行。”

“在 API 网关中，这个字段叫 @request_id，在计费服务中叫 trace_id。它们的值相同。”

“即使 Stripe webhook 实际上没有处理，Staging 也会返回 200。请检查 payment_events，确认真实状态。”

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

图 B SKILL.md 文件会指向其他几个文件，供 Claude 在特定情况下参考。例如，如果某个任务处于等待状态，它就应该参考 stuck-jobs.md。

正如我们前面所说，Skill 是一个文件夹，而不只是一份 Markdown 文件。你应该把整个文件系统都视为上下文工程和渐进式披露的一种形式。告诉 Claude 你的 Skill 中有哪些文件，它就会在适当的时候读取它们。

渐进式披露最简单的形式，是指向其他供 Claude 使用的 Markdown 文件。例如，你可以把详细的函数签名和用法示例拆分到 references/api.md 中。

再举一个例子：如果最终输出是一个 Markdown 文件，你可以在 assets/ 中放入一个模板文件，供 Claude 复制和使用。

你可以设置用于参考资料、脚本、示例等内容的文件夹，帮助 Claude 更有效地工作。

不要把 Claude 限制在固定轨道上

Claude 通常会努力遵循你的指令，而 Skill 又非常容易复用，所以你要小心，不要把指令写得过于具体。告诉 Claude 它需要的信息，同时让它能够灵活地适应具体情况。

例如：

图 C 说明目标和约束，而不是列出每一个步骤。

仔细考虑设置流程

图 D 上面的 Skill 在配置中未包含 Slack 频道时，会提示用户。

有些 Skill 可能需要结合用户提供的上下文进行设置。例如，如果你要制作一个把站会报告发到 Slack 的 Skill，你可能希望 Claude 询问要发到哪个 Slack 频道。

一种好的做法是在 Skill 目录中用 config.json 文件存储这些设置信息，如上例所示。如果配置尚未设置，智能体就可以向用户询问所需信息。

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

为模型而非人为描述 Skill

Claude Code 启动会话时，会生成一份包含所有可用 Skill 及其描述的列表。Claude 会扫描这份列表，判断“这个请求有没有对应的 Skill？”这意味着 description 字段不是摘要，而是说明何时应触发这个 Skill。

图 E 在 Skill 的 description 中加入触发条件会很有帮助，例如“babysit”。

帮助 Claude 记住

图 F 这个文本日志文件帮助 Claude 记住过去发生的事情，例如曾审查过 Sarah 的身份验证 PR。

有些 Skill 可以通过在其中存储数据来实现某种形式的记忆。你可以把数据存储在很简单的只追加文本日志文件或 JSON 文件中，也可以存储在更复杂的 SQLite 数据库中。

例如，一个 standup-post Skill 可以维护一份 standups.log，记录它发布过的每一条站会报告。这样，下次运行时，Claude 就会读取自己的历史记录，并能判断从昨天到现在发生了什么变化。

你可以使用环境变量 ${CLAUDE_PLUGIN_DATA} 获取一个稳定的目录来存储数据；有关在 Skills 中持久化数据的更多信息，请参阅此处：https://code.claude.com/docs/en/plugins-reference#persistent-data-directory。

存储脚本并生成代码

你可以给 Claude 的最强大工具之一就是代码。给 Claude 提供脚本和库，就能让 Claude 把回合用于组合功能、决定下一步做什么，而不必重新构建样板代码。

例如，在你的数据科学 Skill 中，你可以提供一个函数库，用于从事件来源获取数据。为了让 Claude 进行复杂分析，你可以给它一组辅助函数，例如：

图 G 给 Claude 一个小型辅助函数库，并把常见陷阱写进文档字符串。

然后，Claude 就可以即时生成脚本，组合这些功能，以便针对“周二发生了什么？”之类的提示进行更高级的分析。

图 H Claude 将这些辅助函数组合成一个针对当前问题的一次性脚本。

使用按需钩子

Skill 可以包含仅在 Skill 被调用时才启用、且只在当前会话期间有效的钩子。对于你不希望始终运行、但在某些时候非常有用的、更有主张的钩子，可以使用这种方式。

例如：

/careful——通过 Bash 上的 PreToolUse matcher，拦截 rm -rf、DROP TABLE、强制推送和 kubectl delete。你只有在确定自己要操作生产环境时才需要它；如果它始终启用，会让你抓狂。

/freeze——拦截所有不在特定目录中的 Edit/Write 操作。在调试时很有用：“我想添加日志，但总是不小心‘修复’了无关代码。”

分发 Skills

Skills 最大的好处之一，是可以与团队其他成员分享。

你可能希望通过以下两种方式之一与他人分享 Skills：

• 将 Skills 提交到你的代码库中（放在 ./.claude/skills 下）
• 制作一个插件，并建立 Claude Code 插件市场，让用户上传和安装插件（更多信息请参阅此处的文档）

对于协作的代码库数量相对较少的小团队，把 Skills 提交到代码库中效果很好。但每个提交进来的 Skill 也会稍微增加模型的上下文。随着规模扩大，内部插件市场可以让你分发 Skills，并由团队自行决定安装哪些 Skill，同时还可以包含设置流程。

管理 Skill 市场

如何决定哪些 Skill 应该进入市场？人们如何提交 Skill？

在 Anthropic，我们没有一个集中团队负责做决定；相反，我们会尝试以自发的方式找出最有用的 Skill。如果有人有一个想让大家试用的 Skill，就可以把它上传到 GitHub 上的沙盒文件夹，然后在 Slack 或其他论坛里告诉大家。

一个 Skill 获得了一定关注度后（由 Skill 所有者决定），其所有者就可以提交 PR，把它移入市场。

组合 Skills

你可能会希望某些 Skill 依赖其他 Skill。例如，你可能有一个上传文件的 Skill，以及一个生成 CSV 并上传它的 Skill。目前，市场或 Skills 尚未原生支持这类依赖管理，但你可以直接通过名称引用其他 Skill；如果模型已经安装了这些 Skill，就会调用它们。

衡量 Skills

为了了解某个 Skill 的表现如何，我们使用一个 PreToolUse 钩子来记录公司内部的 Skill 使用情况（此处有示例代码）。这样我们就能找出热门 Skill，或找出其触发频率低于预期的 Skill。

开始使用

Skill 最佳实践仍在不断演变。我们的大多数优秀 Skill 最初只有几行内容和一个常见陷阱；后来，随着 Claude 遇到新的边缘情况，人们不断补充内容，Skill 也就越来越完善。

了解 Skills 最好的方式就是开始使用、不断试验，看看哪些做法适合你。

[查看我们的 Skills 文档] [查找可自定义的示例 Skill]

本文作者是 Anthropic 技术团队成员 Thariq Shihipar，负责 Claude Code。