Claude Code Skills 实战指南：来自 Anthropic 工程团队的经验总结

引言

如果你正在使用 Claude Code 进行开发工作，可能已经听说过 Skills 这个功能。作为 Claude Code 中最常用的扩展点之一，Skills 以其灵活性和易用性赢得了众多开发者的青睐。

Anthropic 内部工程团队在日常开发中使用了数百个 Skills，这些工具显著提升了他们的开发效率。本文将分享他们从实际使用中总结出的经验，帮助你更好地理解和运用这一功能。

Skills 到底是什么？

很多人初次接触 Skills 时，会误以为它只是简单的 Markdown 文件。实际上，Skills 是一个完整的文件夹结构，可以包含脚本、资源文件、数据等多种内容。Claude 能够主动发现、探索并操作这些内容。

在 Claude Code 中，Skills 还配备了一套配置系统，支持注册动态钩子（hooks），这让 Skills 的功能远超静态文档的范畴。

九类实用 Skills 详解

根据 Anthropic 团队的分类，Skills 主要可以归纳为以下九种类型。理解这些分类有助于你判断团队是否遗漏了某些关键场景。

1. 库与 API 参考文档型

这类 Skills 专门解释如何正确使用特定的库、命令行工具或 SDK。它们既适用于内部开发的库，也适用于 Claude 在常规使用中可能遇到困难的常见第三方库。

这类 Skills 通常会包含一个参考代码片段文件夹，以及 Claude 在编写脚本时应避免的常见陷阱列表。

典型应用场景：

场景 说明
内部计费库 记录边界情况、常见错误用法等
内部平台 CLI 详细说明每个子命令及使用时机
前端设计系统 让 Claude 更好地遵循团队的设计规范

2. 产品验证型

这类 Skills 描述如何测试或验证代码是否正常工作。它们通常与 Playwright、Tmux 等外部工具配合使用，执行实际的验证操作。

验证型 Skills 对于确保 Claude 的输出质量至关重要。Anthropic 团队甚至建议，值得投入一周时间专门完善这类 Skills。

实用技巧：

  • 让 Claude 录制测试过程的视频，便于后续查看
  • 在每个步骤中强制执行程序化的状态断言
  • 在 Skill 中包含多种脚本以支持不同验证场景

示例场景：

  • 注册流程驱动器：在 headless 浏览器中完成注册 → 邮件验证 → 引导流程，并在每个步骤设置状态断言钩子
  • 结账验证器：使用 Stripe 测试卡驱动结账界面，验证发票最终状态
  • Tmux CLI 驱动器：针对需要 TTY 的交互式 CLI 测试

3. 数据获取与分析型

这类 Skills 连接团队的数据和监控体系。它们可能包含用于获取数据的库（含凭证）、特定的仪表板 ID，以及常见工作流的操作说明。

典型应用：

  • 漏斗查询：说明需要关联哪些事件才能查看”注册 → 激活 → 付费”转化路径，以及包含标准 user_id 的表
  • 群组对比：比较两个群组的留存率或转化率，标记统计显著性差异，并链接到群组定义
  • Grafana 集成：数据源 UID、集群名称、问题到仪表板的查询映射表

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

这类 Skills 将重复性工作流简化为单一命令。虽然指令本身通常较为简单，但可能依赖其他 Skills 或 MCP 实现复杂功能。

对于这类 Skills，将历史执行结果保存在日志文件中可以帮助模型保持一致性，并回顾之前的工作流执行情况。

常见用例：

  • 站会报告生成：聚合工单系统、GitHub 活动和 Slack 历史消息，生成格式化的站会报告，仅显示变化内容
  • 工单创建：强制执行字段规范（有效枚举值、必填字段）以及创建后的工作流（通知审核人、在 Slack 中链接）
  • 周报生成：合并已合并的 PR、关闭的工单和部署记录，生成格式化的总结报告

5. 代码脚手架与模板型

这类 Skills 为代码库中的特定功能生成框架样板代码。你可以将它们与可组合的脚本结合使用。当脚手架包含无法完全通过代码表达的自然语言需求时，这类 Skills 特别有用。

应用场景：

  • 新工作流脚手架：使用团队注解创建新服务、工作流或处理器
  • 迁移文件模板：包含团队迁移文件模板及常见注意事项
  • 应用创建：预配置认证、日志记录和部署配置的新内部应用

6. 代码质量与审查型

这类 Skills 在组织内部强制执行代码质量标准并协助代码审查。它们可以包含确定性脚本或工具以实现最大健壮性。你可能希望将这些 Skills 作为钩子自动运行，或在 GitHub Action 中使用。

功能示例：

  • 对抗性审查：生成一个”全新视角”的子代理进行批判性审查，实施修复，迭代直到问题降级为细节问题
  • 代码风格：强制执行代码风格，特别是 Claude 默认表现不佳的风格
  • 测试实践：编写测试的指导和测试内容建议

7. CI/CD 与部署型

这类 Skills 协助在代码库中获取、推送和部署代码。这些 Skills 可能会引用其他 Skills 来收集数据。

实际案例：

  • PR 监控：监控 PR → 重试 flaky CI → 解决合并冲突 → 启用自动合并
  • 服务部署：构建 → 冒烟测试 → 渐进式流量推出并对比错误率 → 检测到退化时自动回滚
  • 生产环境 cherry-pick：隔离工作树 → cherry-pick → 冲突解决 → 使用模板创建 PR

8. 运维手册型（Runbooks）

这类 Skills 接收一个症状（如 Slack 线程、告警或错误特征），执行多工具调查，并生成结构化报告。

典型场景：

  • 服务调试：将症状映射到工具和高流量服务的查询模式
  • 值班运行：获取告警 → 检查常见原因 → 格式化发现结果
  • 日志关联：给定请求 ID，从可能处理过该请求的每个系统中提取匹配日志

9. 基础设施操作型

这类 Skills 执行日常维护和操作程序，其中一些涉及破坏性操作，需要设置防护栏。它们让工程师在关键操作中更容易遵循最佳实践。

应用示例：

  • 资源孤儿清理：查找孤立的 pod/卷 → 发布到 Slack → 浸泡期 → 用户确认 → 级联清理
  • 依赖管理：组织的依赖审批工作流
  • 成本调查：”为什么存储/出口费用激增”，包含特定存储桶和查询模式

创建高质量 Skills 的实战技巧

确定了 Skill 的类型后，如何编写才能让它真正好用？以下是 Anthropic 团队总结的最佳实践。

避免陈述显而易见的内容

Claude Code 对你的代码库已有相当了解，Claude 本身也掌握大量编程知识，包括许多默认观点。如果你正在编写以知识为主的 Skill，应专注于那些能推动 Claude 跳出常规思维模式的信息。

Anthropic 的设计系统 Skill 就是一个很好的例子。它由一位工程师通过与客户迭代改进 Claude 的设计品味而创建，成功避免了 Inter 字体和紫色渐变等常见模式。

建立”陷阱”（Gotchas）章节

任何 Skill 中价值最高的内容就是”陷阱”章节。这些章节应从 Claude 使用该 Skill 时遇到的常见失败点中积累。理想情况下，你会随着时间推移不断更新 Skill 以捕获这些陷阱。

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

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

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

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

你可以拥有参考文件、脚本、示例等文件夹，帮助 Claude 更有效地工作。

避免过度限制 Claude

Claude 通常会尝试遵循你的指令，由于 Skills 的可重用性很高，你需要注意不要在指令中过于具体。给 Claude 所需的信息，但给它适应情况的灵活性。

考虑初始化配置

某些 Skill 可能需要用户提供上下文才能使用。例如，如果你正在制作一个将站会报告发布到 Slack 的 Skill，你可能希望 Claude 询问要发布到哪个 Slack 频道。

实现这一点的一个好模式是将这些设置信息存储在 Skill 目录的 config.json 文件中。如果配置未设置，代理可以询问用户信息。

如果你想让代理呈现结构化的多选题，可以指示 Claude 使用 AskUserQuestion 工具。

描述字段是给模型看的

当 Claude Code 启动会话时，它会构建一个包含每个可用 Skill 及其描述的列表。这个列表是 Claude 用来判断”是否有适合这个请求的 Skill”的依据。这意味着描述字段不是摘要，而是说明何时触发该 Skill 的描述。

内存与数据存储

某些 Skills 可以通过在其内部存储数据来实现某种形式的”记忆”。你可以将数据存储在简单的追加式文本日志文件或 JSON 文件中，也可以存储在复杂的 SQLite 数据库中。

例如，一个站会报告 Skill 可能会保留一个 standups.log 文件，记录它编写的每篇报告。这样下次运行时，Claude 可以读取自己的历史记录，并告诉用户自昨天以来发生了什么变化。

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

存储脚本与生成代码

你能给 Claude 最强大的工具之一就是代码。给 Claude 脚本和库让它把回合花在组合上——决定下一步做什么，而不是重构样板代码。

例如，在你的数据科学 Skill 中，你可能有一个从事件源获取数据的函数库。为了让 Claude 进行复杂分析，你可以给它一组辅助函数。然后 Claude 可以即时生成脚本来组合这些功能，以响应”周二发生了什么？”这类提示。

按需钩子

Skills 可以包含仅在 Skill 被调用时激活、并在会话持续期间保持激活的钩子。这适用于你不想一直运行但在某些时候非常有用的更具观点性的钩子。

示例：

  • /careful：通过 Bash 上的 PreToolUse 匹配器阻止 rm -rf、DROP TABLE、强制推送、kubectl delete。你只在接触生产环境时才需要这个，一直开启会让人发疯
  • /freeze：阻止不在特定目录中的任何编辑/写入。在调试时很有用：”我想添加日志，但一直不小心’修复’无关内容”

分发与共享 Skills

Skills 的最大优势之一是你可以与团队其他成员共享。

两种分发方式

方式一：存入代码库

将 Skills 存入仓库（在 ./.claude/skills 下）。对于在相对较少仓库中工作的小团队，这种方式效果很好。但每个存入的 Skill 都会为模型增加一点上下文负担。

方式二：插件市场

创建一个插件，并建立 Claude Code 插件市场，用户可以在其中上传和安装插件。随着规模扩大，内部插件市场允许你分发 Skills，并让团队成员决定安装哪些。

管理市场

如何决定哪些 Skills 进入市场？人们如何提交？

Anthropic 没有专门的 centralized 团队来决定，而是尝试有机地发现最有用的 Skills。如果你有一个想让人们试用的 Skill，可以将其上传到 GitHub 的沙盒文件夹，然后在 Slack 或其他论坛中指向它。

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

需要注意的是，创建糟糕或冗余的 Skills 相当容易，因此在发布前确保有某种审核机制非常重要。

组合 Skills

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

衡量 Skills 效果

为了了解 Skill 的表现，可以使用 PreToolUse 钩子在公司内部记录 Skill 使用情况。这意味着你可以找到受欢迎的 Skills，或与预期相比触发不足的 Skills。

常见问题解答

Q: Skills 和普通的 Claude 提示有什么区别？

Skills 是结构化的、可复用的知识包。与一次性提示不同，Skills 可以包含脚本、配置文件、模板和渐进式加载的参考文档。它们还能通过钩子与 Claude Code 的运行时行为深度集成。

Q: 我的团队应该从哪里开始创建 Skills？

建议从你最痛苦的重复性任务开始。查看上面列出的九种类型，找出团队在日常工作中频繁遇到 friction 的场景。通常，内部 API 文档、代码审查标准或部署流程是很好的起点。

Q: 一个 Skill 可以包含多个类型吗？

虽然某些 Skills 可能跨越多个类别，但 Anthropic 团队发现，最好的 Skills 通常 cleanly 地落入单一类别。跨越多个类型的 Skills 往往会让使用者感到困惑。

Q: 如何确保 Skill 不会被误触发？

仔细编写描述字段。这个字段不是给人类看的摘要，而是告诉 Claude 在什么情况下应该激活这个 Skill。使用具体的触发条件描述，包含文件类型、操作和工具等关键词。

Q: Skills 和 MCP Servers 有什么关系？

Skills 和 MCP（Model Context Protocol）Servers 都是扩展 Claude 能力的方式，但它们服务于不同层次。Skills 通常是 Claude Code 内部的轻量级知识包，而 MCP Servers 是独立运行的外部服务。某些 Skills 可能会调用 MCP Servers 来完成任务。

Q: 如何更新和维护 Skills？

Skills 应该是活文档。当 Claude 在使用某个 Skill 时遇到新的边界情况或错误模式时，及时更新 Gotchas 章节。对于存入代码库的 Skills，使用正常的代码审查流程；对于插件市场的 Skills，遵循团队的发布流程。

Q: 私有仓库的 Skills 如何分发？

Claude Code 支持从私有仓库安装插件。对于手动安装和更新，Claude Code 使用你现有的 git 凭证助手。如果 git clone 在你的终端中对私有仓库有效，它在 Claude Code 中也会有效。对于自动更新，需要在环境中设置适当的认证令牌，如 GITHUB_TOKEN 或 GH_TOKEN。

结语

Skills 是强大而灵活的代理工具，但这仍然是一个新兴领域，我们都在探索最佳使用方法。

本文提供的更像是 Anthropic 团队验证过的实用技巧集合，而非权威指南。理解 Skills 的最佳方式是开始实践、实验，看看什么适合你。Anthropic 的大多数 Skills 最初都只有几行代码和一个陷阱提示，之所以变得更好，是因为人们在 Claude 遇到新的边界情况时不断添加内容。

希望这些来自一线开发团队的经验能帮助你更高效地使用 Claude Code Skills，构建适合自己团队的工作流。

本文内容基于 Anthropic 工程团队在 Claude Code 中使用 Skills 的实战经验整理，涵盖从 Skill 分类、创建技巧到分发管理的完整知识体系。