Claude Code 构建经验：如何高效利用 Agent Skills

Agent Skills（智能体技能）已经成为 Claude Code 中使用最频繁的扩展点之一。它们灵活、易于创建且易于分发。但这种灵活性也带来了一些难题：什么样的技能值得开发？编写优秀技能的秘诀是什么？什么时候应该与他人分享？

在 Anthropic 内部，我们极其广泛地在 Claude Code 中使用技能，日常活跃使用的技能多达数百个。以下是我们利用技能加速开发流程所学到的核心经验。

什么是 Skills？

对于刚接触技能的人来说，最常见的一个误解是认为“技能仅仅就是 Markdown 文件”。但技能最有趣的地方在于，它们不仅仅是文本文件，而是完整的文件夹。这些文件夹可以包含脚本、静态资产、数据等，Agent 可以对其进行发现、探索和操作。

在 Claude Code 中，技能还拥有丰富的配置选项，包括注册动态 Hook（钩子）。我们发现，Claude Code 中最有趣的一些技能，正是创造性地利用了这些配置选项和文件夹结构。

技能的九大类型

在对我们内部的所有技能进行分类后，我们发现它们大多集中在几个反复出现的类别中。最好的技能通常清晰地归属于其中一类，而那些容易让人困惑的技能往往跨越了多个类别。这虽然不是一个绝对的清单，但能很好地帮助你思考你的组织内部是否缺少了某些功能。

1. 库与 API 参考 (Library & API Reference)

解释如何正确使用内部库、CLI 工具或 SDK 的技能。这既适用于内部私有库，也适用于 Claude Code 偶尔会遇到困难的公共库。这些技能通常包含一个存放参考代码片段的文件夹，以及一个让 Claude 在编写脚本时避免踩坑的注意事项列表。

  • 示例：
    • billing-lib：内部计费库的边缘情况、踩坑点等。
    • internal-platform-cli：内部 CLI 包装器的每个子命令及使用场景示例。
    • frontend-design：让 Claude 更好地遵循你们的前端设计系统。

2. 产品验证 (Product Verification)

描述如何测试或验证代码是否正常工作的技能。这些技能通常与 playwright、tmux 等外部工具结合使用来进行验证。产品验证技能对于确保 Claude 输出的正确性极为有用。专门安排一名工程师花一周时间把验证技能打磨到极致，绝对是物超所值的。

  • 进阶技巧：可以考虑让 Claude 录制其输出的视频，以便你确切地看到它测试了什么；或者在每一步强制对状态进行可编程断言。这通常通过在技能中包含各种脚本来实现。
  • 示例：
    • signup-flow-driver：在无头浏览器中运行“注册 → 邮件验证 → 用户引导”流程，并带有在每一步断言状态的 Hook。
    • checkout-verifier：使用 Stripe 测试卡驱动结账 UI，验证发票是否实际进入了正确状态。
    • tmux-cli-driver：用于需要 TTY 终端的交互式 CLI 测试。

3. 数据获取与分析 (Data Fetching & Analysis)

连接到你的数据和监控技术栈的技能。这些技能可能包含使用凭证获取数据的库、特定的仪表板 ID，以及有关常见工作流或数据获取方式的说明。

  • 示例：
    • funnel-query：“我该关联哪些事件来查看‘注册 → 激活 → 付费’”，外加包含标准 user_id 的实际数据表。
    • cohort-compare：比较两个群组的留存率或转化率，标记出具有统计学意义的差异，并链接到相关的受众细分定义。
    • grafana：数据源 UID、集群名称、以及“问题 → 仪表板”的对照表。

4. 业务流程与团队自动化 (Business Process & Team Automation)

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

  • 示例：
    • standup-post：汇总你的工单追踪器、GitHub 活动和先前的 Slack 记录 → 生成格式化的每日站会内容（仅包含增量更新）。
    • create-<ticket-system>-ticket：强制执行工单 Schema（有效的枚举值、必填字段），加上创建后的工作流（@ 相应的 Reviewer，在 Slack 中发送链接）。
    • weekly-recap：已合并的 PR + 已关闭的工单 + 部署记录 → 格式化的团队周报。

5. 代码脚手架与模板 (Code Scaffolding & Templates)

为代码库中的特定功能生成框架样板的技能。你可以将这些技能与可组合的脚本结合起来。当你的脚手架具有无法完全用代码覆盖的自然语言要求时，它们特别有用。

  • 示例：
    • new-<framework>-workflow：搭建带有你特定注释的新服务/工作流/处理程序。
    • new-migration：你们的数据库迁移文件模板加上常见的注意事项。
    • create-app：预先配置好身份验证、日志记录和部署设置的全新内部应用。

6. 代码质量与审查 (Code Quality & Review)

在组织内部强制执行代码质量规范并协助审查代码的技能。这可以包括确定性的脚本或工具，以实现最大的稳健性。你可能希望将这些技能作为 Hook 的一部分或在 GitHub Action 内部自动运行。

  • 示例：
    • adversarial-review：生成一个带有“全新视角”的子 Agent 来挑刺，实施修复，并不断迭代，直到发现的问题降级为“吹毛求疵”的级别。
    • code-style：强制执行代码风格，特别是那些 Claude 默认处理得不太好的规范。
    • testing-practices：关于如何编写测试以及应该测试哪些内容的具体指导。

7. CI/CD 与部署 (CI/CD & Deployment)

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

  • 示例：
    • babysit-pr：监控一个 PR → 重试不稳定的 CI → 解决合并冲突 → 启用自动合并。
    • deploy-<service>：构建 → 冒烟测试 → 逐步切流并比较错误率 → 在发生回归时自动回滚。
    • cherry-pick-prod：在隔离的工作区中 → cherry-pick → 解决冲突 → 使用标准模板发起 PR。

8. 运维手册 (Runbooks)

根据某个症状（如 Slack 对话串、警报或错误签名），走完多工具调查流程，并生成结构化报告的技能。

  • 示例：
    • <service>-debugging：为你们流量最大的服务提供“症状 → 工具 → 查询模式”的映射。
    • oncall-runner：获取警报 → 检查常见的可疑项 → 格式化输出发现结果。
    • log-correlator：给定一个 Request ID，从每一个可能接触过该请求的系统中提取匹配的日志。

9. 基础设施操作 (Infrastructure Operations)

执行常规维护和操作程序的技能——其中一些涉及具有破坏性的操作，因此受益于 AI 护栏。这使得工程师在关键操作中更容易遵循最佳实践。

  • 示例：
    • <resource>-orphans：查找孤立的 Pod/Volume → 发送到 Slack → 等待观察期 → 用户确认 → 级联清理。
    • dependency-management：你们组织的依赖项升级审批工作流。
    • cost-investigation：“为什么我们的存储/出站流量账单飙升了”，并附带具体的存储桶和查询模式。

编写技能的实战技巧

一旦你决定了要制作的技能，该怎么写呢？以下是我们发现的一些最佳实践和技巧。（提示：Anthropic 最近发布了 Skill Creator，能让你在 Claude Code 中更轻松地创建和测试技能。）

不要陈述显而易见的事

Claude Code 对你的代码库了解很多，并且 Claude 对编程也有很多默认的见解。如果你发布的技能主要是关于知识的，尽量把重点放在那些能把 Claude 从其常规思维模式中拉出来的信息上。 例如，前端设计技能就是一个很好的例子——它是 Anthropic 的一位工程师通过与客户迭代，提高 Claude 的设计品味而构建的，特意指出要避免使用 Inter 字体和紫色渐变等典型的 AI 生成式设计模式。

建立“避坑（Gotchas）”章节

任何技能中信号量（价值）最高的内容就是 Gotchas（避坑）章节。这些部分应该建立在 Claude 使用你的技能时经常遇到的失败点之上。理想情况下，你应该随着时间的推移更新你的技能，以捕获这些新发现的坑。

利用文件系统与渐进式上下文 (Progressive Disclosure)

正如我们前面所说，技能是一个文件夹，而不仅仅是一个 Markdown 文件。你应该将整个文件系统视为一种“上下文工程”和“渐进式暴露”。告诉 Claude 你的技能中有哪些文件，它就会在合适的时候读取它们。 最简单的渐进式暴露形式是指向其他 Markdown 文件供 Claude 使用。例如，你可以将详细的函数签名和使用示例拆分到 references/api.md 中。 另一个例子：如果你的最终输出是一个 Markdown 文件，你可以在 assets/ 中包含一个模板文件供它复制和使用。拥有参考资料、脚本、示例等文件夹可以帮助 Claude 更有效地工作。

避免对 Claude“过度死板的管控 (Railroading)”

Claude 通常会尝试坚持你的指令，因为技能是非常可复用的，所以你要小心指令不要过于具体死板。给 Claude 提供它需要的信息，但同时给它适应不同情况的灵活性。

深入思考初始化配置 (Setup)

有些技能可能需要通过用户的上下文来进行设置。例如，如果你正在制作一个将站会内容发布到 Slack 的技能，你可能希望 Claude 询问应该将其发布到哪个 Slack 频道。 一个好的模式是像上面的例子一样，将这些设置信息存储在技能目录下的 config.json 文件中。如果配置未设置，Agent 就可以向用户询问信息。如果你希望 Agent 呈现结构化的多项选择题，你可以指示 Claude 使用 AskUserQuestion 工具。

Description 字段是写给模型看的

当 Claude Code 开始一个会话时，它会构建一个包含每个可用技能及其描述（Description）的列表。Claude 通过扫描这个列表来决定“是否有适用于此请求的技能？”这意味着 Description 字段不是给人类看的摘要，而是关于“何时触发该技能”的详细描述。

记忆与数据存储

有些技能可以通过在内部存储数据来包含一种形式的“记忆”。你可以将数据存储在简单的仅追加文本日志文件或 JSON 文件中，或者复杂到 SQLite 数据库中。 例如，standup-post 技能可能会保留一个 standups.log，记录它写过的每一篇帖子。这意味着下次你运行它时，Claude 会读取自己的历史记录，并能分辨出自昨天以来发生了什么变化。 由于技能目录中的数据在升级技能时可能会被删除，你应该将其存储在稳定的文件夹中。目前我们提供了 ${CLAUDE_PLUGIN_DATA} 作为一个稳定的单插件文件夹来存储数据。

存储脚本，让 Claude 去生成代码

你能给 Claude 的最强大的工具之一就是代码。给 Claude 提供脚本和库，让 Claude 把它的交互轮次花在“组合”上——决定下一步该做什么，而不是去重构冗长的样板代码。 例如，在你的数据科学技能中，你可能有一个包含从事件源获取数据的函数的库。为了让 Claude 进行复杂的分析，你可以给它一组辅助函数，这样 Claude 就能在运行中生成脚本，组合这些功能，从而对“周二发生了什么？”这样的提示进行更高级的分析。

按需触发的 Hooks (On Demand Hooks)

技能可以包含只有在调用该技能时才激活的 Hook，并持续到会话结束。将此用于你不想始终运行，但在某些时候极其有用的具有特定观点的 Hook。

  • 示例：
    • /careful：通过 Bash 上的 PreToolUse 拦截器阻止 rm -rf、DROP TABLE、force-push、kubectl delete。你只会在知道自己要触碰生产环境时才需要它——如果它一直开着，会把你逼疯的。
    • /freeze：阻止特定目录以外的任何编辑/写入操作。在调试时很有用：“我想添加日志，但我总是意外地‘修复’了不相关的代码”。

如何分发你的 Skills？

技能最大的好处之一就是你可以与团队的其他成员共享它们。分享技能通常有两种方式：

  1. 将技能提交到你的代码仓库中（放在 ./.claude/skills 下）。
  2. 制作一个插件并拥有一个 Claude Code 插件市场，用户可以在那里上传和安装插件。

对于在相对较少的 Repo 中工作的小型团队来说，将技能检入代码库效果很好。但是，每一个被检入的技能都会增加模型的一点点上下文负担。随着规模的扩大，内部插件市场允许你分发技能，并让你的团队自己决定安装哪些技能。

管理内部市场

你如何决定哪些技能进入市场？人们如何提交它们？ 我们没有一个集中的团队来决定；相反，我们试图有机地找到最有用的技能。如果你有一个希望人们尝试的技能，你可以将其上传到 GitHub 的沙盒文件夹中，并在 Slack 或其他论坛中向人们推荐它。 一旦一项技能获得了足够的关注度（由技能所有者决定），他们就可以提交一个 PR 将其移入正式的插件市场。需要注意的是，很容易创建出糟糕或多余的技能，所以在发布前确保你有某种审核机制是很重要的。

组合技能 (Composing Skills)

你可能希望技能相互依赖。例如，你可能有一个负责上传文件的技能，以及一个生成 CSV 并上传它的 CSV 生成技能。这种依赖关系管理尚未原生内置到市场或技能中，但你只需通过名称引用其他技能，模型就会在它们被安装的情况下自动调用它们。

衡量技能效果 (Measuring Skills)

为了了解一项技能的表现如何，我们使用 PreToolUse hook 来记录公司内部的技能使用情况。这意味着我们可以找到那些受欢迎的技能，或者那些相较于我们的预期触发频率过低的技能。

结语

技能对于 AI Agent 来说是极其强大和灵活的工具，但这仍处于早期阶段，我们都在探索如何最好地使用它们。

请将这篇文章视为我们在实践中发现的有用的技巧锦囊，而不是一份死板的权威指南。理解技能的最佳方法是开始动手、不断实验，看看什么对你有用。我们内部的大多数技能最初都只是几行代码和一个 Gotcha（避坑点），正是因为人们在 Claude 遇到新的边缘情况时不断添加内容，它们才变得越来越好。

希望这篇文章对你有所帮助！

🔗 原文参考：Lessons from Building Claude Code: How We Use Skills