我们如何使用好AI工具的技能 (Skills)

我们如何使用好AI工具的技能 (Skills)

构我们如何使用技能 (Skills)

技能 (Skills) 已成为 Claude Code/ Open Code 等编成工具中最常用的扩展点之一。它们灵活、易于制作且分发简单。 但这种灵活性也使得很难知道什么才是最有效的。什么样的技能值得制作？写好一个技能的秘诀是什么？什么时候应该与他人分享它们？ 我借鉴了 Anthropic 广泛使用 Claude Code 中的技能，目前有数百个技能正在活跃使用中。以下是我们关于利用技能加速开发所学到的经验。

什么是技能 (Skills)？

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

我们听到的一个常见误解是，技能“只是 markdown 文件”，但技能最有趣的部分在于它们不仅仅是文本文件。它们是文件夹，可以包含脚本、资产、数据等，代理可以发现、探索和操作这些内容。 在 Claude Code 中，技能还拥有各种配置选项，包括注册动态钩子 (hooks)。 我们发现，Claude Code 中一些最有趣的技能都创造性地使用了这些配置选项和文件夹结构。

技能的类型

在对所有技能进行分类后，我们注意到它们聚集成几个重复出现的类别。最好的技能能清晰地归入其中一类；而更令人困惑的技能则横跨几类。这不是一个详尽的列表，但它是一个很好的方式，用来思考您的组织是否缺少某些类型的技能。

1. 库与 API 参考 (Library & API Reference) 解释如何正确使用库、CLI 或 SDK 的技能。这些既可以是内部库，也可以是 Claude Code 有时会遇到困难的常用库。这些技能通常包含一个参考代码片段文件夹，以及一份供 Claude 在编写脚本时避免的“陷阱”(gotchas) 列表。 示例：
   • billing-lib — 您的内部计费库：边缘情况、潜在陷阱等。
   • internal-platform-cli — 您的内部 CLI 包装器的每个子命令，并附带何时使用它们的示例。
   • frontend-design — 让 Claude 更擅长您的设计系统。

2. 产品验证 (Product Verification) 描述如何测试或验证代码是否正常工作的技能。这些技能通常与外部工具（如 Playwright, tmux 等）配对使用以进行验证。 验证技能对于确保 Claude 的输出正确性极其有用。值得让工程师花一周时间专门将您的验证技能做得非常出色。 考虑采用诸如让 Claude 录制其输出的视频，以便您可以确切地看到它测试了什么，或者在每一步强制对状态进行编程断言等技术。这些通常通过在技能中包含各种脚本来实现。 示例：

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

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 — 强制执行模式（有效的枚举值、必填字段）以及创建后的工作流（通知审查者、在 Slack 中链接）。
   • weekly-recap — 合并的 PR + 关闭的工单 + 部署 → 格式化的周报帖子。

5. 代码脚手架与模板 (Code Scaffolding & Templates) 为代码库中的特定功能生成框架样板代码的技能。您可以将这些技能与可组合的脚本结合起来。当您的脚手架具有无法纯粹通过代码覆盖的自然语言要求时，它们尤其有用。 示例：

   • new-<framework>-workflow — 使用您的注释搭建新的服务/工作流/处理器。
   • new-migration — 您的迁移文件模板加上常见的陷阱。
   • create-app — 新的内部应用，已预配置好您的认证、日志记录和部署配置。

6. 代码质量与审查 (Code Quality & Review) 在您组织内强制执行代码质量并帮助审查代码的技能。这些可以包括用于最大稳健性的确定性脚本或工具。您可能希望作为钩子的一部分或在 GitHub Action 中自动运行这些技能。 示例：

   • adversarial-review — 生成一个“新鲜视角”的子代理进行批评，实施修复，迭代直到发现退化为吹毛求疵。
   • 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 — 给定一个请求 ID，从每个可能接触过它的系统中拉取匹配的日志。

9. 基础设施运维 (Infrastructure Operations) 执行例行维护和操作程序的技能——其中一些涉及需要从防护措施中受益的破坏性操作。这些使工程师更容易在关键操作中遵循最佳实践。 示例：

   • <resource>-orphans — 查找孤立的 pod/卷 → 发布到 Slack → 浸泡期 → 用户确认 → 级联清理。
   • dependency-management — 您组织的依赖项批准工作流。
   • cost-investigation — “为什么我们的存储/出口账单激增”，包含具体的存储桶和查询模式。

制作技能的技巧

一旦决定了要制作的技能，该如何编写呢？以下是我们发现的一些最佳实践、技巧和窍门。 我们最近还发布了 Skill Creator，以更轻松地在 Claude Code 中创建技能。

• 不要陈述显而易见的内容 Claude Code 对您的代码库了解很多，Claude 也对编码了解很多，包括许多默认观点。如果您发布的技能主要是关于知识的，请尝试专注于能将 Claude 推出其正常思维方式的信息。 前端设计技能就是一个很好的例子——它是由 Anthropic 的一位工程师通过与客户迭代改进 Claude 的设计品味而构建的，避免了像 Inter 字体和紫色渐变这样的经典模式。

• 建立“缺陷”(Gotchas) 规则部分 任何技能中信号最高的内容是“陷阱”(Gotchas) 部分。这些部分应根据 Claude 在使用您的技能时遇到的常见失败点来构建。理想情况下，您将随着时间的推移更新您的技能以捕获这些陷阱。

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

• 避免限制 Claude (Avoid Railroading Claude) Claude 通常会尝试坚持您的指示，并且由于技能非常可重用，因此在指示中过于具体时需要小心。给 Claude 它需要的信息，但也要给它适应情况的灵活性。例如：

• 仔细考虑设置 (Think through the Setup) 有些技能可能需要用户提供的上下文进行设置。例如，如果您正在制作一个将站会报告发布到 Slack 的技能，您可能希望 Claude 询问要发布到哪个 Slack 频道。 一个好的模式是将此设置信息存储在技能目录中的 config.json 文件中，如上例所示。如果配置未设置，代理随后可以向用户询问信息。 如果您希望代理提出结构化的多项选择题，您可以指示 Claude 使用 AskUserQuestion 工具。

• 描述字段是给模型看的 (The Description Field Is For the Model) 当 Claude Code 启动会话时，它会构建每个可用技能及其描述的列表。Claude 会扫描此列表以决定“是否有针对此请求的技能？”这意味着描述字段不是摘要——它是关于何时触发此技能的描述。

• 记忆与数据存储 (Memory & Storing Data) 有些技能可以通过在其中存储数据来包含某种形式的记忆。您可以将数据存储在简单的只追加文本日志文件或 JSON 文件中，也可以存储在复杂的 SQLite 数据库中。 例如，standup-post 技能可能会保留一个 standups.log，记录它编写的每篇帖子，这意味着下次运行它时，Claude 会读取自己的历史记录，并能告诉您自昨天以来发生了什么变化。 技能目录中存储的数据可能在升级技能时被删除，因此您应该将其存储在稳定的文件夹中。截至目前，我们提供 ${CLAUDE_PLUGIN_DATA} 作为每个插件存储数据的稳定文件夹。

• 存储脚本与生成代码 (Store Scripts & Generate Code) 您可以赋予 Claude 的最强大工具之一就是代码。给 Claude 脚本和库可以让 Claude 将其回合用于组合，决定下一步做什么，而不是重构样板代码。 例如，在您的数据科学技能中，您可能有一个函数库来从事件源获取数据。为了让 Claude 进行复杂分析，您可以给它一组辅助函数，如下所示： （此处原文应有代码示例，但用户提供的文本中省略了具体代码块） 然后，Claude 可以即时生成脚本来组合此功能，以进行更高级的分析，以响应诸如“周二发生了什么？”之类的提示。

• 按需钩子 (On Demand Hooks) 技能可以包含仅在调用技能时激活并在会话持续期间存在的钩子。将此用于您不希望一直运行但有时非常有用的更有主见的钩子。 例如：

  • /careful — 通过 Bash 的 PreToolUse 匹配器阻止 rm -rf, DROP TABLE, force-push, kubectl delete。您只希望在确定要接触生产环境时才使用它——如果一直开启会把您逼疯。
  • /freeze — 阻止任何不在特定目录中的编辑/写入操作。在调试时很有用：“我想添加日志，但我总是不小心‘修复’了无关的代码”。

分发技能 (Distributing Skills)

技能的最大好处之一是您可以与团队的其余成员分享它们。 有两种方法可以与他人分享技能：

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

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

管理市场 (Managing a Marketplace)

如何决定哪些技能进入市场？人们如何提交它们？ 我们没有专门的团队来决定；相反，我们尝试有机地找到最有用的技能。如果您有一个希望人们尝试的技能，可以将其上传到 GitHub 中的沙盒文件夹，并在 Slack 或其他论坛中引导人们前往。 一旦某个技能获得了关注（由技能所有者决定），他们可以提交 PR 将其移入市场。 需要注意的是，创建糟糕或冗余的技能非常容易，因此在发布前确保您有一些策划方法非常重要。

组合技能 (Composing Skills)

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

衡量技能 (Measuring Skills)

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

结论

技能是代理极其强大、灵活的工具，但这仍处于早期阶段，我们都在摸索如何最好地使用它们。 将此更多地视为我们见过有效的有用技巧的大杂烩，而不是一份权威指南。理解技能的最佳方式是开始动手、实验，看看什么对您有效。我们大多数技能开始时只有几行和一个陷阱，之所以变得更好，是因为人们在 Claude 遇到新的边缘情况时不断对其进行补充。