重磅Anthropic内部Skills经验全部公开核心内容深度详解

Anthropic 终于公开了其团队内部使用 Claude Code Skills 的实战经验。 这份经验分享的含金量极高。他们不仅完整复盘了内部团队的用法，还将 Skills 划分为 9 个类别，并明确指出哪类最值得投入精力、如何编写才能真正落地执行。这些宝贵内容此前仅在内部流传，如今一次性对外公开。 在阅读这份经验帖时，一个明显的感受是：他们的思路非常务实，摒弃了所有空洞的理论。今天，我将把这篇核心经验拆解透彻，为你彻底讲清楚。 **首先，正确理解 Skill 的概念** 如果你去询问 Anthropic，他们大概率会先纠正一个常见误解：Skill 并不仅仅是几段提示词。 它更像是一个围绕特定任务组织的“文件夹”。这个文件夹中可以包含 SKILL.md 文件，也可以存放参考文档、脚本、模板、示例、hooks，甚至包括那些会被后续任务继续读取的数据。当 Claude 调用一个 Skill 时，它实际上获取了一整套完成该任务所需的工作材料。 这个定义至关重要。因为许多团队真正缺乏的，从来不是“再补一段提示词”。他们真正需要的是，将那些已经验证有效的做法、踩过的坑、常用的脚本和固定流程，一次性整理好，然后反复复用。 **Anthropic 将内部 Skills 归为 9 类** 他们将内部盘点的 Skills 大致分为 9 类。这 9 类内容串联起来，几乎精确对应了一条软件工程的全流程：从知识补充到代码编写，再到验证、部署、故障排除和运维。 先看前三类：**为模型补充知识、验证、数据**。 第一类是 **library 和 API reference**。其作用是向模型解释某个库、CLI 或 SDK 在团队内部应该如何正确使用，尤其是那些容易出错的使用规则和“陷阱”。第二类是 **product verification**。这类 Skill 负责判断产出是否真的能正常工作，例如在无头浏览器中完整执行一遍注册和结账流程。他们明确表示：这类 Skill 对输出质量的提升最为显著，值得工程师花费一周时间专门打磨。第三类是 **data fetching and analysis**。它连接数据仓库和监控系统，将取数方法、字段约定和常见分析路径封装好，这样模型就不必再去猜测表结构和字段名。 再看中间三类：**开始接手日常流程**。 第四类是 **business process and team automation**。它可以将一些重复发生的团队流程，压缩成一个命令即可运行的工作流，例如只输出相对于昨天增量的 standup 报告，或者固定格式的周报。这可以看出，Skill 接手的不仅是代码任务，也包括协作任务。第五类是 **code scaffolding and templates**。它负责生成那些具有固定骨架，同时又带有大量自然语言约束的代码，例如新建一个 service 或生成迁移文件。这正是纯模板引擎无法覆盖的部分。第六类是 **code quality and review**。其目标是让代码尽可能符合团队的质量标准。一个典型例子是拉取一个“新鲜视角”的 subagent 来挑错的 adversarial-review，这种能力还可以做成 hook 集成到 CI 中。 最后是三类：**已经连接到生产环境**。 第七类是 **CI/CD and deployment**。它将代码从开发阶段推到上线阶段。例如 babysit-pr 会盯完一个 PR 的全过程，deploy- 会将 build、放量、错误率对比和回滚条件串联成一条完整的链路。第八类是 **runbooks**。其入口不是“我要写什么”，而是“现在出现了什么症状”。报警、Slack thread、request ID 进入后，它会自动匹配应该使用哪些工具、查询哪些路径，最终给出结构化的结论。第九类是 **infrastructure operations**。它负责处理资源清理、依赖治理和成本排查等例行操作。由于这些操作常常具有破坏性，因此 Skill 中必须明确写清楚 guardrail：先通知、再确认，最后才真正执行。 **Anthropic 真正强调的，不仅是“会写”，更是“写对”** 将 9 类内容梳理完毕后，他们接着讲述了几条更底层的判断：什么样的 Skill 更稳定？哪些地方最值得投入精力？ **好的 Skill，往往都很聚焦** 说起来可能有些反直觉，但最好的 Skill 往往都很聚焦。能够清晰归入某一类别的 Skill，通常更稳定；试图同时覆盖过多目标的 Skill，反而更容易让模型混乱。这个判断极具参考价值。许多团队一开始最容易犯的错误，就是想“一次做大做全”，结果导致既难以触发，又难以维护。 **在所有类型中，他们最看重“验证”** 在所有类型中，验证类 Skill 被特别强调。因为模型最容易给人一种“已经做完了”的错觉，而真正容易出问题的环节，恰恰是最后一步验证。原文甚至建议，值得让工程师单独花一周时间，将验证类 Skill 打磨得足够好。这个投入听起来很重，但如果它直接影响最终交付的质量，其实非常划算。 他们还给出了两个非常实用的建议。一是让 Claude 录制自己测试过程的视频，这样你可以清楚地看到它到底测试了什么。二是在关键节点添加程序化断言：状态是否发生变化？事件是否真正落库？最终页面是否到达目标状态？这些都应尽量避免仅凭“看起来差不多”来判断。 **真正有价值的内容，往往是 gotchas** 在 Skill 内容的优先级排序上，他们的观点也很清晰。最具信号量的部分，通常不是通用步骤，而是那些“陷阱”。因为 Claude 本来就会写代码，也会读代码库。那些“默认它也会做”的内容，写进 Skill 只会增加上下文，但不一定增加价值。 真正值得写的，是那些能够将模型从默认思路中拉出来的细节。例如：subscriptions 表是 append-only 的，要查找最高 version，不能只看最新 created_at。再比如，同一个字段在 API gateway 中称为 @request_id，而在 billing 服务中则称为 trace_id。还有 staging 返回 200，并不代表 Stripe webhook 真的处理成功了，还需要查看 payment_events 中的真实状态。这类信息单独看都不大，但一旦出错，最终结果就会偏离。Skill 的价值，很多时候就体现在这些“团队里人人知道，但模型默认不知道”的地方。 **Skill 到底该怎么写？** 前面讲完了“先做什么”，接下来这部分是“具体怎么写，才能让 Skill 真正发挥作用”的内部经验。 第一个建议非常直接：**不要将显而易见的规则再写一遍**。Skill 不是给人看的摘要，它要补充的是模型默认无法获取、或者默认容易走偏的信息。他们举过一个前端设计 Skill 的例子：它的价值不在于教 Claude 怎么写前端，而在于补充团队通过和客户反复迭代后沉淀下来的“设计品味”和避坑点，例如少用过于套路化的字体和配色。 第二个建议：**SKILL.md 更像目录，而不应该写成大杂烩**。更好的做法是让它作为目录和路标，将具体资料按需分发到其他文件里。例如，任务卡住了，再去读取 stuck-jobs.md；API 的函数签名和用法示例，可以拆分到 references/api.md；如果最终要产出一份 markdown 文件，那么模板可以放在 assets/ 中。脚本、参考资料、例子都可以分目录存放好，让 Claude 在需要时再去获取。这套做法对应的就是所谓的 progressive disclosure。文件系统本身，也是一种上下文工程。 第三个建议：**不要将 Skill 写得太死**。你需要给 Claude 关键规则，但也要给它足够的适应空间，否则 Skill 一旦复用，就容易在其他具体情境中卡住。 第四个建议：**提前想好 setup**。许多 Skill 真正运行时，会缺少一些来自用户的上下文，例如 Slack 要发送到哪个频道。建议将这类配置放到 config.json 中。如果配置尚未建立，Claude 可以先询问用户；如果需要结构化、多选式提问，还可以直接调用 AskUserQuestion 工具。 第五个建议：**description 要直接服务于触发**。Claude Code 启动时会先扫描所有 Skill 的名称和 description，再判断本次请求是否有可用的 Skill。因此，description 不是摘要，而是触发条件说明。用户可能会说哪些关键词？会上传什么文件？什么场景下应该激活这个 Skill？这些信息都应直接写进去。他们还举了一个很小的例子：像“babysit”这种触发词，就应该直接出现在 description 中。 **Skill 使用深入后，会先长出记忆、脚本和 hooks** 他们专门留了一个章节来讲述这一点。许多 Skill 一开始只是几行说明，随着使用频率增加，最先成长出来的就是记忆、脚本和 hooks 这三样。 先说记忆。例如 standup-post 这种 Skill，可以将每次输出记录到 standups.log 中，下次运行时先读取历史，再判断今天和昨天相比究竟改变了什么。这种记忆可以很简单，使用 append-only 文本或 JSON 即可；也可以复杂一些，直接使用 SQLite。他们还提到，可以使用 $CLAUDE_PLUGIN_DATA 这个环境变量，获取一个稳定的持久化目录来存储这些数据。 再说脚本。能给 Claude 的最强工具之一，其实就是代码本身。如果你将常用的数据抓取函数、分析函数或者操作脚本预先放入，Claude 就不必每次从零重写样板代码，而是将更多精力放在“如何编排”和“下一步做什么”上。例如，数据分析类 Skill 可以直接带一组 helper functions，这样当用户询问“周二到底发生了什么”时，Claude 就能临时拼凑出一段更复杂的分析脚本。 最后是 on-demand hooks。它们只在 Skill 被调用时生效，并且只在当前会话中存在。两个很典型的例子：/careful 会拦截 rm -rf、DROP TABLE、force-push、kubectl delete 这类高风险操作；/freeze 则会阻止对指定目录之外的 Edit 和 Write，适合在故障排除时，防止自己一边加日志一边顺手改坏其他地方。 **当团队开始大量使用 Skill，后面就是分发和治理** 这应该是那些已经在生产环境中将 Skills 真正运行起来的团队，才会遇到的问题。Skill 一旦在团队中扩散，问题就不只是“怎么写”，还会变成“如何发给别人用、如何持续管理”。 两条主要路线：**repo 内 check-in 和插件 marketplace**。一种思路是直接将 Skill check in 到 repo 中的 ./.claude/skills 目录。对于规模不大的团队，或者只在少数代码库协作的团队，这已经很好用。另一种是做成插件，使用内部的 Claude Code Plugin marketplace 来上传和安装。团队规模变大后，这种方式的优势会更明显，因为每多 check-in 一个 Skill，模型可见的上下文负担就会增加；而 marketplace 可以将安装权交给团队成员自己决定。 在治理方面，他们并没有一开始就采用中央审批制度。更常见的方式是，谁有 Skill 想给大家试用，就先传到 GitHub 中的 sandbox 文件夹，再发到 Slack 让别人试用。等这个 Skill 真正产生了影响力，再由 Skill owner 提交 PR，将其正式移入 marketplace。这个流程很轻量，但非常符合 Skills 这种依靠真实使用慢慢成长出来的特性。 Skills 之间也可以互相组合。例如，你可以有一个文件上传 Skill，再有一个 CSV 生成 Skill，后者生成完文件后，再去调用前者完成上传。这类依赖管理目前还不是原生能力，但只要在 Skill 中直接引用另一个 Skill 的名称，模型在安装了这些 Skill 的前提下，照样能够将链路串联起来。 还可以进行 **usage measurement**。他们会使用 PreToolUse hook 记录公司内部的 Skill 使用情况，这样就能看到哪些 Skill 很热门，哪些明显触发不足。这类数据其实很有用，因为 Skill 制作出来之后，真正的问题常常不是“能否运行”，而是“是否会在该触发的时候被想起来”。 **写在最后** Anthropic 在文章结尾提到一个非常朴素的细节：他们内部最好的 Skills，一开始往往只有几行字和一个 gotcha，使用得越多，才补充得越完整。 这句话基本可以作为上手指南。编写 Skill 不必追求一步到位，先把验证方法写清楚，把真正踩过的坑记录下来。脚本、记忆、hooks 和分发，等使用起来之后再慢慢补充。 如果你也在使用 Claude Code，不妨从手头最常重复的那个任务开始。先写几行说明，加上一个 gotcha，剩下的，交给时间和使用频率。