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

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

但这种灵活性也让人难以把握最佳实践：什么类型的技能值得做？写好一个技能的秘诀是什么？什么时候应该和团队分享？

我们在 Anthropic 内部大量使用 Claude Code 的技能功能，有数百个技能在日常使用中。以下是我们通过技能加速开发过程中学到的经验。

什么是技能？

如果你是技能的新手，建议先阅读官方文档或观看 Skilljar 上关于 Agent 技能的最新课程。本文假定你已经对技能有基本了解。

关于技能，一个常见的误解是它们"不过是一些 markdown 文件"。但实际上，技能最有趣的部分在于——它们不只是文本文件。它们是文件夹，可以包含脚本、资源、数据等，Agent 可以发现、探索和操作这些内容。

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

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

技能的类型

在整理所有技能之后，我们发现它们可以归入几个反复出现的类别。最好的技能能清晰地归入某一类；令人困惑的那些则往往横跨多个类别。这不是一份权威清单，但它是一个很好的思考框架——可以帮助你检查组织内是否遗漏了某些类型的技能。

1. 库与 API 参考

这类技能解释如何正确使用某个库、CLI 或 SDK。可以是内部库，也可以是 Claude Code 容易出错的常用库。这类技能通常包含一个参考代码片段文件夹，以及一份 Claude 在编写脚本时需要避免的踩坑清单。

示例：

• billing-lib —— 你们内部的计费库：边界情况、自伤陷阱等
• internal-platform-cli —— 内部 CLI 封装的每个子命令，附带使用场景示例
• frontend-design —— 让 Claude 更好地理解你们的设计系统

2. 产品验证

描述如何测试或验证代码是否正常工作的技能。通常与 Playwright、tmux 等外部工具配合使用。

验证技能对于确保 Claude 输出的正确性极其有用。让工程师花一周时间专门打磨你们的验证技能，是非常值得的。

可以考虑让 Claude 录制其输出的视频，以便你精确看到它测试了什么；或者在每一步对状态进行编程断言。这些通常通过在技能中包含各种脚本来实现。

示例：

• signup-flow-driver —— 在无头浏览器中运行注册 → 邮箱验证 → 引导流程，每一步都有状态断言钩子
• checkout-verifier —— 用 Stripe 测试卡驱动结账 UI，验证发票确实落到正确状态
• tmux-cli-driver —— 用于需要 TTY 的交互式 CLI 测试

3. 数据获取与分析

连接到数据和监控栈的技能。可能包含使用凭证获取数据的库、特定的仪表盘 ID，以及常见工作流程的说明。

示例：

• funnel-query —— "要查看注册 → 激活 → 付费，需要关联哪些事件"以及包含标准 user_id 的表
• cohort-compare —— 比较两个群组的留存或转化率，标记统计显著的差异，链接到分段定义
• grafana —— 数据源 UID、集群名称、问题 → 仪表盘查找表

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

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

示例：

• standup-post —— 聚合你的工单追踪器、GitHub 活动和历史 Slack 消息 → 格式化的站会汇报，仅展示变化
• create-ticket —— 强制执行模式（有效的枚举值、必填字段）加上创建后的工作流（通知评审者、在 Slack 中链接）
• weekly-recap —— 合并的 PR + 关闭的工单 + 部署 → 格式化的周报

5. 代码脚手架与模板

为代码库中特定功能生成框架样板的技能。可以与可组合的脚本配合使用。当你的脚手架有无法纯粹通过代码覆盖的自然语言需求时，这类技能尤其有用。

示例：

• new-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 —— 隔离工作树 → cherry-pick → 冲突解决 → 使用模板创建 PR

8. 运维手册

接收症状（如 Slack 讨论串、告警或错误特征），通过多工具调查，生成结构化报告的技能。

示例：

• service-debugging —— 映射症状 → 工具 → 高流量服务的查询模式
• oncall-runner —— 获取告警 → 检查常见原因 → 格式化发现
• log-correlator —— 给定请求 ID，从所有可能涉及的系统中拉取匹配的日志

9. 基础设施运维

执行例行维护和运维操作的技能——其中一些涉及需要防护栏的破坏性操作。这些技能让工程师在关键操作中更容易遵循最佳实践。

示例：

• resource-orphans —— 查找孤立的 Pod/卷 → 发布到 Slack → 等待期 → 用户确认 → 级联清理
• dependency-management —— 组织的依赖审批工作流
• cost-investigation —— "为什么存储/出口费用激增"，包含具体的 bucket 和查询模式

技能编写技巧

确定了要制作的技能之后，怎么写？以下是我们发现的一些最佳实践、技巧和诀窍。

我们最近还发布了 Skill Creator，让在 Claude Code 中创建技能变得更加容易。

不要说显而易见的东西

Claude Code 对你的代码库了解很多，Claude 对编程也了解很多，包括许多默认观点。如果你发布的技能主要是关于知识的，尽量聚焦于能让 Claude 跳出其常规思维的信息。

frontend-design 技能就是一个很好的例子——它由 Anthropic 的一位工程师通过与客户反复迭代，改善 Claude 的设计品味而构建，避免了 Inter 字体和紫色渐变等经典模式。

建立踩坑记录章节

任何技能中信息量最高的内容都是"踩坑记录"（Gotchas）章节。这些章节应该基于 Claude 在使用你的技能时遇到的常见失败点来构建。理想情况下，你会随着时间推移更新技能来捕获这些踩坑记录。

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

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

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

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

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

避免过度约束 Claude

Claude 通常会尽量遵守你的指令。因为技能的复用性很强，所以要注意不要在指令中过于具体。给 Claude 它需要的信息，但也给它适应具体情况的灵活性。

考虑好设置流程

有些技能可能需要来自用户的上下文来设置。例如，如果你在做一个将站会发布到 Slack 的技能，你可能希望 Claude 询问发布到哪个 Slack 频道。

一个好的做法是将这些设置信息存储在技能目录的 config.json 文件中。如果配置未设置，Agent 可以询问用户获取信息。

如果你想让 Agent 展示结构化的多选问题，可以指示 Claude 使用 AskUserQuestion 工具。

描述字段是给模型看的

当 Claude Code 启动会话时，它会构建每个可用技能及其描述的列表。Claude 扫描这个列表来决定"有没有适合这个请求的技能？"这意味着描述字段不是摘要——而是描述何时应该触发这个技能。

记忆与数据存储

一些技能可以通过在自身内部存储数据来实现某种形式的记忆。你可以用简单的纯文本日志文件或 JSON 文件存储数据，也可以用复杂的 SQLite 数据库。

例如，一个站会发布技能可以维护一个 standups.log，记录它发布的每一条站会。这样下次运行时，Claude 就能读取自己的历史记录，判断自昨天以来发生了什么变化。

存储在技能目录中的数据在升级技能时可能会被删除，因此你应该将其存储在稳定的文件夹中。目前我们提供 ${CLAUDE_PLUGIN_DATA} 作为每个插件的稳定存储文件夹。

存储脚本并生成代码

你能给 Claude 的最强大工具之一就是代码。给 Claude 脚本和库，让它将轮次用在组合和决策上，而不是重构样板代码。

例如，在你的数据科学技能中，你可能有一个从事件源获取数据的函数库。为了让 Claude 能做复杂分析，你可以给它一组辅助函数。

Claude 可以动态生成脚本来组合这些功能，以应对"周二发生了什么？"这样的提示。

按需钩子

技能可以包含仅在技能被调用时才激活的钩子，并在会话期间持续有效。适用于你不想一直运行但有时极其有用的偏执型钩子。

示例：

• /careful —— 通过 PreToolUse 匹配器阻止 rm -rf、DROP TABLE、force-push、kubectl delete。只有在你知道自己在操作生产环境时才用——一直开着会让你抓狂
• /freeze —— 阻止不在特定目录中的任何 Edit/Write。调试时很有用："我想加日志但一直在不小心'修复'不相关的代码"

技能分发

技能最大的好处之一就是可以与团队分享。

有两种分享方式：

• 将技能签入你的仓库（在 ./.claude/skills 下）
• 制作插件，建立 Claude Code 插件市场，让用户可以上传和安装插件

对于跨少量仓库工作的小团队，将技能签入仓库效果很好。但签入的每个技能都会给模型增加一点上下文。随着规模扩大，内部插件市场可以让你分发技能，让团队自行决定安装哪些。

管理市场

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

我们没有中心化的团队来决定；相反，我们尽量有机地发现最有用的技能。如果你有一个想让大家试用的技能，可以上传到 GitHub 的沙盒文件夹，在 Slack 或其他渠道中推广。

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

需要注意的是，创建糟糕或冗余的技能相当容易，所以在发布前确保有某种筛选机制很重要。

技能组合

你可能需要相互依赖的技能。例如，你可能有一个文件上传技能和一个生成 CSV 并上传的技能。这种依赖管理目前在市场或技能中没有原生支持，但你可以直接通过名称引用其他技能，模型在已安装的情况下会调用它们。

技能度量

为了了解技能的表现，我们使用 PreToolUse 钩子来记录公司内部的技能使用情况。这样我们可以发现受欢迎的技能，以及触发率低于预期的技能。

总结

技能是极其强大、灵活的 Agent 工具，但现在仍处于早期阶段，我们都在摸索最佳使用方式。

与其说这是一份权威指南，不如说是我们验证过有效的一袋实用技巧。理解技能的最好方式就是开始动手、实验、找到适合你的方式。我们的大多数技能都始于几行代码和一个踩坑记录，然后随着 Claude 遇到新的边界情况，人们不断补充而变得更好。

希望这对你有帮助，有任何问题欢迎交流。