Claude Code Skills 构建经验：Anthropic 如何使用 Skills 加速开发

这篇文章来自 Anthropic 工程师 Thariq (@trq212) 的深度分享，总结了 Anthropic 团队内部数百个 Skills 的实际使用经验，涵盖 Skills 的九大类型、编写技巧、分发策略以及组合使用方法。

Skills 是什么？

一个常见的误解是 Skills "只是 markdown 文件"，但实际上最有意思的部分是它们不只是文本文件。它们是可以包含脚本、资产、数据等的文件夹，agent 可以发现、探索和操作这些内容。

在 Claude Code 中，Skills 还有多种配置选项，包括注册动态 hooks。

我们注意到，一些最有趣的 Skills 创造性地使用了这些配置选项和文件夹结构。

Skills 的九大类型

在梳理了所有 Skills 后，我们发现它们聚集在几个重复出现的类别中。最好的 Skills 完美地属于其中一类；而更令人困惑的往往跨越了多个类别。

1. 库与 API 参考 (Library & API Reference)

解释如何正确使用库、CLI 或 SDK 的 Skills。这些可以是内部库或 Claude Code 有时处理不好的通用库。这些 Skills 通常包含一个参考代码片段文件夹和让 Claude 避免踩坑的注意事项列表。

示例：

• billing-lib — 你的内部计库：边界情况、容易出错的陷阱等
• internal-platform-cli — 内部 CLI 包装器的每个子命令，附带使用时机示例
• frontend-design — 让 Claude 更好地理解你的设计系统

2. 产品验证 (Product Verification)

描述如何测试或验证代码是否正常工作的 Skills。通常与 Playwright、tmux 等外部工具配对使用。

验证 Skills 对于确保 Claude 的输出正确极其有用。值得让工程师花一周时间把验证 Skills 做到极致。

可以考虑让 Claude 录制输出视频以便你看到它测试了什么，或在每个步骤对状态执行程序化断言。这些通常通过在 Skill 中包含各种脚本来实现。

示例：

• signup-flow-driver — 在无头浏览器中运行注册→邮件验证→引导流程，带有在每一步断言状态的钩子
• checkout-verifier — 使用 Stripe 测试卡驱动结账 UI，验证发票确实进入正确状态
• tmux-cli-driver — 用于交互式 CLI 测试，当你要验证的内容需要 TTY 时

3. 数据获取与分析 (Data Fetching & Analysis)

连接到你的数据和监控栈的 Skills。这些 Skills 可能包括带有凭据获取数据的库、特定仪表板 ID 等，以及常见工作流的指令。

示例：

• funnel-query — "我需要 join 哪些事件才能看到注册→激活→付费" 加上实际拥有规范 user_id 的表
• cohort-compare — 比较两个队列的留存或转化，标记统计显著的差异，链接到分群定义
• grafana — 数据源 UID、集群名称、问题→仪表板查找表

4. 业务流程与团队自动化 (Business Process & Team Automation)

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

示例：

• standup-post — 聚合你的工单跟踪器、GitHub 活动和之前的 Slack → 格式化站会报告，仅显示增量
• create-ticket — 强制执行 schema（有效枚举值、必填字段）加创建后工作流（@评审者、链接到 Slack）
• weekly-recap — 合并的 PR + 关闭的工单 + 部署 → 格式化周报

5. 代码脚手架与模板 (Code Scaffolding & Templates)

为代码库中特定功能生成框架样板代码的 Skills。你可以将这些 Skills 与可组合的脚本结合使用。当你的脚手架有无法被纯代码覆盖的自然语言需求时特别有用。

示例：

• new-workflow — 使用你的注解脚手架新的服务/工作流/处理器
• new-migration — 你的迁移文件模板加常见陷阱
• create-app — 预配置认证、日志和部署配置的新内部应用

6. 代码质量与审查 (Code Quality & Review)

在组织内执行代码质量标准并帮助审查代码的 Skills。可以包含确定性脚本或工具以实现最大鲁棒性。

示例：

• adversarial-review — 生成新鲜视角的子代理进行批评，实现修复，迭代直到发现降级为小问题
• code-style — 强制执行代码风格，尤其是 Claude 默认做得不好的风格
• testing-practices — 如何编写测试和测试什么的指令

7. CI/CD 与部署

帮助你在代码库中获取、推送和部署代码的 Skills。

示例：

• babysit-pr — 监控 PR → 重试不稳定 CI → 解决合并冲突 → 启用自动合并
• deploy-service — 构建→冒烟测试→渐进流量发布加错误率对比→回归时自动回滚
• cherry-pick-prod — 隔离工作树 → cherry-pick → 冲突解决 → 带模板的 PR

8. 运维手册 (Runbooks)

接受症状（如 Slack 线程、警报或错误签名），通过多工具调查并产生结构化报告的 Skills。

示例：

• service-debugging — 将你的高流量服务的症状映射到工具和查询模式
• oncall-runner — 获取警报→检查常见嫌疑→格式化发现
• log-correlator — 给定请求 ID，从每个可能接触过的系统拉取匹配日志

9. 基础设施运维 (Infrastructure Operations)

执行例行维护和操作程序的 Skills — 其中一些涉及从护栏中受益的破坏性操作。

示例：

• resource-orphans — 查找孤立的 pod/卷 → 发布到 Slack → 浸泡期 → 用户确认 → 级联清理
• dependency-management — 你组织的依赖审批工作流
• cost-investigation — "为什么我们的存储/出口费用激增" 加上特定存储桶和查询模式

编写 Skills 的技巧

不要陈述显而易见的内容

Claude Code 对你的代码库已经了解很多，而且 Claude 对编码也了解很多，包括许多默认观点。如果你发布的 Skill 主要是关于知识的，尽量关注能让 Claude 跳出常规思维的信息。

frontend-design Skill 就是一个很好的例子——它由 Anthropic 的一位工程师通过迭代与客户合作改善 Claude 的设计品味而构建，避免了 Inter 字体和紫色渐变等经典模式。

构建 Gotchas 部分

任何 Skill 中信号量最高的内容就是 Gotchas 部分。这些部分应该从 Claude 使用你的 Skill 时遇到的常见失败点中积累。理想情况下，你会随着时间更新你的 Skill 以捕获这些 gotchas。

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

如前所述，Skill 是一个文件夹，而不仅仅是一个 markdown 文件。你应该将整个文件系统视为上下文工程和渐进式披露的一种形式。告诉 Claude 你的 Skill 中有哪些文件，它会在适当的时候读取它们。

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

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

不要过度限制 Claude

Claude 通常会尽量遵循你的指令，而由于 Skills 是如此可重用，你需要小心不要在指令中过于具体。给 Claude 所需的信息，但给它灵活性来适应情况。

考虑设置流程

某些 Skill 可能需要从用户那里获取上下文。一个好的做法是将设置信息存储在 Skill 目录中的 config.json 文件中。如果配置没有设置，agent 可以向用户询问信息。

Description 字段是给模型看的

当 Claude Code 启动会话时，它会构建每个可用 Skill 及其描述的列表。Claude 扫描此列表来决定"是否有适合此请求的 Skill？"因此描述字段不是摘要——它是关于何时触发此 Skill 的描述。

存储脚本与生成代码

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

按需 Hooks

Skills 可以包含仅在调用 Skill 时激活的 hooks，并在会话期间持续有效。

例如：

• /careful — 通过 Bash 上的 PreToolUse 匹配器阻止 rm -rf、DROP TABLE、force-push、kubectl delete。你只在你知道要接触生产环境时才需要这个——一直开着会让你发疯
• /freeze — 阻止不在特定目录中的任何 Edit/Write。在调试时很有用："我想添加日志，但总是不小心'修复'不相关的东西"

分发 Skills

Skills 的最大好处之一是你可以与团队的其他人分享。

两种分享方式：

1. 将 Skills 检入代码仓库（在 ./.claude/skills 下）
2. 制作插件并通过 Claude Code Plugin Marketplace 分发

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

管理市场

如何决定哪些 Skills 进入市场？我们不有一个集中式的团队来决定；相反，我们尝试有机地找到最有用的 Skills。

如果你想让人们试用某个 Skill，可以将其上传到 GitHub 的沙盒文件夹，然后在 Slack 或其他论坛中指向它。

一旦某个 Skill 获得了吸引力，负责人就可以提交 PR 将其移入市场。

⚠️ 创建不好或冗余的 Skills 可能很容易，因此确保在发布前有某种筛选机制很重要。

组合 Skills

你可能希望 Skills 之间有依赖关系。例如，你可能有一个上传文件的 Skill 和一个生成 CSV 并上传的 Skill。这种依赖管理目前还没有原生构建到市场或 Skills 中，但你可以通过名称引用其他 Skills，模型会在已安装的情况下调用它们。

衡量 Skills

为了了解 Skill 的表现，我们使用一个 PreToolUse hook 来记录公司内的 Skill 使用情况。这意味着我们可以找到受欢迎的或相对于预期触发不足的 Skills。

结语

Skills 是极其强大和灵活的 agent 工具，但仍然处于早期阶段，我们都在摸索最佳使用方式。

这更像是一袋有用的小技巧，而不是一份权威指南。理解 Skills 最好的方式就是开始、实验，看看什么对你有效。我们的大多数 Skills 最初只有几行代码和一个 gotcha，因为人们随着 Claude 遇到新的边界情况而不断添加内容才变得更好。

---

原文来源：X (Twitter) @trq212，发布于 2026 年 3 月 18 日