Anthropic 团队近日公开了一套内部经验总结，详细分享了他们使用 Claude Code Skills 的实战方法论。内容涵盖技能分类、编写原则、治理与分发，这份实践指南信息密度极高，值得深入研读。

以下是对这份经验帖核心内容的提炼与解析。

一、先正确理解 Skill 的本质

Anthropic 首先纠正了一个常见误区：Skill 远不止是一段提示词，它更像是一个围绕特定任务组织起来的文件夹。

这个文件夹里可以存放 SKILL.md，也可以放入参考文档、脚本、模板、示例、hooks，甚至包括会被后续任务持续读取的数据。当 Claude 调用一个 Skill 时，它拿到的实际上是一整套完成该任务所需的全部工作材料。

这个定义至关重要。因为许多团队真正缺乏的，从来不是“再补一段提示词”，而是将那些已验证过的最佳实践、容易踩的坑、常用脚本以及固定流程，一次性整理好，便于后续反复复用。

二、Anthropic 将内部 Skills 归纳为 9 大类

Anthropic 梳理了内部使用的 Skills，大致分成 9 个类别。这 9 类连起来看，恰好构成一条完整的软件工作流——从知识补充、编码实现，到验证、部署、排障和运维。

前三类：为模型补充知识、验证手段与数据

第一类是 library 和 API reference，用于向模型解释某个库、CLI 或 SDK 在团队内部应该如何正确使用，把容易用错的规则和注意事项写清楚。

第二类是 product verification，负责判断产出是否真正有效，例如在无头浏览器中完整执行一遍注册和结账流程。Anthropic 直言这类 Skill 对输出质量提升最明显，值得让工程师专门花一周时间打磨。

第三类是 data fetching and analysis，连接数据仓库和监控系统，将取数方法、字段约定及常见分析路径封装好，模型无需再去猜测表结构和字段名。

中间三类：承接团队日常流程

第四类是 business process and team automation，把重复发生的团队流程压缩成一个命令即可运行的工作流，比如只输出相对于昨天增量的站会汇报，或固定格式的周报。Skill 不仅能承接代码任务，也能处理协作任务。

第五类是 code scaffolding and templates，生成那些带有固定骨架、同时又包含大量自然语言约束的代码，例如新建 service 或迁移文件。这正是纯模板引擎覆盖不到的部分。

第六类是 code quality and review，确保代码符合团队质量标准。典型示例是拉一个“新鲜视角”的 subagent 来挑错的 adversarial-review，这类能力还可以作为 hook 接入 CI 流程。

后三类：连接生产环境

第七类是 CI/CD and deployment，将代码从开发态推送到上线态。例如 babysit-pr 会全程监控一个 PR 的合并过程，deploy- 会把构建、灰度发布、错误率对比和回滚条件串联成一条自动化链路。

第八类是 runbooks，入口不是“我要写什么”，而是“现在出了什么状况”。当报警、Slack 线程或 request ID 出现时，它负责映射到该用哪些工具、查看哪些路径，最后给出结构化结论。

第九类是 infrastructure operations，处理资源清理、依赖治理和成本排查等例行操作。这些动作常带有破坏性，所以 Skill 里需要写明防护措施：先通知、再确认、最后才真正执行。

三、Anthropic 真正强调的，不只是“会写”，更是“写对”

梳理完 9 类分类后，Anthropic 接着分享了更底层的判断标准：什么样的 Skill 更稳健，哪些地方最值得投入精力。

好的 Skill 往往都很聚焦

Anthropic 说得非常直接：最好的 Skill 通常都高度聚焦。能够清楚归属到某一类中的 Skill，通常更稳健；试图同时覆盖过多目标的 Skill，反而容易把模型带偏。

这个判断极具参考价值。许多团队在起步阶段最容易犯的错误，就是试图“一次做大做全”，结果既不好触发，也不易维护。

所有类型中，他们最看重「验证」

在所有类型里，Anthropic 特别强调 verification。因为模型很容易给人一种“已经做完了”的假象，而真正容易出问题的地方恰恰是最后那一步验证。

原文甚至建议，值得让工程师单独花一周时间，把验证类 Skill 打磨到足够好。这个投入听起来很重，但如果它直接影响结果质量，其实非常划算。

他们还给出了两个实用建议。一是让 Claude 录下自己测试过程的视频，这样你能清楚看到它到底测试了什么。另一个是在关键节点加入程序化断言：状态是否变化、事件是否真正落库、最终页面是否达到目标状态——这些都应避免仅凭“看起来差不多”来判断。

真正有价值的内容，往往是 gotchas

Anthropic 对 Skill 中内容的优先级说得非常清楚。最有信息量的部分，通常不是通用步骤，而是那些容易出错的细节（gotchas）。

因为 Claude 本身就会写代码，也能读取代码库。那些“默认它也会做”的内容，写进 Skill 只会增加上下文负担，不一定增加价值。

真正值得写的，是那些能把模型从默认思路里“拽出来”的细节。例如：subscriptions 表是 append-only 的，要找最高 version，不能只看最新 created_at。再比如，同一个字段在 API gateway 里叫 @request_id，到了 billing 服务里却叫 trace_id。还有，staging 环境返回 200 并不代表 Stripe webhook 真的处理成功了，还得去查看 payment_events 里的真实状态。

这类信息单独看都很微小，但一旦出错，最终结果就会偏离。Skill 的价值，很多时候就体现在这些“团队里人人知道，但模型默认不知道”的地方。

四、Skill 到底该怎么写

前面讲完了“先做什么”，这一段他们分享了“具体怎么写，才能让 Skill 真正起作用”的内部经验。

1. 别把显而易见的话再写一遍

第一个细节：不要重复那些显而易见的内容。Skill 不是给人看的摘要，它要补充的是模型默认拿不到、或者默认容易走偏的信息。

Anthropic 提到过一个前端设计 Skill 的例子。它的价值不在于教 Claude 怎么写前端，而在于补充团队通过与客户反复迭代后沉淀下来的“设计品味”和避坑点——比如少用一些过于套路化的字体和配色选择。

2. SKILL.md 更像目录，不该写成大杂烩

第二个细节：SKILL.md 不要写成大杂烩。更好的做法是让它扮演目录和路标的角色，把具体资料按需分发到其他文件中。

例如，任务卡住时再去读 stuck-jobs.md。API 的函数签名和用法示例可以拆进 references/api.md。如果最终需要产出一份 markdown 文件，模板可以放进 assets/。脚本、参考资料、示例也都可以分目录存放，让 Claude 在需要时再取用。

这套做法对应的是 Anthropic 所说的“渐进式披露”（progressive disclosure）。文件系统本身，也是一种上下文工程。

3. Skill 不要写得太死

第三个细节：别把 Skill 写得太死板。你需要给 Claude 关键规则，但也要给它足够的适应空间，否则 Skill 一旦复用，就容易在其他具体情境中卡住。

4. setup 要提前规划好

第四个细节：提前设计好 setup 流程。很多 Skill 真正运行时缺少来自用户的上下文信息，比如 Slack 要发送到哪个频道。

原文建议将这类配置放入 config.json。如果配置尚未完成，Claude 会先向用户提问；如果需要结构化、多选式的提问，还可以直接调用 AskUserQuestion 工具。

5. description 要直接服务于触发

第五个细节：description 要写给模型看。Claude Code 启动时会先扫描所有 Skill 的名称和 description，再判断本次请求是否有可用的 Skill。

因此 description 不是摘要，而是触发条件说明。用户可能会说什么关键词、会上传什么文件、什么场景下应该激活这个 Skill——这些都应直接写进去。

原文还举了一个很小但很典型的点：像 "babysit" 这种触发词，就应该直接出现在 description 里。

五、Skill 用深之后，会先长出记忆、脚本和 hooks

Anthropic 专门留了一节讲解这个现象。许多 Skill 一开始只是几行说明，用得越多，最先长出来的就是记忆、脚本和 hooks 这三样东西。

先说记忆。像 standup-post 这种 Skill，可以把每次输出都记进 standups.log，下次运行时先读取历史，再判断今天和昨天相比到底变了什么。

这种记忆可以很简单，用 append-only 的文本或 JSON 就够了；也可以更复杂一些，直接用 SQLite。原文还提到，可以使用 ${CLAUDE_PLUGIN_DATA} 这个环境变量，获得一个稳定的持久化目录来存储这些数据。

再说脚本。Anthropic 的判断很明确：能赋予 Claude 的最强工具之一，其实就是代码本身。

如果你把常用的数据抓取函数、分析函数或者操作脚本预先放进去，Claude 就不用每次都从头重写样板代码，而是能把更多精力花在“如何编排”和“下一步做什么”上。

例如，数据分析类 Skill 可以直接附带一组 helper functions。这样当用户问“周二到底发生了什么”时，Claude 就能临时拼接出一段更复杂的分析脚本，而不是先花大量心力重建基础设施。

最后是 on-demand hooks。它们只在 Skill 被调用时生效，并且只在当前会话中存在。

原文举了两个很典型的例子。/careful 会拦截 rm -rf、DROP TABLE、force-push、kubectl delete 这类高风险操作；/freeze 则会阻止对指定目录之外的 Edit 和 Write 操作，适合排障时防止一边加日志一边顺手改坏其他地方。

六、当团队开始大量使用 Skill，后面就是分发和治理

这是单个 Skill 成长后的下一步。Skill 一旦开始在团队中扩散，问题就不只是“怎么写”，还会变成“怎么发给别人用、怎么持续管理”。

两条主路线：repo 内 check-in 和插件 marketplace

一种是把 Skill 直接 check in 到 repo 的 ./.claude/skills。对于规模不大的团队，或者只在少数代码库协作的团队，这已经足够好用。

另一种是做成插件，利用内部的 Claude Code Plugin marketplace 来上传和安装。当团队规模变大后，这种方式的优势更为明显。

原因很简单：每多 check in 一个 Skill，模型可见的上下文负担就会增加一点；而 marketplace 可以把安装权交给团队成员自行决定，也方便顺手完成 setup 流程。

Anthropic 在治理上并没有一开始就建立中央审批制度。更常见的做法是，谁有 Skill 想让大家试试，就先传到 GitHub 里的 sandbox 文件夹，再发到 Slack 或其他渠道供他人试用。

等这个 Skill 真正有了关注度，再由 Skill owner 提交 PR，正式将它移入 marketplace。这个流程非常轻量，但很符合 Skills 这种依赖真实使用慢慢成长起来的东西。

Skills 之间也可以互相组合

原文还提到一个很有意思的方向：skill composition（技能组合）。例如，你可以有一个文件上传 Skill，再有一个 CSV 生成 Skill，后者生成完文件后，再去调用前者完成上传。

这类依赖管理目前还不是 marketplace 或 Skill 机制中的原生能力，但只要在 Skill 里直接引用另一个 Skill 的名称，模型在已经安装了它们的前提下，照样能把链路串联起来。

还可以做 usage measurement

Anthropic 还提到，他们会使用 PreToolUse hook 记录公司内部的 Skill 使用情况。这样就能看到哪些 Skill 很受欢迎，哪些触发明显不足。

这类数据其实非常有用。因为 Skill 做出来以后，真正的问题常常不是“能不能运行”，而是“会不会在应该被触发的时候被想起来”。

写在最后

Anthropic 在文章结尾提到一个细节：他们内部最好的 Skills，一开始往往只有几行字和一个 gotcha，用得越多，才补充得越完整。

这句话基本可以当作上手指南。写 Skill 不用追求一步到位，先把验证方法写清楚，把真正踩过的坑记下来，脚本、记忆、hooks 和分发，等用起来之后再慢慢补充。

如果你也在使用 Claude Code，不妨从手头最常重复的那个任务开始。先写几行说明，加上一个 gotcha，剩下的交给时间和使用频率。