从构建克劳德代码中汲取的经验教训：我们如何运用技能

发表于 分类于 本文字数： 4.3k 阅读时长 ≈ 16 分钟

技能已成为Claude Code中最常用的扩展功能之一。它们灵活、易于创建且易于分发。 但这种灵活性也使得我们难以判断哪种方法最有效。哪些类型的技能值得培养？编写好的技能说明的秘诀是什么？何时应该与他人分享这些技能？ 在 Anthropic，我们广泛使用 Claude Code 中的各种技能，其中数百项技能已投入使用。以下是我们从运用这些技能加速产品开发过程中总结出的经验教训。 什么是技能…

技能已成为Claude Code中最常用的扩展功能之一。它们灵活、易于创建且易于分发。

但这种灵活性也使得我们难以判断哪种方法最有效。哪些类型的技能值得培养？编写好的技能说明的秘诀是什么？何时应该与他人分享这些技能？

在 Anthropic，我们广泛使用 Claude Code 中的各种技能，其中数百项技能已投入使用。以下是我们从运用这些技能加速产品开发过程中总结出的经验教训。

什么是技能？

如果你是技能新手，我建议阅读我们的文档或者观看我们最新的课程特工技能新增 Skilljar 功能本文假设您已经具备一定的技能。

我们经常听到的一种关于技能的误解是，它们"只是 Markdown 文件"，但技能最有趣的地方在于它们不仅仅是文本文件。它们是文件夹，可以包含脚本、资源、数据等，代理可以发现、探索和操作这些内容。

在克劳德代码中，技能也具有多种配置选项包括注册动态钩子。

我们发现 Claude Code 中一些最有趣的技能创造性地利用了这些配置选项和文件夹结构。

技能类型

在对所有技能进行分类后，我们发现它们大致可以归为几个类别。最优秀的技能可以清晰地归入某一类别；而那些比较复杂的技能则可能跨越多个类别。这并非一份完整的清单，但它可以帮助您思考组织内部是否存在技能缺失。

图像

1. 库和 API 参考

这些技能讲解了如何正确使用库、命令行界面 (CLI) 或软件开发工具包 (SDK)。这些库可能包括内部库，也可能包括 Claude Code 有时遇到问题的常用库。这些技能通常包含一个参考代码片段文件夹，以及一份 Claude 在编写脚本时需要避免的陷阱列表。

例如：

  • billing-lib - 您的内部计费库：特殊情况、意外情况等。
  • internal-platform-cli - 内部 CLI 包装器的每个子命令，以及何时使用它们的示例
  • 前端设计–让 Claude 更擅长你的设计系统

2. 产品验证

这些技能描述了如何测试或验证代码是否正常运行。这些技能通常会与 Playwright、tmux 等外部工具配合使用，以进行验证。

验证技能对于确保克劳德的输出正确性至关重要。花一周时间专门提升你的验证技能是值得的。

可以考虑一些技巧，例如让 Claude 录制输出视频，以便您准确了解它测试的内容；或者在每个步骤中强制执行状态的程序化断言。这些通常是通过在技能中包含各种脚本来实现的。

例如：

  • signup-flow-driver - 在无头浏览器中运行注册 → 邮箱验证 → 引导流程，并在每个步骤提供状态断言钩子。
  • 结账验证器 - 使用 Stripe 测试卡驱动结账用户界面，验证发票是否实际进入正确的状态
  • tmux-cli-driver - 用于交互式 CLI 测试，尤其适用于需要 TTY 的测试。

3. 数据获取与分析

与您的数据和监控系统相关的技能。这些技能可能包括使用凭据、特定仪表板 ID 等获取数据的库，以及有关常见工作流程或数据获取方法的说明。

例如：

  • 漏斗查询–"我应该加入哪些事件才能查看注册→激活→付费"以及实际包含规范用户 ID 的表
  • 队列比较 - 比较两个队列的留存率或转化率，标记具有统计学意义的差异，并链接到细分定义。
  • Grafana - 数据源 UID、集群名称、问题 → 仪表盘查找表

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

这些技能可以将重复性工作流程自动化为一条命令。这些技能通常是相当简单的指令，但可能与其他技能或主控程序 (MCP) 存在更复杂的依赖关系。对于这些技能，将先前的结果保存到日志文件中可以帮助模型保持一致性，并反映工作流程的先前执行情况。

例如：

  • standup-post - 聚合您的工单跟踪器、GitHub 活动和之前的 Slack 记录 → 格式化的站会，仅显示增量信息
  • 创建<工单系统>工单 - 强制执行架构（有效的枚举值、必填字段）以及创建后工作流程（通知审核人、在 Slack 中提供链接）
  • 每周回顾 - 合并的 PR + 已关闭的工单 + 部署 → 格式化的回顾文章

5. 代码脚手架和模板

这些技能可以生成代码库中特定功能的框架样板代码。您可以将这些技能与可组合的脚本结合使用。当您的脚手架具有无法完全通过代码实现的自然语言要求时，这些技能尤其有用。

例如：

  • new--workflow - 使用您的注解搭建一个新的服务/工作流/处理程序
  • 新迁移 - 您的迁移文件模板以及常见陷阱
  • 创建应用 - 创建一个新的内部应用，其中预先配置了身份验证、日志记录和部署设置

6. 代码质量与审查

这些技能可以确保组织内部的代码质量，并有助于代码审查。它们可以包括用于最大限度提高健壮性的确定性脚本或工具。您可能希望将这些技能作为钩子的一部分或在 GitHub Action 中自动运行。

  • 对抗性审查–生成一个具有全新视角的子代理进行批判，实施修复，不断迭代，直到发现的问题都只是吹毛求疵为止。
  • 代码风格 - 强制执行代码风格，特别是 Claude 默认情况下处理不佳的风格。
  • 测试实践–关于如何编写测试以及测试什么的说明。

7. CI/CD 和部署

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

例如：

  • babysit-pr - 监控 PR → 重试不稳定的 CI → 解决合并冲突 → 启用自动合并
  • 部署-<服务> - 构建 → 冒烟测试 → 逐步流量部署并比较错误率 → 回归测试自动回滚
  • cherry-pick-prod - 隔离的工作树 → cherry-pick → 冲突解决 → 使用模板的 PR

8. 运行手册

能够根据症状（例如 Slack 线程、警报或错误签名）进行多工具调查，并生成结构化报告的技能。

例如：

  • <服务>调试 - 针对流量最高的服务，映射症状 → 工具 → 查询模式
  • 值班运行程序 - 获取警报 → 检查常见嫌疑对象 → 格式化调查结果
  • 日志关联器–给定一个请求 ID，从所有可能访问过该请求的系统中拉取匹配的日志。

9. 基础设施运营

执行日常维护和操作程序所需的技能–其中一些操作可能具有破坏性，因此需要采取防护措施。这些措施有助于工程师在关键操作中遵循最佳实践。

例如：

  • -orphans - 查找孤立的 pod/volumes → 发布到 Slack → 等待一段时间 → 用户确认 → 级联清理
  • 依赖管理 - 贵组织的依赖审批工作流程
  • 成本调查–“为什么我们的存储/出站流量费用飙升”，并分析具体的存储桶和查询模式

提升技能的技巧

图像

一旦你决定要制作什么技能，该如何编写代码呢？以下是我们总结的一些最佳实践、技巧和窍门。

我们最近也发布了技能创建者使在 Claude Code 中创建技能更加容易。

不要说显而易见的事

Claude Code 对你的代码库非常了解，也精通编程，包括许多默认观点。如果你发布的技能主要涉及知识，请尝试提供能够打破 Claude 固有思维模式的信息。

这前端设计技能就是一个很好的例子–它是由 Anthropic 的一位工程师通过与客户反复沟通，改进 Claude 的设计品味而打造的，避免了 Inter 字体和紫色渐变等经典图案。

建立陷阱部分

图像

任何技能中最具价值的内容都是"陷阱"部分。这些部分应该基于克劳德在使用技能时常遇到的失败点构建而成。理想情况下，你应该随着时间的推移不断更新技能，以涵盖这些陷阱。

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

图像

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

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

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

您可以创建文件夹，存放参考资料、脚本、示例等，这有助于 Claude 更有效地工作。

避免铁路克劳德

克劳德通常会尽量遵循你的指令，但由于技能可以重复使用，所以你的指令要谨慎，不要过于具体。给克劳德提供所需的信息，但也要赋予它适应不同情况的灵活性。例如：

图像

仔细考虑一下设置

图像

有些技能可能需要根据用户提供的上下文进行设置。例如，如果您创建的技能是将您的站会发布到 Slack，您可能需要让 Claude 询问要发布到哪个 Slack 频道。

一个好的做法是将这些配置信息存储在技能目录下的 config.json 文件中，就像上面的示例一样。如果配置未设置，代理可以向用户询问相关信息。

如果您希望代理提出结构化的多项选择题，您可以指示 Claude 使用 AskUserQuestion 工具。

描述字段用于模型

当 Claude Code 启动会话时，它会创建一个包含所有可用技能及其描述的列表。Claude 会扫描此列表以判断"是否存在满足此请求的技能？"。这意味着描述字段并非摘要，而是对何时触发此 PR 的描述。

图像

内存与数据存储

图像

某些技能可以通过存储数据来实现某种形式的记忆。你可以将数据存储在任何类型的存储介质中，例如仅追加的文本日志文件或 JSON 文件，也可以存储到像 SQLite 数据库这样复杂的介质中。

例如，站立发帖技能可能会为它撰写的每篇帖子保留一个 standups.log 文件，这意味着下次运行它时，Claude 会读取它自己的历史记录，并知道自昨天以来发生了哪些变化。

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

存储脚本并生成代码

你能给 Claude 的最强大的工具之一就是代码。给 Claude 提供脚本和库，就能让 Claude 将精力集中在组合代码上，决定下一步该做什么，而不是重复编写样板代码。

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

图像

然后，Claude 可以即时生成脚本来组合此功能，从而对"星期二发生了什么事？"之类的提示进行更高级的分析。

图像

按需钩子

技能可以包含仅在技能被调用时激活、且持续到游戏结束的钩子。这适用于一些你不想一直使用，但有时又非常有用的特殊钩子。

例如：

  • 注意**–**在 Bash 中，PreToolUse 匹配器会阻止 rm -rf、DROP TABLE、force-push 和 kubectl delete 命令。只有在确定要操作生产环境时才需要启用此功能–始终启用会让人抓狂。
  • / freeze - 阻止对指定目录之外的所有编辑/写入操作。很有用。
  • 调试时：“我想添加日志，但我总是不小心’修复’了无关的问题。”

技能分配

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

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

  • 将你的技能提交到你的代码仓库（位于 ./.claude/skills 目录下）
  • 创建一个插件，并建立一个 Claude Code 插件市场，用户可以在其中上传和安装插件（了解更多信息）。文档这里）

对于规模较小的团队来说，在代码库数量相对较少的情况下，将技能提交到代码库中是一个不错的选择。但每个提交的技能都会为模型增添一些上下文信息。随着团队规模的扩大，内部插件市场可以让你分发技能，并让团队成员决定安装哪些技能。

管理市场

如何决定哪些技能可以放到技能交易平台上？人们如何提交技能信息？

我们没有一个集中决策的团队；相反，我们会尽量自然地发现最有用的技能。如果您有想让大家试用的技能，可以将其上传到 GitHub 的沙盒文件夹中，然后在 Slack 或其他论坛上分享给大家。

一旦某项技能获得关注（这取决于技能所有者的决定），他们就可以提交 PR 将其推向市场。

需要提醒的是，很容易创建不好的或冗余的技能，因此在发布之前确保有一些审核方法非常重要。

作曲技巧

您可能需要一些相互依赖的技能。例如，您可以创建一个文件上传技能来上传文件，以及一个 CSV 生成技能来生成并上传 CSV 文件。目前，市场或技能库尚未原生支持这种依赖关系管理，但您可以直接通过名称引用其他技能，如果这些技能已安装，模型会自动调用它们。

技能评估

为了解某项技能的使用情况，我们使用 PreToolUse 钩子来记录公司内部的技能使用情况（示例代码如下这意味着我们可以发现一些热门技能，或者与我们的预期相比，这些技能的触发程度较低。

结论

技能是经纪人非常强大、灵活的工具，但目前还处于早期阶段，我们都在摸索如何才能最好地使用它们。

与其说这是一份权威指南，不如说它更像是一个实用技巧大全，汇集了我们亲身实践过的有效方法。掌握技能的最佳途径就是动手实践，不断尝试，找出适合自己的方法。我们的大多数技巧最初都只是寥寥几行代码和一个小小的陷阱，随着克劳德遇到新的极端情况，大家不断补充完善，技巧也随之不断改进。

希望这对您有所帮助，如有任何疑问，请随时联系我。