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

中文精读

原文约 2,967 词 · 24 节

1. 引言：Claude Code 团队使用 Skills 的经验

   • Skills 已成为 Claude Code 中使用最广泛的扩展点之一，灵活、易创建、易分发，但灵活性也让人难以判断什么做法最好。
   • 文中要回答的问题包括：值得做哪类 skill、如何组织结构、何时分享给他人。
   • Anthropic 内部有数百个 skill 在活跃使用，文章总结的是他们借此加速开发的实践教训。

2. 什么是 Skills

   • Skill 是包含指令、脚本和资源的文件夹，agent 可以发现并使用它们来更准确高效地完成任务。
   • 常见误解是 skill 只是 markdown 文件，实际上它可以包含脚本、资产、数据等，agent 能发现、浏览和操作这些内容。
   • 在 Claude Code 中 skill 还有多种配置项，包括注册动态 hooks（钩子）；一些最有效的 skill 正是充分利用了这些配置和文件夹结构。

3. Skills 的类型划分

   • 梳理 Anthropic 内部全部 skill 后，发现它们可归为九大类。
   • 最好的 skill 能清晰地落在某一类里；试图做太多事情的 skill 会横跨多类，让模型困惑。
   • 这份分类并非定论，但可作为查找自身 skill 库空白的框架。

4. 1. 库与 API 参考

   • 这类 skill 说明如何正确使用某个库、CLI 或 SDK，既可能是内部库，也可能是 Claude Code 常处理不好的公共库。
   • 通常包含一个参考代码片段文件夹，以及一份让 Claude 写脚本时避坑的清单。
   • 示例：内部计费库的边界情况与陷阱、内部 CLI 包装器的所有子命令及使用场景、组织出口网关的配置与“连接被拒”排查。

5. 2. 产品验证

   • 这类 skill 描述如何测试或验证代码可用，常与 playwright、tmux 等外部工具配合。
   • 验证类 skill 对 Claude 输出质量的可测量影响在内部最大，值得让一名工程师花一周把验证 skill 打磨到优秀。
   • 可采用让 Claude 录制输出视频、在各步骤对状态做程序化断言等技术，往往通过在 skill 中放入多种脚本实现。
   • 示例：无头浏览器跑注册→邮箱验证→引导流程并在每步断言状态、用 Stripe 测试卡驱动结账界面并核对发票状态、用于需要 TTY 的交互式 CLI 测试。

6. 3. 数据获取与分析

   • 这类 skill 连接数据与监控栈，可能包含带凭据取数的库、具体 dashboard id，以及常见工作流的说明。
   • 示例：注册→激活→付费的漏斗查询及规范 user_id 所在表、队列群组留存/转化对比并标记统计显著差异、Grafana 的数据源 UID 与问题到看板的映射、Datadog 的字段引用与服务清单。

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

   • 这类 skill 把重复工作流自动化成一条命令，指令通常较简单，但可能较复杂地依赖其他 skill 或 MCP。
   • 对这类 skill，把以往结果存进日志文件有助于模型保持一致并能回顾此前执行情况。
   • 示例：聚合工单系统、GitHub 活动和先前 Slack 内容生成只含增量的站会汇报、强制字段与创建后流程的建单 skill、合并 PR 与关闭工单及部署的周报。

8. 5. 代码脚手架与模板

   • 这类 skill 为代码库中某类功能生成框架样板，可以与可组合的脚本搭配使用。
   • 当脚手架含有无法完全用代码表达的自然语言要求时，这类 skill 尤其有用。
   • 示例：带注解的新服务/工作流/handler 脚手架、迁移文件模板加常见陷阱、预置好鉴权与日志和部署配置的新内部应用。

9. 6. 代码质量与评审

   • 这类 skill 在组织内强制执行代码质量并协助评审，可包含确定性脚本或工具以获得最大稳健性。
   • 可以在 hooks 中或 GitHub Action 里自动运行这些 skill。
   • 示例：启动全新视角的子 agent 做对抗式评审并反复修复直到只剩琐碎意见、强制 Claude 默认不擅长的代码风格、说明如何写测试和测试什么。

10. 7. CI/CD 与部署

    • 这类 skill 帮助在代码库内拉取、推送和部署代码，可能会引用其他 skill 来收集数据。
    • 示例：监控 PR 并重试不稳定 CI、解决合并冲突并开启自动合并；构建→冒烟测试→按错误率对比逐步放量→回归时自动回滚；在隔离 worktree 中 cherry-pick 并带模板提 PR。

11. 8. 运行手册（Runbooks）

    • 这类 skill 接收一个症状（如 Slack 讨论串、告警或错误签名），走完多工具排查流程并产出结构化报告。
    • 示例：把症状映射到工具和查询模式的调试 skill、拉取告警并检查常见嫌疑项后格式化结论的值班 skill、按 request ID 汇总各系统相关日志。

12. 9. 基础设施运维

    • 这类 skill 执行例行维护与操作流程，其中一些涉及破坏性操作，需要护栏。
    • 目的是让工程师在关键操作中更容易遵循最佳实践。
    • 示例：查找孤立 pod/卷→发到 Slack→静置期→用户确认→级联清理；组织的依赖审批流程；带具体存储桶和查询模式的成本异常调查。

13. 制作 Skills 的建议（开篇）

    • 确定要做什么 skill 之后，如何写？这一部分给出 Claude Code 团队的最佳实践、技巧和诀窍。

14. 不要陈述显而易见的内容

    • Claude 已会写代码并能读代码库；重述它默认会做的事只会增加上下文、不增加价值。
    • 如果发布的是以知识为主的 skill，应聚焦于能把 Claude 推出惯常思维的信息。
    • 前端设计 skill 是范例：Anthropic 一名工程师与客户反复迭代打磨 Claude 的设计品味，避开 Inter 字体、紫色渐变等套路。

15. 建立“陷阱”小节

    • 任何 skill 中信噪比最高的内容就是 Gotchas 小节，应基于 Claude 使用该 skill 时遇到的常见失败点逐步累积。
    • 理想做法是随时间不断更新 skill 来记录这些坑。
    • 示例：subscriptions 表只追加、要取最高版本行而非最新 created_at；同一值在网关叫 @request_id、在计费服务叫 trace_id；Staging 即使 webhook 未处理也返回 200，需查 payment_events 看真实状态。

16. 利用文件系统与渐进披露

    • skill 是整个文件夹而非单个 markdown 文件，应把整个文件系统视为上下文工程和渐进披露（progressive disclosure）的手段。
    • 最简单的渐进披露是让 SKILL.md 指向其他 markdown 文件，例如把函数签名与用法示例拆到 references/api.md。
    • 若最终输出是 markdown 文件，可在 assets/ 放模板供复制使用；还可放参考、脚本、示例等文件夹。
    • 图 B 示例中 SKILL.md 是一张“症状→文件”对照表，job pending 时指向 stuck-jobs.md。

17. 不要过度框死 Claude

    • Claude 通常会严格遵循指令，而 skill 复用率高，所以指令过于具体要格外小心。
    • 应给出必要信息，同时留出适应具体情况的灵活性。
    • 图 C 示例：过于规定性的做法是六步逐一写死 git 命令；更好的写法是“把提交 cherry-pick 到干净分支，解决冲突时保留原意，若无法干净落地就说明原因”——讲清目标与约束，而非每一步。

18. 想清楚初始化设置

    • 有些 skill 需要用户提供上下文，例如发站会汇报的 skill 需要知道发到哪个 Slack 频道。
    • 推荐模式是把设置信息存在 skill 目录下的 config.json 中；若尚未配置，agent 就向用户索取。
    • 若希望以结构化选择题方式询问，可指示 Claude 使用 AskUserQuestion 工具。
    • 图 D 中的 standup-post 在“Your config”里运行 shell 命令读取 config.json，缺失时输出 NOT_CONFIGURED，并指示 Claude 询问频道和示例站会内容后保存。

19. 描述写给模型看，不是写给人看

    • Claude Code 启动会话时会为所有可用 skill 建立带描述（description）的清单，Claude 扫这份清单来判断“有没有处理这个请求的 skill”。
    • 因此 description 不是摘要，而是描述何时触发该 skill。
    • 图 E 示例： babysit-pr 的描述写“监控 PR 直到合并，在出现 babysit、watch CI、make sure this lands 等说法时触发”，比泛泛的“综合工具”更有用。

20. 帮 Claude 记住

    • 一些 skill 可以通过在自身内部存数据来实现某种记忆，简单如只追加的文本日志或 JSON 文件，复杂如 SQLite 数据库。
    • 例如 standup-post 可维护 standups.log 记录每次发布的内容，下次运行时 Claude 读自己的历史就知道昨天以来有什么变化。
    • 可用环境变量 ${CLAUDE_PLUGIN_DATA} 获取稳定的数据存放目录。

21. 存脚本、让 Claude 生成代码

    • 能给 Claude 的最有力工具之一就是代码：提供脚本和库后，Claude 可以把回合花在组合与决定下一步上，而不是重建样板。
    • 图 G 示例：data-science skill 中有一小组取数辅助函数（fetch、by_referrer、by_landing_page），并在 docstring 里写明 user_id 在注册前为 null 之类的数据陷阱。
    • 图 H 示例：面对“周二发生了什么”这类问题，Claude 现场生成脚本组合这些函数，得出周二维首页出了问题。

22. 使用按需触发的 hooks

    • skill 可以包含只在被调用时激活、且仅在本次会话期间生效的 hook，适合那些不想常开但偶尔极为有用的强硬规则。
    • /careful：通过 Bash 的 PreToolUse 匹配器拦截 rm -rf、DROP TABLE、force-push、kubectl delete；只在明知要碰生产时需要，常开会很烦人。
    • /freeze：阻止对特定目录之外任何文件的 Edit/Write；调试时有用，比如“只想加日志却总在顺手改无关代码”。

23. 分发 Skills

    • 分享 skill 是它最大的好处之一，有两种方式：提交到仓库的 ./.claude/skills；或做成 plugin，通过 Claude Code 插件市场让用户上传和安装。
    • 跨仓库不多的小团队，把 skill 提交进仓库即可；但每个提交的 skill 都会占用一点模型上下文。
    • 规模扩大后，内部插件市场让团队自行选择安装哪些 skill，并可附带初始化流程。

24. 运营 Skills 市场

    • Anthropic 没有集中决策的团队，而是让最有用的 skill 自然浮现。
    • 想让别人试用某个 skill 的人，可以把它上传到 GitHub 的沙盒文件夹，并在 Slack 等渠道指路。
    • 当 skill 获得一定关注（由所有者自行判断）后，可提交 PR 将其移入市场。