Anthropic内部Skills开发秘籍：从实战经验到最佳实践（第一部分）

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

但这种灵活性也带来了一个问题：很难判断什么才是最佳实践。什么类型的 Skills 值得开发？写出一个优秀 Skill 的秘诀是什么？又应该在什么时候将它们分享给他人？

在 Anthropic 内部，我们已经在 Claude Code 中广泛使用 Skills，目前有数百个 Skills 在实际运行中。

以下是我们使用 Skills 来加速开发过程中总结的一些经验。

什么是 Skills？

如果你刚接触 Skills，建议先阅读官方文档：

相关链接：https://code.claude.com/docs/en/skills

本文默认你已经对 Skills 有一定了解。

我们经常听到一个常见的误解：认为 Skills“只是一些 Markdown 文件”。但实际上，Skills 最有趣的地方在于——它们并不仅仅是文本文件，而是一个文件夹，里面可以包含脚本、资源、数据等内容，供智能体进行发现、探索和操作。

在 Claude Code 中，Skills 还具备多种配置选项，包括注册动态钩子（hooks）等。

相关链接：https://code.claude.com/docs/en/skills#frontmatter-reference

我们发现，一些最有意思的 Skills，正是通过巧妙利用这些配置选项和文件结构来实现的。

Skills 类型

在整理我们所有 Skills 之后，我们发现它们大致可以分为几个常见的类别。

最好的 Skills 通常能够清晰地归类到一个类别中，而那些更为复杂或难以理解的 Skills，则可能跨越多个类别。这并不是一个权威的分类列表，但它为你判断在你的组织中是否缺少某些类型的 Skills 提供了一个很好的思路。

1. 库与 API 参考

这些 Skills 解释如何正确使用库、CLI 或 SDK。这些 Skills 可以是针对内部库，也可以是针对 Claude Code 在使用常见库时遇到困难的库。它们通常包含一组参考代码片段，以及 Claude 在编写脚本时应避免的一些常见问题。

示例：
* billing-lib — 你的内部账单库：边缘情况、常见陷阱等
* internal-platform-cli — 你内部 CLI 包装器的每个子命令，并提供何时使用它们的示例
* frontend-design — 使 Claude 更好地理解你的设计系统

2. 产品验证

这些 Skills 描述了如何测试或验证代码是否正常工作。它们通常与外部工具（如 Playwright、tmux 等）配合使用，以进行验证。

验证 Skills 对确保 Claude 输出正确非常有用。可能值得让工程师花一周时间，专注于提高验证 Skills 的质量。

考虑使用技术，例如让 Claude 记录它的输出视频，这样你就可以准确看到它测试了什么，或者在每个步骤上强制进行状态的程序化断言。这些通常通过在 Skills 中包含各种脚本来实现。

示例：
* signup-flow-driver — 在无头浏览器中运行注册 → 邮件验证 → 入职流程，并在每个步骤上进行状态断言
* checkout-verifier — 使用 Stripe 测试卡驱动结账界面，验证发票是否真正落入正确的状态
* tmux-cli-driver — 用于需要 TTY 的交互式 CLI 测试

3. 数据抓取与分析

这些 Skills 连接到你的数据和监控系统。这些 Skills 可能包括库，用于通过凭证、特定的仪表盘 ID 等抓取数据，以及常见工作流或获取数据的方式说明。

示例：
* funnel-query — “我需要哪些事件来查看注册 → 激活 → 付费” 以及实际包含标准 user_id 的表
* cohort-compare — 比较两个群体的留存率或转化率，标记统计显著的差异，链接到细分定义
* grafana — 数据源 UID、集群名称、问题 → 仪表盘查找表

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

这些 Skills 将重复的工作流自动化为一个命令。虽然这些 Skills 通常是相对简单的指令，但可能有更复杂的依赖关系，涉及其他 Skills 或 MCP（多控制点）。

对于这些 Skills，将先前的结果保存在日志文件中有助于保持模型的一致性，并反映工作流的前期执行。

示例：
* standup-post — 汇总你的任务追踪器、GitHub 活动和 Slack 内容 → 格式化的站立会议，仅显示增量变化
* create–ticket — 强制执行模式（有效的枚举值、必填字段）以及创建后工作流（通知审阅者、在 Slack 中链接）
* weekly-recap — 合并的 PR + 关闭的票据 + 部署 → 格式化的周报

5. 代码脚手架与模板

这些 Skills 用于生成代码库中特定功能的框架模板。你可以将这些 Skills 与可组合的脚本结合使用。它们在你的脚手架有自然语言要求，而这些要求无法仅通过代码覆盖时尤为有用。

示例：
* new–workflow — 使用你的注释脚手架一个新的服务 / 工作流 / 处理器
* new-migration — 你的迁移文件模板以及常见的坑
* create-app — 新的内部应用，预先配置你的认证、日志记录和部署

6. 代码质量与审核

这些 Skills 强制执行你组织中的代码质量并帮助审查代码。它们可以包括确定性的脚本或工具，以确保最大程度的稳健性。你可能希望将这些 Skills 自动运行，作为钩子的一部分或 GitHub Actions 中的一部分。

示例：
* adversarial-review — 启动一个新鲜眼光的子智能体进行批评，实施修复，迭代直到反馈降级为小瑕疵
* code-style — 强制执行代码风格，特别是 Claude 默认处理不好的一些风格
* testing-practices — 关于如何编写测试以及需要测试什么的说明

7. CI/CD 与部署

7. 代码操作

这些 Skills 帮助你在代码库内执行获取、推送和部署代码等操作。它们可以引用其他 Skills 来收集必要的数据。

示例：
* babysit-pr — 监控 PR → 重试不稳定的 CI → 解决合并冲突 → 启用自动合并
* deploy — 构建 → 烟雾测试 → 渐进式流量发布与错误率比较 → 回滚
* cherry-pick-prod — 隔离工作树 → 衍生选择 → 冲突解决 → 创建带模板的 PR

8. 运行手册

这些 Skills 通过症状（如 Slack 线程、警报或错误签名）触发，执行多工具调查，并生成结构化的诊断报告。

示例：
* debugging — 映射症状 → 工具 → 查询模式，适用于高流量服务
* oncall-runner — 获取警报 → 检查常见问题 → 格式化结果
* log-correlator — 根据给定的请求 ID，从所有相关系统中提取匹配的日志

9. 基础设施操作

这些 Skills 执行常规的维护和操作程序，其中一些涉及需要防护措施的破坏性操作。它们旨在帮助工程师遵循最佳实践，避免在关键操作中出错。

示例：
* clean-orphans — 查找孤立的 pods/volumes → 发布到 Slack → 浸泡期 → 用户确认 → 级联清理
* dependency-management — 实现你组织的依赖审批工作流
* cost-investigation — 调查“为什么我们的存储/出站流量账单突然飙升”，并提供具体的存储桶和查询模式

制作 Skills 的技巧

一旦你决定要制作某个 Skill，如何编写它呢？以下是我们总结的一些最佳实践、技巧和窍门。

不要陈述显而易见的内容

Claude Code 已经对你的代码库和编码基础知识有相当的了解。如果你的 Skill 主要是传递知识，请专注于那些能让 Claude 脱离常规思维模式的信息。

示例：
“前端设计” Skill 就是一个很好的例子。它旨在提升 Claude 的设计品味，避免使用某些经典但可能过时的设计模式。

构建“陷阱”部分

在任何 Skill 中，“常见陷阱”部分都是最有价值的内容之一。这部分应基于 Claude 在使用该 Skill 时遇到的常见失败点来构建。理想情况下，你应该随着时间推移更新 Skill，不断纳入这些常见问题，以确保其有效性和准确性。

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

Skill 是一个文件夹，而不仅仅是一个 Markdown 文件。你应该将整个文件系统视为一种上下文工程和渐进式披露的手段。告诉 Claude 你的 Skill 包含哪些文件，它会在适当时机读取它们。

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

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

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

避免“束缚” Claude

Claude 通常会尽力遵循你的指示。然而，由于 Skills 具有高度可复用性，你需要小心避免让指令过于具体。给予 Claude 必要的信息，同时也要留出一定的灵活性以适应不同的情况。

思考 Skill 的设置

有些 Skills 可能需要用户提供上下文信息来完成设置。例如，如果你在制作一个将站会内容发布到 Slack 的 Skill，你可能希望 Claude 询问要发布到哪个 Slack 频道。

一种良好的做法是将这些设置信息存储在 Skill 目录中的 config.json 文件中。如果配置尚未设置，智能体可以提示用户提供必要的信息。

如果你希望智能体呈现结构化的多选问题，可以指示 Claude 使用 AskUserQuestion 工具。

描述字段是给模型的

当 Claude Code 启动一个会话时，它会构建一个包含每个可用 Skill 及其描述的列表。这份列表是 Claude 用来决定“是否有 Skill 能解决这个请求？”的依据。因此，描述字段并非 Skill 的总结，而是描述何时触发该 Skill 的场景。

记忆与存储数据

有些 Skills 可以通过在其内部存储数据来实现一定的记忆功能。你可以将数据存储在简单的附加文本日志文件、JSON 文件，或者更复杂的 SQLite 数据库中。

例如：
一个 standup-post Skill 可能会维护一个 standups.log 文件，记录每次发布的内容。这意味着下次运行时，Claude 可以读取自己的历史记录，并能够检测自昨天以来的变化。

需要注意的是，存储在 Skill 目录中的数据可能在 Skill 升级时被删除，因此你应当将数据存储在一个稳定的文件夹中。

存储脚本与生成代码

提供代码是赋予 Claude 最强大的工具之一。将脚本和库交给 Claude，可以让它专注于组合和决策，而不是重新构建基础代码。

例如：
在你的数据科学 Skill 中，你可能有一组用于从事件源抓取数据的函数库。为了让 Claude 执行复杂的分析，你可以为它提供一套帮助函数。

Claude 然后可以动态生成脚本，利用这些功能组合来执行更高级的分析，比如处理类似“星期二发生了什么？”这样的提示。

按需钩子

Skills 可以包含仅在 Skill 被调用时才激活的钩子，并且这些钩子的作用仅持续到当前会话结束。这对于一些有强烈偏好、但并不希望一直运行的钩子特别有用。

示例：
* /careful — 通过 Bash 中的 PreToolUse 匹配器阻止 rm -rf、DROP TABLE、force-push、kubectl delete 等危险操作。你只希望在知道自己正在操作生产环境时才启用它。
* /freeze — 阻止在特定目录外的任何编辑/写入操作。当你想确保更改仅发生在特定文件夹中时，这非常有用。

调试技巧：使用按需钩子

在调试过程中，开发者常面临一个困境：“我想添加日志，但又担心无意中‘修复’了无关的代码。” 使用按需钩子可以有效解决此问题。这类钩子仅在特定条件下触发，而非始终保持启用状态。这既能避免对无关文件或代码片段造成不必要的干扰，又能在你需要深入排查时，提供强有力的辅助功能。

Skills 的分发与共享

Skills 的核心优势之一是便于在团队内部共享。你可以通过以下两种方式分发 Skills：

1. 检入代码库：将 Skills 文件存放在项目目录的 ./.claude/skills 路径下，并随代码库一同管理。
2. 发布至插件市场：创建一个插件，并将其上传至 Claude Code 插件市场。其他用户可以从市场中发现并安装你的插件。（更多详情请参阅官方文档。）

如何选择？
对于在少量代码库中协作的小型团队，将 Skills 检入代码库是简单直接的选择。但需注意，每个被检入的 Skills 都会略微增加模型的上下文负担。当团队规模扩大、项目增多时，建立一个内部插件市场会是更优方案。它允许你集中管理 Skills 的分发，并让团队成员自主决定安装哪些 Skills。

管理内部市场

一个常见的问题是：如何决定哪些 Skills 可以进入市场？以及人们如何提交？

我们的实践是去中心化的，而非依赖一个集中审核团队。我们鼓励通过自然涌现的方式发现最有用的 Skills。流程大致如下：
1. 沙箱分享：如果你开发了一个 Skills 并希望他人试用，可以将其上传至一个共享的沙箱目录（例如 GitHub 上的特定文件夹），并通过 Slack 等内部渠道分享链接。
2. 晋升流程：当一个 Skills 获得足够的关注和使用后（由 Skills 的维护者判断），可以通过提交 Pull Request 的方式，申请将其正式移入市场。

重要提示：创建不必要或功能冗余的 Skills 非常容易。因此，在正式发布前，建立一套筛选和评估机制至关重要。

组合使用 Skills

你可能会遇到需要多个 Skills 协同工作的场景。例如，一个 Skills 负责生成 CSV 文件，另一个则负责上传文件。目前，Skills 系统或市场并未内置官方的依赖管理功能。但是，你可以通过直接在其他 Skills 的代码中按名称引用已安装的 Skills。如果这些被引用的 Skills 已安装，模型在运行时将会调用它们。

衡量 Skills 效果

为了评估 Skills 的实际效用，我们利用了 PreToolUse 钩子来记录公司内部 Skills 的调用情况。通过分析这些使用数据，我们可以：
* 识别出哪些 Skills 最受欢迎、使用频率最高。
* 发现哪些 Skills 的触发率低于预期，从而可能需要优化或调整。

这为我们持续改进 Skills 的质量和相关性提供了数据支持。

结语

Skills 是极其强大且灵活的工具，但目前生态系统仍处于早期阶段，最佳实践仍在不断演进中。

本文所分享的内容，源于我们在实战中积累的经验与教训，旨在提供一些有用的提示，而非权威定论。理解并掌握 Skills 的最佳方式，就是立即开始动手实践，大胆实验，找到最适合你与团队的工作流程。

我们团队中的许多 Skills，最初都只是源于一行代码和一个特定的痛点（“Gotcha”）。随着 Claude 在处理各种边界情况中不断学习，这些 Skills 也在社区的贡献下被逐步完善和增强。

关注“鲸栖”小程序，掌握最新AI资讯