从 Claude Code 看 Agent Skills：Anthropic 内部如何设计、沉淀和规模化复用能力

Anthropic 在文章 《Lessons from building Claude Code: How we use skills》 中，分享了他们在 Claude Code 内部大规模使用 Skills 的经验。文章发布于 2026 年 6 月 3 日，核心不是介绍某一个具体功能，而是总结 Anthropic 在内部维护和使用数百个 Skills 之后，沉淀出的设计原则、分类方法和组织化分发经验。

这篇文章对做 Agent 系统的人很有参考价值。因为它回答了一个很实际的问题：

当一个 Agent 已经具备工具调用、代码执行、文件读写和上下文理解能力后，如何把团队经验、业务流程、排查方法、验证手段沉淀成可复用能力？

Anthropic 给出的答案是：使用 Skills。

但更准确地说，Skills 不是简单的 prompt 模板，也不是几段 Markdown 文档，而是一种面向 Agent 的能力封装方式。

一、Skill 不是 Markdown，而是 Agent 可探索的能力目录

文章首先澄清了一个常见误解：很多人认为 Skill 只是一个 Markdown 文件，但 Anthropic 明确指出，Skill 实际上是一个文件夹，里面可以包含说明文档、脚本、资源文件、示例代码、数据文件等内容，Agent 可以按需发现、读取、执行和组合这些资源。

这点非常关键。

如果把 Skill 理解成一段提示词，那么它只能告诉 Agent “应该怎么想”。
但如果把 Skill 理解成一个能力目录，它就可以同时提供：

1
2
3
4
5
6
7
8
9
10
1. 任务说明
2. 使用条件
3. 常见错误
4. 示例代码
5. 可执行脚本
6. 输出模板
7. 参考文档
8. 配置文件
9. 持久化状态
10. 安全钩子

这意味着 Skill 本质上是一种 轻量级、可分发、可演化的 Agent 能力包。

它不只是给模型补充知识，更重要的是把组织内部已经验证过的流程、工具使用方式、错误规避经验和输出标准，变成 Agent 可以复用的工程资产。

二、好的 Skill 应该聚焦，而不是包罗万象

Anthropic 在整理内部 Skills 后发现，这些 Skills 大致可以归为九类。文章特别强调，最好的 Skills 通常能清晰落入某一类；那些试图同时做太多事的 Skills，往往会跨多个类别，从而让 Agent 感到困惑。

这个判断很有价值。

很多团队在建设 Agent 能力库时，容易把一个 Skill 写成“大而全”的超级说明文档：既包含业务背景，又包含工具说明，又包含排障流程，又包含数据分析规则，还包含最终输出格式。结果是 Skill 看起来很完整，但模型触发时不知道重点在哪里。

Anthropic 的经验说明，Skill 应该有明确边界。一个 Skill 最好解决一类稳定问题，而不是覆盖一个模糊领域。

文章归纳出的九类 Skills 包括：

1
2
3
4
5
6
7
8
9
1. Library and API reference
2. Product verification
3. Data fetching and analysis
4. Business process and team automation
5. Code scaffolding and templates
6. Code quality and review
7. CI/CD and deployment
8. Runbooks
9. Infrastructure operations

这些分类并不是唯一标准，但它提供了一个很实用的能力地图。

如果一个团队要建设自己的 Agent Skills，可以先不用急着写具体内容，而是先问：

1
2
3
4
5
6
7
8
9
我们缺的是工具/API 使用说明？
还是验证流程？
还是数据分析流程？
还是业务自动化流程？
还是代码模板？
还是审查规范？
还是部署流程？
还是故障 Runbook？
还是基础设施操作规范？

这个问题能帮助团队避免把所有内容塞进一个 Skill。

三、Anthropic 的九类 Skills 说明了什么

文章中最值得关注的，不只是九个分类本身，而是这些分类背后的设计思想。

第一类是 Library and API reference。这类 Skill 用来告诉 Agent 如何正确使用某个库、CLI 或 SDK，尤其是内部工具和容易用错的第三方库。它通常包含代码片段、参数说明和常见陷阱。

这说明 Skill 很适合承载“组织内部工具知识”。很多工具并不复杂，但使用时有隐含约定，比如哪个参数不能乱填、哪个字段已经废弃、哪个命令只能在特定环境执行。这些知识如果只存在于老员工脑子里，Agent 很容易犯错。

第二类是 Product verification。这类 Skill 用于验证代码或产品功能是否真的工作，例如配合 Playwright、tmux 等工具进行 UI、CLI 或交互式流程验证。Anthropic 特别提到，验证类 Skills 在内部对 Claude 输出质量的提升最可衡量，甚至值得工程师专门花一周时间把验证 Skills 做好。

这个经验非常重要。

很多 Agent 系统把重点放在“生成”上，却忽视“验证”。但对工程任务而言，Agent 写完代码、生成配置、执行流程之后，必须有验证闭环。Skill 不仅可以告诉 Agent 怎么做，还可以告诉 Agent 怎么证明自己做对了。

第三类是 Data fetching and analysis。这类 Skill 连接数据和监控系统，可能包含数据拉取脚本、凭证使用方式、Dashboard ID、数据源命名规则、常见分析流程等。文章举的例子包括 funnel 查询、cohort 对比、Grafana、Datadog 等。

这说明 Skill 可以作为数据分析流程的入口，而不是让 Agent 每次都从零探索数据系统。

第四类是 Business process and team automation。这类 Skill 把重复业务流程压缩成一个可执行命令，例如生成站会内容、创建工单、生成周报等。文章还提到，对于这类流程，保存历史执行结果可以帮助模型保持一致，并反思过去的执行情况。

第五类是 Code scaffolding and templates。这类 Skill 用于生成特定代码库中的标准模板，比如新建服务、新建 migration、新建内部应用等。它的价值在于把组织约定固化下来，让 Agent 不只是会写代码，而是会按照团队已有工程风格写代码。

第六类是 Code quality and review。这类 Skill 用于代码审查、质量约束和测试实践，也可以结合确定性脚本或 GitHub Action 自动运行。Anthropic 举了 adversarial-review、code-style、testing-practices 等例子。

第七类是 CI/CD and deployment。这类 Skill 用于 PR 监控、CI 重试、合并冲突处理、部署、灰度、回滚等工程流程。

第八类是 Runbooks。这类 Skill 从症状出发，比如 Slack 线程、告警或错误签名，引导 Agent 进行多工具排查，并生成结构化报告。

第九类是 Infrastructure operations。这类 Skill 面向常规维护和基础设施操作，其中部分操作具有破坏性，因此特别需要 guardrails。文章举例包括清理孤儿资源、依赖管理、成本调查等。

综合来看，Anthropic 的 Skill 分类说明了一件事：

Skill 不是为了补充模型不会的知识，而是为了把组织中可重复、可验证、有约束的工作方式，沉淀成 Agent 可调用的能力单元。

四、不要写显而易见的内容

在 Skill 编写建议中，Anthropic 的第一条就是：不要陈述显而易见的内容。

Claude 已经知道如何写代码，也能读取代码库。如果一个 Skill 只是重复模型默认会做的事情，它只会增加上下文负担，却不会带来实际价值。文章建议，如果 Skill 主要承载知识，就应该聚焦那些能把 Claude 从默认思考路径中拉出来的信息。

这条经验非常实用。

低质量 Skill 常见写法是：

1
2
3
4
5
请阅读代码。
请理解需求。
请写清晰代码。
请添加注释。
请保证代码正确。

这些内容基本没有价值，因为模型默认就知道。

高质量 Skill 应该写的是：

1
2
3
4
这个内部 API 的 page_token 不是标准游标，不能跨 filter 复用。
这个表是 append-only，查询当前状态时必须取最高 version。
这个环境返回 200 不代表 webhook 真的处理成功，需要查事件表确认。
这个服务里 request_id 和 trace_id 是同一个值，但字段名在不同系统中不一致。

也就是说，Skill 的价值来自 非显然知识、组织特有约定 和 模型容易踩坑的地方。

五、Gotchas 是 Skill 中最高信号密度的部分

Anthropic 明确指出，任何 Skill 中信号密度最高的部分通常是 Gotchas，也就是常见陷阱和注意事项。这些内容应该来自 Claude 在实际使用 Skill 时遇到的失败点，并随着时间持续更新。

这实际上给出了 Skill 演化的正确方式：

1
2
3
4
5
6
不要试图一开始就写出完美 Skill。
先写一个最小版本。
让 Agent 在真实任务中使用。
观察它在哪里失败。
把失败点沉淀到 Gotchas。
不断迭代。

Gotchas 的作用不是教模型通用知识，而是显式拦截高频错误路径。

对于工程团队来说，这一点尤其重要。因为很多错误不是来自模型能力不足，而是来自“局部约定不透明”。比如：

1
2
3
4
5
6
字段名看起来一样，但含义不同；
表名看起来正确，但已经废弃；
接口返回成功，但业务状态没有完成；
测试环境行为和生产环境不一致；
CLI 参数顺序错误会产生危险操作；
某些命令必须先 dry-run。

这些内容如果不写进 Skill，Agent 大概率会反复犯同样的错。

六、把文件系统当作上下文工程工具

Anthropic 反复强调，Skill 是一个文件夹，不只是一个 Markdown 文件。文章建议把整个文件系统看作一种 context engineering 和 progressive disclosure 机制。

所谓 progressive disclosure，就是不要一次性把所有内容都塞进 SKILL.md，而是让 SKILL.md 作为入口，只提供任务触发条件、总流程和索引。当 Agent 遇到具体情况时，再按需读取更细的参考文件。

例如：

1
2
3
4
5
6
7
8
9
10
11
12
skill/
  SKILL.md
  references/
    api.md
    schema.md
    examples.md
  scripts/
    fetch_data.py
    verify_state.py
  assets/
    report_template.md
  gotchas.md

这种结构比一个超长 Markdown 更适合 Agent 使用。

因为 Agent 在启动时不需要读取所有细节，只需要知道：

1
2
3
4
这个 Skill 适合什么任务；
遇到什么情况该看哪个文件；
有哪些脚本可以调用；
最终输出应该参考哪个模板。

这和传统 prompt 工程有明显不同。Prompt 工程倾向于把内容塞进上下文；Skill 工程则强调按需加载、分层组织和可执行资源。

七、不要把 Claude “钉死”在单一路径上

Anthropic 还提醒：不要过度 railroading Claude。

因为 Claude 通常会尽量遵循 Skill 中的说明，而 Skill 又具有复用性，所以如果说明写得过于具体，反而可能让模型在不适合的情况下也机械执行固定流程。文章建议给 Claude 必要信息，但保留根据具体情况调整的灵活性。

这条经验可以概括为：

1
2
Skill 应该约束关键路径，
但不要替代模型判断。

低质量 Skill 往往写成：

1
无论什么情况，都先执行 A，再执行 B，再执行 C。

更好的写法是：

1
2
3
4
5
通常优先执行 A。
如果出现某类症状，再执行 B。
如果数据缺失，先向用户确认。
如果风险较高，进入验证流程。
如果结果冲突，停止并输出不确定性。

这类写法给 Agent 提供决策框架，而不是死板脚本。

八、Skill 需要考虑初始化和配置

有些 Skill 需要用户提供初始配置，比如 Slack channel、工单系统项目 ID、默认环境、常用仓库、通知对象等。Anthropic 建议把这类 setup 信息存放在 Skill 目录中的 config.json 里。如果配置缺失，Agent 可以向用户询问必要信息。

这个建议很实际。

很多团队一开始写 Skill 时只关注执行流程，却忽略了 Skill 的配置生命周期。结果是每次执行都要重新问用户，或者把配置硬编码在文档里，难以复用和分发。

更好的方式是：

1
2
3
4
5
1. Skill 自带默认配置
2. 用户首次使用时补充缺失配置
3. 配置写入本地文件
4. 后续执行自动复用
5. 配置变更有明确入口

这样 Skill 才能从“临时提示词”变成“长期可用工具”。

九、Skill 描述是写给模型看的，不是写给人看的

Anthropic 提到，Claude Code 启动会构建一个可用 Skills 列表，并读取每个 Skill 的 description 来判断用户请求是否应该触发该 Skill。因此，description 不是给人看的摘要，而是给模型看的触发条件。

这个点非常容易被忽视。

很多团队会把 Skill description 写成：

1
用于处理订单相关任务。

这对模型帮助不大。

更好的 description 应该包括触发词、任务场景和边界，例如：

1
2
3
当用户要求排查订单支付状态、核对支付回调、检查 invoice 状态、
或提到 checkout、Stripe、payment_events 时使用本 Skill。
不要用于退款策略分析。

也就是说，Skill description 应该回答：

1
2
3
什么时候该用我？
什么时候不该用我？
用户会用哪些自然语言表达来触发我？

这本质上是 Skill Router 的入口设计。

十、让 Skill 具备“记忆”

Anthropic 还提到，Skill 可以通过存储文件具备某种形式的记忆。这个存储可以很简单，比如 append-only text log 或 JSON 文件，也可以更复杂，比如 SQLite 数据库。文章举例说，一个站会 Skill 可以保存每次生成的 standup 内容，这样下次运行时，Claude 就能读取历史记录并判断和昨天相比发生了什么变化。

这说明 Skill 不只是静态知识包，也可以承载轻量状态。

对于重复流程来说，记忆非常重要。因为很多任务不是一次性问答，而是周期性执行。例如：

1
2
3
4
5
昨天汇报过什么？
这次新增了哪些变更？
上次排查到哪里？
某个 PR 之前审查过哪些问题？
某个流程上次失败在哪一步？

这些信息如果每次都依赖用户重新输入，Agent 的连续性会很差。通过 Skill 内部持久化，Agent 可以在流程级别形成上下文延续。

十一、给 Claude 代码，而不是让它每次重写样板

Anthropic 认为，能给 Claude 的最强工具之一就是代码。Skill 中可以包含脚本和库，让 Claude 把精力放在组合和决策上，而不是每次从零重写样板逻辑。

这条经验非常关键。

如果一个 Agent 每次执行数据拉取、接口调用、格式转换、验证检查时都重新生成代码，那么它会有几个问题：

1
2
3
4
5
1. 容易重复犯低级错误
2. 每次实现略有差异
3. 难以复用团队已有最佳实践
4. 难以审计
5. 难以测试

把稳定逻辑写成脚本放进 Skill，可以显著提高可靠性。

理想状态是：

1
2
稳定、可测试、确定性的部分 → 脚本/库
灵活、需要判断和组合的部分 → 交给 Agent

这也是 Agent 工程化的核心原则之一。不要让模型承担所有工作，而是让模型做最适合它的部分：理解目标、选择路径、组合工具、解释结果。

十二、按需启用 Hooks，给高风险操作加临时护栏

文章提到，Skills 可以包含只在 Skill 被调用时启用的 hooks，并且这些 hooks 只在当前会话期间生效。Anthropic 举了两个例子：一个是 /careful，可以通过 PreToolUse matcher 阻止 rm -rf、DROP TABLE、force-push、kubectl delete 等危险命令；另一个是 /freeze，限制 Edit/Write 只能发生在特定目录，用于调试时防止模型修改无关代码。

这个设计很有启发。

很多安全规则如果全局启用，会让日常使用变得很痛苦；但在某些场景下，它们又非常必要。按需 hooks 的价值就在于：

1
2
3
平时保持灵活；
高风险任务中临时收紧权限；
任务结束后自动恢复正常。

这比“一刀切”的安全策略更适合 Agent。

十三、Skill 的分发：小团队进仓库，大团队建市场

Anthropic 提到，Skills 的一个重要价值是可以在团队内共享。文章给出两种主要分发方式：一种是把 Skills 放进代码仓库，比如 ./.claude/skills；另一种是制作插件，并通过 Claude Code Plugin marketplace 让用户安装。

对于小团队和少量仓库，把 Skill 直接随仓库管理很合适。这样 Skill 可以和代码一起演化，团队成员进入仓库后自然获得对应能力。

但随着规模扩大，每个仓库都内置大量 Skills 会增加模型上下文负担，也会带来维护问题。因此，Anthropic 建议使用内部插件市场，让团队按需安装 Skills，并支持 setup flow。

这个经验可以抽象为：

1
2
3
早期：Repo-local Skills
中期：团队共享 Skills
后期：内部 Skill Marketplace

Skill 分发方式应该随着组织规模变化，而不是一开始就过度平台化。

十四、Skill 市场不一定要中心化审批

在 Skill marketplace 管理上，Anthropic 的做法也很有意思。他们并没有设立一个中心团队统一决定哪些 Skills 能进入市场，而是让有用的 Skills 自然冒出来。个人可以先把 Skill 上传到 GitHub 的 sandbox 文件夹，再通过 Slack 或其他渠道让大家试用。当某个 Skill 获得足够使用后，再由 owner 发 PR 移入 marketplace。

这是一种很务实的组织机制。

如果一开始就要求所有 Skill 经过中心化评审，门槛太高，团队可能不愿意贡献。
如果完全没有治理，Skill 又容易泛滥，质量参差不齐。

Anthropic 的方式介于两者之间：

1
2
3
先低成本试用；
再基于真实使用情况筛选；
最后进入正式市场。

这有点像开源社区的孵化机制，也适合内部工具生态。

十五、Skill 可以组合，但要谨慎管理依赖

文章提到，有些 Skills 之间会存在依赖关系。例如，一个文件上传 Skill 可以负责上传文件，另一个 CSV 生成 Skill 可以生成 CSV 并调用上传能力。虽然 marketplace 和 Skills 当前还没有原生 dependency management，但可以在 Skill 中通过名称引用其他 Skills，如果它们已安装，模型就可以调用。

这说明 Skill 不一定是孤立能力，它可以形成组合。

但这里也隐含一个风险：当 Skill 之间依赖过多时，系统复杂度会上升。团队需要注意：

1
2
3
4
不要让一个 Skill 隐式依赖太多其他 Skill；
依赖关系要在文档里明确；
被依赖 Skill 的能力边界要稳定；
组合 Skill 应该只组合流程，不重复定义底层规则。

否则 Skill 库会从“能力复用”变成“隐式耦合”。

十六、Skill 需要度量，而不是凭感觉维护

Anthropic 使用 PreToolUse hook 记录公司内部 Skill 使用情况，从而发现哪些 Skills 很受欢迎，哪些 Skills 触发不足。

这说明 Skill 进入规模化阶段后，必须可观测。

一个 Skill 写得好不好，不应该只靠作者感觉，而应该看：

1
2
3
4
5
6
7
8
1. 被触发次数
2. 触发是否符合预期
3. 是否经常误触发
4. 使用后任务成功率是否提升
5. 是否减少人工介入
6. 是否经常需要用户纠正
7. 是否在某些场景下失败
8. 是否已经过期

这和软件工程里的监控类似。Skill 不是静态文档，而是 Agent 系统中的运行时组件，因此也需要 telemetry。

十七、最好的 Skill 往往从几行内容开始

文章最后强调，Skills 的最佳实践仍然在演化中。Anthropic 内部很多最好的 Skills，最开始只是几行说明和一个 Gotcha，后来随着 Claude 遇到新的边界情况，团队不断补充，最终变得越来越好。

这个结论很重要，因为它降低了团队建设 Skills 的心理门槛。

不需要一开始就设计完整平台，也不需要一开始就写几十页规范。更好的方式是：

1
2
3
4
5
6
先找一个高频、稳定、容易出错的任务；
写一个最小 Skill；
让 Agent 在真实任务中使用；
收集失败点；
补充 Gotchas、脚本、模板和验证逻辑；
再考虑分发和度量。

Skill 的价值不是一次性写出来的，而是在反复使用和纠错中长出来的。

十八、从文章中可以提炼出的通用经验

综合 Anthropic 的文章，可以提炼出一套通用的 Skill 设计原则。

第一，Skill 是能力包，不是提示词。
它可以包含文档、脚本、配置、模板、状态和 hooks。

第二，Skill 要聚焦单一任务类型。
越清晰的边界，越容易被模型正确触发和使用。

第三，不要写模型已经知道的常识。
Skill 应该沉淀组织特有知识、工具约定和错误规避经验。

第四，Gotchas 是 Skill 的核心资产。
常见失败点应该被持续收集并写回 Skill。

第五，用文件系统做渐进式上下文加载。
SKILL.md 只做入口和路由，细节拆到 references、scripts、assets 等目录。

第六，稳定逻辑写成脚本，灵活决策交给 Agent。
不要让模型每次重写可确定的样板代码。

第七，Skill 描述要服务于模型触发。
description 应该描述什么时候使用，而不是给人类写摘要。

第八，高风险操作需要按需护栏。
hooks 可以在特定任务中临时限制危险命令或写入范围。

第九，Skill 需要分发机制。
小团队可以放仓库，大团队需要插件市场或内部能力市场。

第十，Skill 需要度量和演化。
记录触发、成功、误触发和失败情况，才能持续改进。

结语：Skill 是 Agent 工程化的关键载体

这篇文章的价值不在于告诉我们 Claude Code 有哪些具体功能，而在于展示了一种 Agent 工程化思路：

不要把所有能力都塞进一个巨大的系统 prompt，也不要让 Agent 每次从零探索工具、流程和组织经验。应该把稳定、可复用、可验证的能力沉淀为 Skills，让 Agent 在需要时按需加载和组合。

从这个角度看，Skill 是介于 prompt、文档、脚本、工具和工作流之间的一种新型工程资产。

它既不像传统脚本那样死板，也不像纯 prompt 那样不可控。
它把人类团队的经验、流程、模板、验证方式和安全约束，组织成 Agent 可以理解和执行的能力单元。

一句话总结 Anthropic 的经验：

好的 Skill 不是告诉 Agent “你要聪明地完成任务”，而是把团队已经验证过的正确路径、常见陷阱、可执行工具和验证方法交给 Agent，让它少猜、多复用、可验证地完成任务。