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

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

但这种灵活性也使得难以分辨哪些最有效。哪种类型的 skills 值得开发？编写一个好的 skill 的秘诀是什么？何时与他人分享它们？

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

什么是技能 (Skills)？

如果你是技能新手，我建议你阅读我们的文档或观看我们在 Skilljar 上关于 Agent Skills 的最新课程，本文假设你已经对技能有所了解。

我们听到关于技能的一个常见误解是它们“只是 Markdown 文件”，但技能最有趣的部分在于它们不仅仅是文本文件。它们是文件夹，可以包含代理可以发现、探索和操作的脚本、资产、数据等。

在 Claude Code 中，技能还具有多种配置选项，包括注册动态Hook。

我们发现 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 — 在无头浏览器中运行注册 → 邮件验证 → 入职流程，并在每个步骤都有状态断言的Hook。
• checkout-verifier — 使用 Stripe 测试卡驱动结账 UI，验证发票是否实际处于正确状态。
• tmux-cli-driver — 用于交互式 CLI 测试，其中需要验证的对象需要 TTY。

3. 数据获取与分析

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

示例：

• funnel-query — “我应该连接哪些事件才能看到注册 → 激活 → 付费”以及实际包含规范 user_id 的表。
• cohort-compare — 比较两个群组的留存率或转化率，标记统计上显著的差异，链接到细分定义。
• grafana — 数据源 UID、集群名称、问题 → 仪表板查找表。

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

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

示例：

• standup-post — 聚合你的工单跟踪器、GitHub 活动和之前的 Slack → 格式化的站会报告，仅显示增量。
• create-<ticket-system>-ticket — 强制执行模式（有效的枚举值、必填字段）以及创建后的工作流（ping 审阅者，在 Slack 中链接）。
• weekly-recap — 合并的 PR + 关闭的工单 + 部署 → 格式化的回顾报告。

5. 代码脚手架与模板

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

示例：

• new-<framework>-workflow — 使用你的注解搭建新的服务/工作流/处理程序。
• new-migration — 你的迁移文件模板以及常见陷阱。
• create-app — 预先配置了你的身份验证、日志记录和部署配置的新内部应用程序。

6. 代码质量与审查

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

• adversarial-review — 派生一个“新视角”子代理进行批判，实施修复，迭代直到发现的问题降级为小问题。
• code-style — 强制执行代码风格，特别是 Claude 默认不擅长的风格。
• testing-practices — 关于如何编写测试以及测试什么的说明。

7. CI/CD 与部署

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

示例：

• babysit-pr — 监控 PR → 重试不稳定的 CI → 解决合并冲突 → 启用自动合并。
• deploy-<service> — 构建 → 冒烟测试 → 逐步流量 rollout 并比较错误率 → 自动回滚（如果出现回归）。
• cherry-pick-prod — 隔离工作树 → cherry-pick → 冲突解决 → 带模板的 PR。

8. 运行手册

技能接受一个症状（例如 Slack 线程、告警或错误签名），通过多工具调查，并生成结构化报告。

示例：

• <service>-debugging — 将症状 → 工具 → 查询模式映射到你流量最大的服务。
• oncall-runner — 获取告警 → 检查常见问题 → 格式化发现。
• log-correlator — 给定一个请求 ID，从所有可能涉及的系统中拉取匹配的日志。

9. 基础设施运维

执行日常维护和操作程序的技能 — 其中一些涉及破坏性操作，需要防护措施。这些使得工程师更容易在关键操作中遵循最佳实践。

示例：

• <resource>-orphans — 查找孤立的 Pods/卷 → 发布到 Slack → 浸泡期 → 用户确认 → 级联清理。
• dependency-management — 你的组织的依赖审批工作流。
• cost-investigation — “为什么我们的存储/出口费用飙升”，附带具体的存储桶和查询模式。

制作技能的技巧

一旦你决定了要制作的技能，你该如何编写它呢？这些是我们发现的一些最佳实践、技巧和窍门。

我们最近还发布了 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 文件中，如上例所示。如果未设置配置，代理可以询问用户提供信息。

如果你希望代理呈现结构化的多项选择问题，你可以指示 Claude 使用 AskUserQuestion 工具。

描述字段是为模型准备的

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

内存与数据存储

有些技能可以通过在其中存储数据来包含某种形式的内存。你可以将数据存储在像只追加文本日志文件或 JSON 文件一样简单的东西中，也可以存储在像 SQLite 数据库一样复杂的东西中。

例如，一个 standup-post 技能可能会保留一个 standups.log 文件，其中包含它编写的每个帖子，这意味着下次你运行它时，Claude 会读取它自己的历史记录，并能判断自昨天以来发生了什么变化。

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

存储脚本和生成代码

你能给予 Claude 最强大的工具之一就是代码。给予 Claude 脚本和库让 Claude 可以将精力花在组合上，决定下一步做什么，而不是重建样板代码。

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

然后，Claude 可以即时生成脚本来组合这些功能，从而对“周二发生了什么？”这样的提示进行更高级的分析。

按需Hook

技能可以包含仅在调用技能时激活并持续整个会话的Hook。将其用于那些你不想一直运行，但在某些时候极其有用的、更具主观性的Hook。

例如：

• /careful — 通过 Bash 上的 PreToolUse 匹配器阻止 rm -rf、DROP TABLE、force-push、kubectl delete。你只希望在你知道要触及生产环境时才使用它 — 如果它一直开启会让你抓狂。
• /freeze — 阻止任何不在特定目录中的编辑/写入。在调试时很有用：“我想添加日志，但我总是意外地‘修复’不相关的部分。”

分发技能

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

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

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

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

管理市场

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

我们没有一个集中的团队来决定；相反，我们尝试有机地找到最有用的技能。如果你有一个想让人们尝试的技能，你可以将其上传到 GitHub 的沙盒文件夹中，并在 Slack 或其他论坛中指引人们。

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

一个警告：创建糟糕或冗余的技能很容易，因此在发布前确保你有一些策展方法很重要。

组合技能

你可能希望拥有相互依赖的技能。例如，你可能有一个文件上传技能用于上传文件，还有一个 CSV 生成技能用于创建 CSV 并上传它。这种依赖管理尚未原生内置到市场或技能中，但你可以通过名称引用其他技能，如果它们已安装，模型将调用它们。

衡量技能

为了了解一个技能的表现，我们使用 PreToolUse Hook，它允许我们记录公司内部的技能使用情况（示例代码在此处）。这意味着我们可以找到受欢迎的技能，或者与我们预期相比触发不足的技能。

结论

技能是代理极其强大、灵活的工具，但它仍处于早期阶段，我们都在探索如何最好地使用它们。

这更像是一个我们发现有效的有用技巧的集合，而不是一个明确的指南。理解技能的最佳方式是开始实践、实验，看看什么对你有效。我们的大多数技能最初都只有几行代码和一个注意事项，并随着 Claude 遇到新的边缘情况而不断改进。

希望这有所帮助，如果你有任何问题，请告诉我。

• 原文链接： x.com/trq212/status/2033...
• 登链社区 AI 助手，为大家转译优秀英文文章，如有翻译不通的地方，还请包涵～