技能已成为 Claude Code 中使用最广泛的扩展点之一。它们灵活、易于创建、灵活运用，且方便分享。
但正是这种灵活性，也让人难以把握最佳实践。究竟哪些类型的技能值得制作？写出好技能的秘诀是什么？何时应该与团队分享？
在 Anthropic，我们内部广泛使用 Claude Code 的技能，已经有数百个技能处于活跃使用中。以下是我们关于如何利用技能加速开发的宝贵经验。
什么是技能？
如果你对技能还不熟悉，我建议你先阅读我们的文档，或者观看我们在 Skilljar 上关于 Agent 技能的最新课程。本文假定你已经对技能有了一定的了解。
一个常见的误解是，技能就是单纯的 Markdown 文件。但技能最有趣的地方在于，它们不仅仅是文本文件，更是包含脚本、资源、数据等的文件夹，Agent 可以自行发现、探索和操作这些内容。
在 Claude Code 中，技能还拥有丰富的配置选项，包括注册动态钩子。
我们发现，Claude Code 中一些最有趣的技能，恰恰是创造性地利用了这些配置选项和文件夹结构。
技能的类型
在整理了我们所有的技能后，我发现它们大致可以归为几类。最优秀的技能通常只属于其中一类；而那些效果不佳、令人困惑的技能往往横跨多个类别。这并非一个绝对的分类，但它能帮助你思考团队内部是否缺少某种类型的技能。
1. 库和 API 参考
解释如何正确使用某个库、CLI 或 SDK 的技能。这些技能既可以是针对内部库，也可以是针对 Claude Code 有时会出错的通用库。这类技能通常包含一个参考代码片段的文件夹，以及一份 Claude 在编写脚本时需要避开的"雷区"列表。
示例：
- billing-lib — 你的内部计费库：边缘情况、易错点等。
- internal-platform-cli — 你的内部 的每个子命令，附带使用场景示例。
- frontend-design — 让 Claude 更好地理解你的设计系统。
2. 产品验证
描述如何测试或验证代码是否正常工作的技能。这类技能通常与 Playwright、tmux 等外部工具结合使用来进行验证。
验证技能对于确保 Claude 的输出正确性非常有用。让一位工程师花上一周时间来精心打磨你的验证技能，是完全值得的。
可以考虑这样的技巧：让 Claude 录制其输出的视频，这样你可以精确地看到它测试过的内容；或者在每一步都强制执行程序化的状态断言。这些通常通过在技能中包含各种脚本来实现。
示例：
- signup-flow-driver — 在无头浏览器中运行注册→邮件验证→新手引导流程，每一步都有状态断言钩子。
- checkout-verifier — 使用 Stripe 测试卡驱动结账 ，验证账单是否正确落入了指定状态。
- tmux-cli-driver — 用于需要 TTY 的交互式 CLI 测试。
3. 数据获取与分析
连接你的数据和监控堆栈的技能。这些技能可能包含用于获取数据的库（带凭证）、特定的仪表盘 ID 等，以及关于常见工作流程或数据获取方式的说明。
示例：
- funnel-query — "哪些事件可以关联起来查看从注册到激活再到付费的转化"以及包含标准用户 ID 的表。
- cohort-compare — 比较两个用户群的留存率或转化率，标记统计显著的差异，并提供用户群定义的链接。
- grafana — 数据源 UID、集群名称、问题→仪表盘查找表。
4. 业务流程与团队自动化
将重复性工作流整合为一条命令的技能。这些技能通常指令相对简单，但可能依赖于其他技能或 MCP，结构更复杂。对于这类技能，将之前的结果保存在日志文件中，可以帮助模型保持一致，并在重复执行工作流时进行反思。
示例：
- standup-post — 汇聚你的工单追踪器、GitHub 活动和之前的 Slack 信息，格式化生成仅包含增量内容的站会报告。
- create-<ticket-system>-ticket — 强制执行模式（有效的枚举值、必填字段）以及创建后的工作流程（通知审核人、在 Slack 中发送链接）。
- weekly-recap — 已合并的 PR + 已关闭的工单 + 部署 → 格式化周报总结。
5. 代码脚手架与模板
为代码库中的特定功能生成框架模板的技能。你可以将这类技能与可组合的脚本结合使用。当你的脚手架搭建涉及无法仅用代码覆盖的自然语言需求时，它们尤其有用。
示例：
- new-<framework>-workflow — 使用你的注解来搭建一个新的服务/工作流/处理器。
- new-migration — 你的迁移文件模板以及常见易错点。
- create-app — 创建一个新的内部应用，并预配置好你的认证、日志和部署配置。
6. 代码质量与审查
在团队内部强制执行代码标准并辅助代码审查的技能。这些技能可以包含确定性的脚本或工具，以实现最大程度的鲁棒性。你可能希望将这些技能作为钩子的一部分或在 GitHub Action 中自动运行。
示例：
- adversarial-review — 启动一个"新鲜视角"的子 Agent 进行批判性审查，实施修复，并不断迭代，直到发现的问题都变成无关紧要的挑刺。
- code-style — 强制执行代码风格，特别是 Claude 默认处理不好的那些。
- testing-practices — 关于如何编写测试以及测试哪些内容的说明。
7. CI/CD 与部署
帮助你获取、推送和部署代码的技能。这些技能可能会引用其他技能来收集数据。
示例：
- babysit-pr — 监控 PR，重试失败的 CI，解决合并冲突，启用自动合并。
- deploy-<service> — 构建→冒烟测试→逐步发布→逐步流量切换并比对错误率出现→出现回归时自动回滚。
- cherry-pick-prod — 隔离工作树→拣选提交提交→解决冲突→创建带有模板的 PR。
8. 操作手册 Runbooks
这些技能接收一个症状起始（例如一个 Slack 讨论串、一条告警或一个错误特征），然后逐步引导一个多工具的调查过程，并最终生成一份结构化的报告。
示例：
- <service>-debugging — 为你的高流量服务将症状映射到工具和查询模式。
- oncall-runner — 获取告警信息，检查常见原因，格式化并给出发现。
- log-correlator — 给定一个请求 ID，从所有可能处理过该请求的系统中拉取对应的日志进行关联。
9. 基础设施运维
执行常规维护和运维操作的技能——其中一些可能涉及破坏性操作，因此适合加入防护措施。这些技能可以让工程师在执行关键操作时更易于遵循最佳实践。
示例：
- <resource>-orphans — 发现孤立的 Pod/卷→发布到 Slack→等待一个静默期→用户确认→进行级联清理。
- dependency-management — 你的组织依赖审批流程。
- cost-investigation — "为什么我们的存储/出站流量费用飙升了？"，并提供特定的存储桶和查询模式来分析。
制作技能的技巧
一旦决定了要制作什么技能，该如何编写呢？以下是我们总结的一些最佳实践、技巧和妙招。
我们还最近发布了技能创建器 Skill Creator，让在 Claude Code 中创建技能变得更加容易。
不要陈述显而易见的内容
Claude Code 对你的代码库了解很多，Claude 本身也了解很多编码知识，包括许多默认的偏好。如果你要发布的技能主要是知识性的，请尽量聚焦于那些能推动 Claude 跳出其常规思维方式的信息。
前端设计技能就是一个很好的例子——它由 Anthropic 的一位工程师与客户合作，通过不断迭代来提升 Claude 的设计品味，避免使用像 Inter 字体和紫色渐变这类经典模式。
建立一个"雷区"部分
在任何技能中，信息密度最高的部分就是"雷区"部分。这些部分应该建立在 Claude 使用你的技能时常出错的点上。理想情况下，你应该随着时间推移不断更新你的技能，以捕获这些易错点。
善用文件系统和渐进式信息揭示
如前所述，技能是一个文件夹，而不仅仅是一个 Markdown 文件。你应该将整个文件系统视为一种上下文工程和渐进式信息揭示的方式。告诉 Claude 你的技能文件夹里有哪些文件，它会在合适的时机去读取它们。
最简单的渐进式揭示方式就是指向其他 Markdown 文件供 Claude 使用。例如，你可以将详细的函数签名和使用示例拆分到 references/api.md 中。
另一个例子：如果你的最终输出是一个 Markdown 文件，你可以在 assets/ 文件夹中包含一个模板文件，供 Claude 复制和使用。
你可以有引用、脚本、示例等文件夹，这能帮助 Claude 更有效地工作。
避免过度约束 Claude
Claude 通常会倾向于严格遵守你的指令。由于技能的复用性很高，因此你需要小心，避免指令过于具体。给予 Claude 所需的信息，但同时也要给它根据实际情况调整的灵活性。例如：
考虑好设置步骤
某些技能可能需要用户提供上下文来进行设置。例如，如果你正在制作一个将站会报告发布到 Slack 的技能，你可能希望 Claude 询问用户应该发布到哪个 Slack 频道。
一个好的模式是，像上面的例子那样，将这些设置信息存储在技能目录下的 config.json 文件中。如果配置尚未设置，Agent 就可以向用户询问信息。
如果你希望 Agent 提供结构化的多项选择问题，可以指示 Claude 使用 AskUserQuestion 工具。
描述字段是为模型准备的
当 Claude Code 启动一个会话时，它会构建一个列表，列出所有可用的技能及其描述。Claude 通过扫描这个列表来决定"某个请求是否有对应的技能？"这意味着描述字段不是一个摘要，而是一个关于何时应该触发此技能的描述。
记忆与数据存储
一些技能可以通过在自身内部存储数据来实现某种形式的记忆功能。你可以将数据存储在简单的追加写入文本日志文件或 JSON 文件中，也可以存储在更复杂的 SQLite 数据库中。
例如，一个 standup-post 技能可能会保留一个 standups.log 文件，记录每一次写过的帖子。这样，下次你运行它时，Claude 会读取自己的历史记录，并能分辨出自上次以来发生了什么变化。
需要注意的是，存储在技能目录中的数据可能会在你升级技能时被删除。因此，你应将数据存储在一个稳定的文件夹中。目前，我们为每个插件提供了 ${CLAUDE_PLUGIN_DATA} 作为稳定的数据存储文件夹。
存放脚本并生成代码
你能给 Claude 的最强大的工具之一就是代码。为 Claude 提供脚本和库，可以让 Claude 把更多精力花在组合和决策上，而不是重构。
例如，在数据科学技能中，你可以有一个函数库来从事件源获取数据。为了让 Claude 进行复杂的分析，你可以给它一组辅助函数，如下所示：
然后，Claude 可以动态生成脚本，组合这些功能，以响应诸如"周二发生了什么？"这样的提示，进行更高级的分析。
按需钩子
技能可以包含仅在技能被调用时才激活的钩子，其效果持续整个会话。适用于那些你不想一直运行，但有时却极其有用的、更具针对性的钩子。
例如：
/careful— 通过PreToolUse 匹配器在 Bash 上触发，用于阻止 、DROP TABLE、强制推送、kubectl delete`。你只会在触碰生产环境时想要这个钩子——如果它一直开着，你会崩溃的。/freeze— 阻止任何不在特定目录中的编辑/写入操作。在调试时很有用："我只想添加日志，但我总是不小心'修复'了一些无关的东西"。
分享与分发技能
技能最大的优势之一在于你可以与团队其他成员分享。
有两种方式可以与其他人分享技能：
- 将你的技能检入到代码仓库中（放在
./.claude/skills目录下） - 创建一个插件，并建立一个 Claude Code 插件市场，供用户上传和安装插件（更多信息请阅读文档）
对于在相对较少的仓库上工作的小团队来说，将技能检入仓库效果很好。但每个检入的技能都会给模型的上下文增加一点点负载。随着团队规模扩大，一个内部的插件市场可以让你分发技能，并让你的团队决定哪些需要安装。
管理插件市场
如何决定哪些技能应该进入市场？人们如何提交技能？
我们没有集中的团队来决定；相反，我们尝试有机地发现最有用的技能。如果你有一个技能想让别人试用，你可以将它上传到 GitHub 的一个沙箱文件夹，并在 Slack 或其他论坛上分享。
一旦一个技能获得了关注度（由技能所有者自己判断），他们可以提交一个 PR 将其移入市场。
值得注意的是，创建低质量或冗余的技能是很容易的，因此在发布前确保有一定的方法进行筛选非常重要。
组合技能
你可能希望技能之间能够相互依赖。例如，你可能有一个文件上传技能，还有一个 CSV 生成技能，它生成 CSV 后上传。这种依赖管理目前还没有内置在市场或技能中，但你只需按名称引用其他技能，如果这些技能已安装，模型就会调用它们。
衡量与评估技能
为了了解技能的表现，我们使用一个 PreToolUse 钩子来记录公司内部技能的使用情况（示例代码）。这使我们能够发现哪些技能是受欢迎的，或者哪些技能的使用频率低于预期。
总结
技能是强大、灵活的工具，用于 Agent，但这仍然处于早期阶段，我们都在摸索最佳的使用方法。
请将这些内容看作是我们观察到的有用技巧合集，而非一份权威指南。理解技能的最佳方式是开始动手，进行实验，看看什么对你有效。我们的大部分技能都是从寥寥几句描述和一个雷区开始的，然后因为人们不断添加 Claude 遇到的新边界情况而变得更好。
希望这篇文章对你有帮助，如有任何问题，请与我联系。
