构建 Claude Code 的经验：我们如何使用 Skills

Skills 已成为 Claude Code 最常用的扩展点之一。它们灵活、易于创建，也便于分发。

但这种灵活性也让人难以判断什么做法最有效：哪些 skills 值得做？写出一个好 skill 的秘诀是什么？又该在什么时候与他人分享？

在 Anthropic，我们一直广泛地在 Claude Code 中使用 skills，目前已有数百个处于活跃使用状态。以下是我们用 skills 加速开发时总结出的经验。

什么是 Skills？

如果你刚接触 skills，建议先阅读我们的文档，或观看我们最新的 Agent Skills Skilljar 课程。本文假定你已经对它们有一些基本了解。

我们经常听到一个误解：skills “不过就是 Markdown 文件”。但 skills 最有意思的地方恰恰在于，它们不只是文本文件；它们是目录，里面可以包含脚本、资源、数据等，agent 能够发现、浏览并操作这些内容。

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

我们发现，Claude Code 中一些最有意思的 skills，正是创造性地运用了这些配置选项和目录结构。

Skills 的类型

梳理完所有 skills 后，我们发现它们会聚成几类反复出现的模式。最好的 skills 往往能清楚地归入其中一类；令人困惑的那些通常横跨了好几类。这并非一份权威清单，但它很适合用来思考：你的组织内部是否还缺少某类 skill。

1. 库与 API 参考

这类 skills 说明如何正确使用某个库、CLI 或 SDK。它们既可以服务于内部库，也可以覆盖 Claude Code 有时难以掌握的常见库。这类 skill 通常会附带参考代码片段目录，以及一份提醒 Claude 在编写脚本时应避开的常见坑的清单。

示例：

• billing-lib — 你的内部计费库：边界情况、易踩坑点等
• internal-platform-cli — 内部 CLI 封装的每个子命令，以及各自的使用时机示例
• frontend-design — 让 Claude 更好地遵循你的设计系统

2. 产品验证

这类 skills 说明如何测试或验证代码是否正常工作。它们通常会搭配 Playwright、tmux 等外部工具来完成验证。

验证类 skills 对确保 Claude 的产出正确极其有用。让一名工程师专门花一周时间把验证 skills 打磨到位，往往非常值得。

可以考虑让 Claude 录制其输出的视频，以便你准确看到它测试了什么；也可以在每一步强制进行可编程的状态断言。这些做法通常通过在 skill 中包含各种脚本来实现。

示例：

• signup-flow-driver — 在无头浏览器中跑通注册 → 邮箱验证 → 引导流程，并提供 hooks 在每一步断言状态
• checkout-verifier — 使用 Stripe 测试卡驱动结账 UI，并验证发票确实进入了正确状态
• tmux-cli-driver — 用于交互式 CLI 测试，适合需要 TTY 的被验证对象

3. 数据获取与分析

这类 skills 连接你的数据与监控栈。它们可以包含用于带凭据获取数据的库、特定 dashboard ID，以及常用工作流或数据获取方法的说明。

示例：

• funnel-query — “查看注册 → 激活 → 付费时，该关联哪些事件？”以及实际存放规范 user_id 的表
• cohort-compare — 比较两个 cohort 的留存或转化，标记具有统计显著性的差异，并链接到分群定义
• grafana — datasource UID、集群名称，以及“问题 → dashboard”的查询映射表

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

这类 skills 将重复性工作流自动化为一条命令。它们的说明通常比较简单，但也可能对其他 skills 或 MCP 有更复杂的依赖。对于这类 skill，把先前结果存入日志文件能帮助模型保持一致性，并反思此前的工作流执行结果。

示例：

• standup-post — 汇总任务追踪器、GitHub 活动和先前的 Slack 内容，生成格式化的 standup；只输出增量
• create--ticket — 强制执行 schema（合法枚举值、必填字段），并完成创建后的工作流（提醒 reviewer、在 Slack 中附上链接）
• weekly-recap — 已合并 PR + 已关闭任务 + 部署记录 → 格式化的回顾帖

5. 代码脚手架与模板

这类 skills 为代码库中特定职能生成框架样板。你可以将它们与可组合的脚本结合使用。当脚手架带有无法完全用代码覆盖的自然语言要求时，它们尤其有用。

示例：

• new--workflow — 为新的 service、workflow 或 handler 生成带有你所需注解的脚手架
• new-migration — 你的 migration 文件模板及常见注意事项
• create-app — 创建新的内部应用，并预先接好认证、日志与部署配置

6. 代码质量与审查

这类 skills 在组织内部落实代码质量要求，并辅助代码审查。为了获得最大的可靠性，它们可以包含确定性的脚本或工具。你可能还会希望通过 hooks 或 GitHub Action 自动运行它们。

• adversarial-review — 派一个拥有全新视角的子 agent 来挑刺、实施修复并持续迭代，直到发现的问题只剩吹毛求疵的细节
• code-style — 强制执行代码风格，尤其是 Claude 默认做得不够好的那些风格要求
• testing-practices — 说明该如何写测试，以及应该测试什么

7. CI/CD 与部署

这类 skills 帮助你在代码库中拉取、推送和部署代码。它们可能会引用其他 skills 来收集所需数据。

示例：

• babysit-pr — 监控 PR → 重试偶发失败的 CI → 解决合并冲突 → 启用自动合并
• deploy- — 构建 → smoke test → 逐步放量并比较错误率 → 发生回归时自动回滚
• cherry-pick-prod — 隔离 worktree → cherry-pick → 解决冲突 → 创建带模板的 PR

8. Runbook

这类 skills 接收一个症状（例如 Slack 讨论串、告警或错误特征），引导完成多工具调查，并产出结构化报告。

示例：

• -debugging — 将症状映射到工具和查询模式，覆盖流量最高的服务
• oncall-runner — 获取告警 → 检查常见问题点 → 整理发现
• log-correlator — 根据 request ID，从每个可能触及该请求的系统中提取匹配日志

9. 基础设施运维

这类 skills 执行日常维护和运维操作，其中有些涉及破坏性动作，因此需要护栏。它们让工程师更容易在关键操作中遵循最佳实践。

示例：

• -orphans — 查找孤立的 pod/volume → 发到 Slack → 静置观察期 → 用户确认 → 级联清理
• dependency-management — 组织内的依赖审批工作流
• cost-investigation — “为什么我们的存储/出网账单突然上涨？”并附上对应 bucket 和查询模式

编写 Skills 的建议

确定要做什么 skill 后，该如何把它写好？以下是我们发现的一些最佳实践、技巧和窍门。

我们最近还发布了 Skill Creator，让创建 skills 变得更容易。

不要陈述显而易见的事

Claude Code 对你的代码库了解很多，Claude 也很懂编程，并且带着不少默认倾向。如果你发布的 skill 主要承载知识，尽量聚焦于那些能让 Claude 跳出惯常思路的信息。

frontend design skill 是个很好的例子——Anthropic 的一位工程师通过与客户反复迭代来改善 Claude 的设计品味，帮助它避免使用 Inter 字体、紫色渐变等经典套路。

建立一个 Gotchas 区段

任何 skill 中信号密度最高的内容，都是 Gotchas 区段。它应当从 Claude 在使用该 skill 时反复遇到的失败点中逐步积累。理想情况下，你会随着时间推移更新 skill，把这些坑持续沉淀进去。

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

如前所述，skill 是一个目录，而不只是一份 Markdown 文件。你应当把整个文件系统视为上下文工程和渐进式披露的一种形式：告诉 Claude skill 中有哪些文件，它就会在合适的时候读取它们。

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

另一个例子是：如果最终产物是 Markdown 文件，可以在 assets/ 中放入一个供复制和使用的模板文件。

你还可以准备 references、scripts、examples 等目录，帮助 Claude 更高效地完成工作。

不要把 Claude 绑死在轨道上

Claude 通常会努力遵循你的指令；而 skills 又具有高度复用性，因此要小心别把指令写得过于具体。给 Claude 它所需的信息，同时保留根据具体情境调整的空间。例如：

认真想清楚初始化配置

有些 skills 需要由用户提供上下文来完成设置。例如，如果你要制作一个把 standup 发到 Slack 的 skill，可能需要让 Claude 询问应发送到哪个 Slack 频道。

一个不错的模式是：把这些设置资料存入 skill 目录中的 config.json。如果配置尚未完成，agent 就可以向用户提问。

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

Description 字段是写给模型看的

Claude Code 启动一个 session 时，会构建所有可用 skill 及其 description 的列表。模型会扫描这个列表，判断“这个请求是否有对应的 skill？”所以 description 不是摘要，而是对该 skill 应在何时触发的说明。

记忆与数据存储

有些 skills 可以通过在内部存储数据而具备某种记忆能力。你可以使用从仅追加的文本日志或 JSON 文件，到 SQLite 数据库这样复杂的任意载体。

例如，一个 standup-post skill 可以保存它写过的每一篇 standup 到 standups.log。下一次运行时，模型就能读取自己的历史，告诉你相比昨天发生了什么变化。

存放在 skill 目录中的数据可能会在升级 skill 时被删除，因此应把这些数据放在稳定目录中。截至目前，我们提供 ${CLAUDE_PLUGIN_DATA} 作为每个 plugin 的稳定数据目录。

保存脚本并生成代码

你能交给 Claude 的最强大工具之一就是代码。提供脚本和库，能让 Claude 把更多回合花在组合与判断下一步，而不是重新搭建样板代码上。

例如，在数据科学 skill 中，你可以提供一套从事件源获取数据的函数库：

Claude 随后便能即时生成脚本来组合这些能力，从而回答诸如“星期二发生了什么？”这样的提示，并完成更复杂的分析。

按需 Hooks

skills 可以包含只在调用时激活、并持续整个 session 的 hooks。对于那些不想一直运行、但在特定场景下极其有用的强约束 hooks，这种方式很合适。

例如：

• /careful — 通过 Bash 上的 PreToolUse matcher 阻止 rm -rf、DROP TABLE、force-push、kubectl delete 等操作。只有明确知道自己在碰生产环境时才需要它；让它一直开着会把人逼疯
• /freeze — 阻止所有不位于特定目录内的 Edit/Write 操作，很有用
• 调试时：“我想加日志，但总会不小心‘修复’无关的内容。”

分发 Skills

Skills 的最大好处之一，是可以将它们分享给团队中的其他人。

分享 skills 有两种方式：

• 将 skills 签入你的仓库（放在 ./.claude/skills 下）
• 制作一个 plugin，并建立 Claude Code Plugin marketplace，让用户可以上传和安装 plugins（详见文档）

对于跨越仓库不多的小团队，把 skills 签入仓库就很合适。但每个签入的 skill 都会给模型上下文增加一点负担。随着规模扩大，内部 plugin marketplace 能让你分发 skills，并由团队成员自行决定安装哪些。

管理一个 Marketplace

如何决定哪些 skills 应进入 marketplace？人们又该如何提交它们？

我们没有一个集中式团队来做这个决定；相反，我们会让真正有用的 skills 自然涌现。如果你有一个希望大家尝试的 skill，可以把它上传到 GitHub 中的 sandbox 目录，再在 Slack 或其他论坛中分享链接。

当某个 skill 获得足够关注后（由 skill 的所有者决定），就可以提交一个 PR，把它移入 marketplace。

需要提醒的是，创建糟糕或重复的 skills 非常容易，因此在发布前建立某种审核机制很重要。

组合 Skills

你可能会需要彼此依赖的 skills。例如，一个文件上传 skill 负责上传文件，另一个 CSV 生成 skill 负责生成 CSV 并上传。marketplace 目前尚未原生提供这类依赖管理，但你可以直接按名称引用其他 skills；如果它们已安装，模型就会调用它们。

衡量 Skills

为了了解一个 skill 的表现，我们使用 PreToolUse hook 记录公司内部的 skill 使用情况（示例代码在这里）。这样我们就能找出哪些 skills 受欢迎，或相对于预期触发得太少。

结语

Skills 是赋予 agents 强大且灵活能力的工具，但这仍是一个很早期的领域，我们都还在摸索。

与其把这篇文章视为一份定论，不如把它看作一袋我们见过确实有效的实用建议。理解 skills 的最好方式，是开始使用、不断实验，再看看结果。我们的大多数 skills 最初只有几行内容和一个 gotcha；随着 Claude 遇到更多边界情况，人们不断补充，它们才逐渐变好。

希望这些内容对你有帮助；如有问题，欢迎告诉我。