构建 Claude Code 的经验教训：我们如何使用技能

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

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

在 Anthropic，我们已在 Claude Code 中广泛使用技能，有数百个技能处于活跃使用状态。以下是我们在利用技能加速开发过程中总结出的经验教训。

什么是技能？

技能是包含指令、脚本和资源的文件夹，智能体可以发现并使用它们，以更准确、更高效地完成任务。本篇博文假设您已了解技能基础知识；如果您是新手，请从我们的 Skilljar 上的智能体技能入门课程开始。

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

在 Claude Code 中，技能还拥有多种多样的配置选项，包括注册动态钩子（hooks）。

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

技能的类型

在对 Anthropic 内部的所有技能进行编目后，我们注意到它们可以归为九个类别。最好的技能能清晰地归入某一类；而试图包罗万象的技能则会横跨多个类别，让智能体感到困惑。这不是一份权威列表，但它是一个有用的框架，可用于识别您自己的技能库中的缺口。

A three-by-three grid of skill categories with example skill names: Library and API Reference, Product Verification, Data and Analysis, Business Automation, Scaffolding and Templates, Code Quality and Review, CI/CD and Deployment, Incident Runbooks, Infrastructure Ops. — **图 A**Claude Code 团队对我们的内部技能进行了分类，发现它们可以归入九个不同的类别。

1. 库和 API 参考

这些技能解释如何正确使用某个库、CLI 或 SDK。它们既可以针对内部库，也可以针对 Claude Code 有时难以处理的常见库。这些技能通常包含一个参考代码片段文件夹，以及一份 Claude 在编写脚本时应避免的常见陷阱（gotchas）列表。

示例包括：

billing-lib — 您的内部计费库：边缘情况、易错点等。
internal-platform-cli — 您内部 CLI 包装器的每个子命令及其使用时机示例。
sandbox-proxy — 为开发工作配置组织的出站网关：哪些主机可达、如何调试“connection refused”错误、如何添加允许列表条目。

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 — 比较两个群体的留存率或转化率，标记具有统计显著性的差异，并链接到群体定义
grafana — 数据源 UID、集群名称、问题 → 仪表板查找表
datadog — 字段参考（@request_id 与 trace_id）、服务列表、指标前缀约定

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

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

示例包括：

standup-post — 汇总你的工单跟踪器、GitHub 活动和之前的 Slack → 格式化的站会，仅显示差异
create-<ticket-system>-ticket — 强制执行架构（有效的枚举值、必填字段）以及创建后的工作流（通知审查者、在 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 — 隔离的工作树 → 挑选提交 → 冲突解决 → 带模板的 PR

8. 运维手册

这些是接收一个症状（如 Slack 线程、警报或错误特征），进行多工具调查，并生成结构化报告的技能。

示例包括：

<service>-debugging — 为你的流量最大的服务映射症状 → 工具 → 查询模式
oncall-runner — 获取警报 → 检查常见嫌疑对象 → 格式化发现结果
log-correlator — 给定一个请求 ID，从每个可能接触过它的系统中提取匹配的日志

9. 基础设施运维

这些技能用于执行例行维护和运维操作，其中一些涉及破坏性操作，需要护栏来保障。它们使工程师更容易在关键操作中遵循最佳实践。

例如：

<resource>-orphans — 查找孤立的 pod/卷 → 发布到 Slack → 观察期 → 用户确认 → 级联清理
dependency-management — 你所在组织的依赖审批工作流
cost-investigation — “为什么我们的存储/出网费用飙升”，并给出具体的存储桶和查询模式

制作技能的技巧

一旦你决定了要制作什么技能，该如何编写它？以下是 Claude Code 团队在制作技能方面的一些最佳实践、技巧和窍门。

不要陈述显而易见的内容

Claude 已经知道如何编写代码，也能阅读你的代码库。重述 Claude 默认会做的事情的技能，只会增加上下文而没有增加价值。如果你发布的技能主要是关于知识的，应专注于提供能让 Claude 跳出常规思维的信息。

前端设计技能就是一个很好的例子；它由 Anthropic 的一位工程师构建，通过与客户反复迭代来提升 Claude 的设计品味，避免使用 Inter 字体和紫色渐变等经典模式。

建立常见问题（Gotchas）部分

The same Billing Lib skill file on day 1, week 2 and month 3. A Gotchas section appears and grows from one line (proration rounds down) to four.

任何技能中信息含量最高的内容是“常见问题”部分。这些部分应基于 Claude 在使用你的技能时遇到的常见失败点来构建。理想情况下，你应该随着时间的推移更新技能，以捕捉这些常见问题。

例如：

“subscriptions 表是仅追加的。你要找的行是版本号最高的那行，而不是最近的 created_at。”
“该字段在 API 网关中称为 @request_id，在计费服务中称为 trace_id。它们是同一个值。”
“即使 Stripe webhook 实际上没有处理，Staging 也会返回 200。请检查 payment_events 以获取真实状态。”

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

A queue-debugging skill folder where SKILL.md is the hub and stuck-jobs.md, dead-letters.md, retry-storms.md and consumer-lag.md are spokes. SKILL.md holds a symptom-to-file table telling Claude which file to read. — **图 B**SKILL.md 文件指向 Claude 可在特定情况下参考的其他几个文件。例如，如果一个任务处于挂起状态，它应该引用 stuck-jobs.md。

正如我们之前所说，一个技能是一个文件夹，而不仅仅是一个 markdown 文件。你应该将整个文件系统视为一种上下文工程和渐进式披露。告诉 Claude 你的技能中有哪些文件，它会在适当的时候读取它们。

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

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

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

避免限制 Claude

Claude 通常会努力遵循你的指令，而且由于技能的可复用性很高，你在指令中要避免过于具体。给 Claude 它需要的信息，但也要给它适应情况的灵活性。

例如：

Two versions of cherry-pick instructions. Too prescriptive: six numbered steps spelling out each git command. Better: “Cherry-pick the commit onto a clean branch. Resolve conflicts preserving intent. If it can’t land cleanly, explain why.” — **图 C**说明目标和约束，而不是每一步。

考虑设置流程

A standup-post SKILL.md whose “Your config” section runs a shell command reading config.json and echoing NOT_CONFIGURED if it is missing; the instructions tell Claude to ask for the Slack channel and a sample standup when unconfigured, then save the answers. — **图 D**上面的技能被设计为：如果配置中未包含 Slack 频道，则会提示用户。

有些技能可能需要根据用户的上下文进行设置。例如，如果你正在制作一个将你的站会发布到 Slack 的技能，你可能希望 Claude 询问要发布到哪个 Slack 频道。

实现此目的的一种好模式是将此设置信息存储在技能目录中的 config.json 文件里，如上例所示。如果未设置配置，代理随后可以向用户询问信息。

如果你想让代理呈现结构化的多选题，可以指示 Claude 使用 AskUserQuestion 工具。

为模型撰写描述，而非为人类撰写

当 Claude Code 启动会话时，它会构建所有可用技能及其描述的列表。Claude 正是扫描这个列表来决定"此请求是否有对应的技能？"这意味着 description 字段不是摘要，而是关于何时触发此技能的描述。

Two SKILL.md descriptions for babysit-pr. Left: “A comprehensive tool for monitoring pull request status across the development lifecycle.” Right: “Monitors a PR until it merges. Trigger on ‘babysit’, ‘watch CI’, ‘make sure this lands’.” — **图 E**在技能的描述中包含触发词（如"babysit"）会很有帮助。

帮助 Claude 记忆

A ~/.claude/standups.log file with dated entries for three consecutive days; the onboarding redesign thread is highlighted across all of them. — **图 F**这个文本日志文件帮助 Claude 记住过去的事件，例如审查 Sarah 的 auth PR。

有些技能可以通过在其中存储数据来包含一种记忆形式。你可以将数据存储在任何东西中，简单到仅追加的文本日志文件或 JSON 文件，复杂到 SQLite 数据库。

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

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

存储脚本并生成代码

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

例如，在你的 data-science 技能中，你可能有一个用于从事件源获取数据的函数库。为了让 Claude 进行复杂的分析，你可以给它一组这样的辅助函数：

Claude 随后可以即时生成脚本来组合这些功能，以进行更高级的分析，例如回答"周二发生了什么？"这样的提示。

使用按需钩子

技能可以包含仅在调用该技能时才激活的钩子，并且仅在会话期间持续。对于那些你不想一直运行、但有时非常有用的更具倾向性的钩子，可以使用此功能。

例如：

/careful —— 通过 Bash 上的 PreToolUse 匹配器阻止 rm -rf、DROP TABLE、强制推送、kubectl delete。只有当你知道自己在操作生产环境时才需要这个——如果一直开着会让你发疯。
/freeze —— 阻止任何不在特定目录中的 Edit/Write 操作。在调试时很有用："我想添加日志，但总是不小心'修复'无关的代码。"

分发技能

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

你可能想与他人共享技能有两种方式：

将你的技能提交到代码仓库中（位于 ./.claude/skills 下）
制作一个插件，并拥有一个 Claude Code 插件市场，用户可以在其中上传和安装插件（在此处的文档中阅读更多）

对于在相对较少的仓库中协作的小型团队来说，将技能检入仓库效果很好。但每检入一个技能，也会略微增加模型的上下文负担。随着规模扩大，内部插件市场可以让您分发技能，让团队决定安装哪些技能，并包含一个设置流程。

管理技能市场

您如何决定哪些技能进入市场？人们如何提交技能？

在 Anthropic，我们没有一个集中的团队来做决定；相反，我们尝试自然地发现最有用的技能。如果有人有一个技能想让大家试用，他们可以将其上传到 GitHub 的沙盒文件夹，并在 Slack 或其他论坛中分享链接。

一旦一个技能获得了一定的热度（这由技能作者决定），他们可以提交 PR 将其移入市场。

组合技能

您可能需要相互依赖的技能。例如，您可能有一个上传文件的文件上传技能，以及一个生成 CSV 并上传的 CSV 生成技能。这种依赖管理尚未原生内置于市场或技能中，但您可以直接按名称引用其他技能，模型会在它们已安装时调用它们。

衡量技能

为了了解技能的表现，我们使用 PreToolUse 钩子来记录公司内部的技能使用情况（示例代码在此）。这意味着我们可以找出那些受欢迎的技能，或与我们预期相比触发不足的技能。

开始使用

技能的最佳实践仍在不断演进。我们大多数优秀的技能都始于几行代码和一个注意事项，然后因为人们在 Claude 遇到新的边缘情况时不断添加而变得更好。

理解技能的最佳方式就是开始动手、尝试，并看看什么最适合您。

本文由 Anthropic 技术团队成员、从事 Claude Code 工作的 Thariq Shihipar 撰写。