Anthropic 分享 Claude Code 中 Skill 的使用经验

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

但这种灵活性也让人难以判断什么最有效。哪些类型的 skills 值得做？如何构建一个 skill？什么时候与他人分享？

我们在 Anthropic 的 Claude Code 中广泛使用 skills，有数百个正在活跃使用。这些是我们在使用 skills 加速开发过程中学到的经验。

什么是 SKILLS？

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

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

在 Claude Code 中，skills 还有多种配置选项，包括注册动态钩子。

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

SKILLS 的类型

在 Anthropic 对内部所有 skills 进行编目后，我们注意到它们可以归为九类。最好的 skills 能清晰地归入其中一类；那些试图做太多事情的 skills 会横跨多类，让智能体感到困惑。这不是一份权威列表，但它是一个有用的框架，可以帮助你发现自己的 skills 库中的空白。

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 团队对我们的内部 skills 进行了分类，发现它们可以归入九个不同的类别。

1. 库和 API 参考

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

示例包括：

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

2. 产品验证

这些 skills 描述如何测试或验证你的代码是否正常工作。它们通常与 playwright、tmux 或其他外部工具配合进行验证。

验证类 skills 对 Claude 输出质量产生了内部最可衡量的影响。值得让一名工程师花一周时间专门把你的验证 skills 做到极致。

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

示例包括：

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 — 强制校验 schema（有效的枚举值、必填字段）以及创建后工作流（通知评审人、在 Slack 中链接）
weekly-recap — 已合并的 PR + 已关闭的工单 + 部署 → 格式化的回顾帖子

5. 代码脚手架与模板

这些技能可为代码库中的特定功能生成框架样板。你可以将这些技能与可组合的脚本结合使用。当你的脚手架包含无法仅由代码完全覆盖的自然语言需求时，它们尤其有用。

示例包括：

new-<framework>-workflow — 使用你的注解搭建新的服务/工作流/处理器
new-migration — 你的迁移文件模板以及常见陷阱
create-app — 预接好你的认证、日志和部署配置的新内部应用

6. 代码质量与审查

这些技能可在你的组织内强制执行代码质量，并帮助审查代码。这些可以包括确定性脚本或工具，以实现最大程度的稳健性。你可能希望将这些技能作为 hooks 的一部分或在 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. 运行手册

这些技能接收一个症状（例如 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 字体和紫色渐变等经典套路。

构建一个“坑点”部分

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 实际上没有处理，预发环境也会返回 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’.” — **FIG 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. — **FIG 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、force-push、kubectl delete。你只希望在你知道自己正在操作生产环境时才启用它——一直开启会把你逼疯。
/freeze — 阻止任何不在特定目录中的 Edit/Write。在调试时很有用：“我想添加日志，但我总是意外地‘修复’不相关的代码。”

分发技能

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

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

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

对于在相对较少仓库中协作的小型团队来说，把技能检入仓库效果不错。但每一个检入的技能都会给模型的上下文增加一点内容。随着规模扩大，内部插件市场可以让你分发技能，让团队自行决定安装哪些，还可以包含一个设置流程。

管理技能市场

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

在 Anthropic，我们没有专门的中央团队来做决定；相反，我们尝试有机地发现最有用的技能。如果有人有一个想让别人尝试的技能，他们可以把它上传到 GitHub 上的沙盒文件夹，并在 Slack 或其他论坛中指引大家去看。

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

组合技能

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

衡量技能

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

开始使用

技能的最佳实践仍在不断演进。我们大多数最好的技能最初只是几行代码和一个坑点，后来因为人们在 Claude 遇到新的边缘情况时不断补充而变得更好。

理解技能的最好方式就是开始动手、实验，看看什么适合你。

本文由 Thariq Shihipar 撰写，他是 Anthropic 的技术人员，从事 Claude Code 相关工作。