从 Claude Code 的实践看，Agent 能力如何被工程化

Anthropic 在《Lessons from Building Claude Code: How We Use Skills》里讲了一件很重要的事：skills 已经成为 Claude Code 最常用的扩展点之一。很多人把它理解成“多写几个 Markdown 提示词”，但从他们的实践看，真正有效的 skill 远不止一段说明文字，而是一个可以被 agent 发现、读取、调用和持续迭代的能力包。

如果只用一句话概括这篇文章的核心观点，那就是：skill 的本质不是提示词模板，而是把组织经验、脚本、数据、流程和约束，封装成可复用的 agent 能力单元。

为什么这篇文章值得看

这篇文章最有价值的地方，不是再次解释什么是 skill，而是把“怎样的 skill 真的有用”讲清楚了。

Anthropic 内部已经在大规模使用 skills，并且活跃中的 skill 数量达到了数百个。也正因为用得足够多，他们看到的不是理想化设计，而是非常具体的工程经验：哪些 skill 值得做、哪些写法更容易触发、哪些结构能让 agent 真正变强，以及 skill 应该如何在团队中分发和演化。

换句话说，这篇文章不是功能介绍，而是一份来自真实使用现场的方法论总结。

Skills 的本质：不是单文件 Prompt，而是“能力目录”

原文反复强调一个常见误解：skill 不是“只是一个 Markdown 文件”。

在 Claude Code 里，skill 更像一个目录。这个目录里除了 SKILL.md，还可以放脚本、参考资料、模板、示例数据、配置文件，甚至用于运行时记录历史的持久化数据。模型并不是一次性吞下所有内容，而是根据任务需要逐步探索这些文件。

这意味着，skill 的设计思路也应该变化：

• 不是把所有信息都塞进一大段提示词里
• 而是把真正重要的内容拆到合适的文件中
• 让 agent 在需要的时候再读取

这其实已经不是传统意义上的 prompt engineering，而更接近 context engineering + capability packaging。Prompt 只是入口，文件系统、脚本和数据结构才是真正拉开效果差距的部分。

Anthropic 总结出的 9 类 Skills

原文把内部常见的 skills 总结成了 9 个类别。这个分类很有启发，因为它告诉我们，skill 并不只适用于“生成代码”。

1. 库与 API 参考

这类 skill 用来告诉 agent 某个库、CLI 或 SDK 应该怎么正确使用，尤其适合内部工具、私有封装或者默认文档不完整的系统。它的价值在于减少“看起来会写、实际上容易踩坑”的错误。

2. 产品验证

这类 skill 关注“代码是否真的工作了”。比如配合 Playwright、tmux 等工具，自动走通注册、支付、命令行交互等流程，再结合断言来验证状态。原文非常强调这一类 skill，因为它直接决定 agent 输出是不是可被信任。

3. 数据获取与分析

这类 skill 把数据源、监控平台、查询方式和常见分析流程封装起来，让 agent 能更快定位问题、做漏斗分析、对比 cohort，或者查看 Grafana 上的关键面板。

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

这类 skill 把重复性工作流变成“一条命令”。例如整理 standup、生成 weekly recap、创建 ticket、补全创建后的通知流程。它们不一定最复杂，但往往最容易在团队里快速产生效率收益。

5. 代码脚手架与模板

这类 skill 适合生成组织内部有强约束的代码骨架，比如新的 workflow、新的 migration、新服务初始化等。它的重点不是“会不会生成”，而是“生成后能不能符合团队规范”。

6. 代码质量与审查

这类 skill 用来统一代码风格、审查方式和测试实践。文章里提到的一个例子很有意思：让一个“fresh-eyes”子代理做对抗式 review，持续提出问题并迭代修复，直到剩下的只是无伤大雅的小问题。

7. CI/CD 与部署

这类 skill 帮助 agent 理解如何构建、测试、推送、部署和回滚代码。对于需要遵循内部发布规范的团队，这类 skill 可以明显减少流程性错误。

8. Runbook

这类 skill 针对线上问题调查。输入可以是报警、错误签名或者某个 Slack 线程，然后由 skill 指导 agent 走完一套调查流程，最后输出结构化报告。

9. 基础设施运维

这类 skill 面向清理资源、依赖审批、成本调查等偏运维流程，通常包含潜在破坏性操作，因此特别需要护栏和确认机制。

如果把这 9 类放在一起看，会发现一个很重要的结论：skill 的适用范围覆盖了知识获取、代码生成、验证测试、业务流程、线上排障和基础设施操作，几乎贯穿了完整的软件交付链路。

一张图看懂：一个好 Skill 是如何演化出来的

下面这张图概括了原文隐含的方法论：skill 不是一次性写完的，而是在真实使用中不断补全的。

最关键的一步不是“先写很多”，而是让它先被用起来，然后围绕真实失败点持续补强。

做好一个 Skill，文章给出的 7 条关键经验

原文后半部分非常有价值，因为它不是在列功能，而是在总结如何写出真正有效的 skill。下面是我认为最值得记住的 7 条。

1. 不要重复常识，要补模型默认做不好的地方

如果一个 skill 只是把模型本来就知道的东西再说一遍，它的价值会很有限。高质量 skill 应该提供的是组织内部知识、反常识规则、特殊约束，或者模型特别容易犯错的地方。

文章提到一个很典型的例子：前端设计 skill 的重点不是重新教模型什么是按钮和卡片，而是纠正模型默认会走向的审美惯性，例如总爱用 Inter 字体、紫色渐变、陈词滥调的布局。

2. Gotchas 是信号最强的部分

原文明确说，任何一个 skill 里最有价值的内容，往往都是 Gotchas。也就是那些“模型最容易踩坑的点”。

这个判断非常重要，因为它告诉我们：skill 不该是百科全书，而应该像一份“失败经验压缩包”。谁能把常见失败模式总结清楚，谁的 skill 就更实用。

3. 善用文件系统和渐进式披露

skill 是目录而不是单文件，这意味着可以把不同粒度的信息拆开存放：

• references/ 放 API 说明和详细签名
• assets/ 放模板
• scripts/ 放可复用脚本
• examples/ 放参考样例

这样做的好处是，agent 不必一上来就加载全部上下文，而是在任务推进过程中逐步读取所需内容。对长任务和复杂任务来说，这种设计比单纯堆 prompt 更稳。

4. 不要把模型“钉死”在一条路径上

原文提醒要避免 railroading。也就是说，skill 要给模型足够的信息，但不要把每一步都写死。

因为 skill 是高度可复用的，如果说明写得太具体，它在一个场景下可能很好，但换个任务就会显得僵硬。一个好的 skill 应该既提供方向，也保留适配空间。

5. 把配置问题设计好

有些 skill 在真正使用前需要补充上下文，比如 Slack 发到哪个频道、使用哪个 dashboard、写入哪个环境。这类信息不应该每次都重新解释，最佳做法是通过配置文件保存下来；如果没有配置，再由 agent 向用户询问。

这说明 skill 不是一次性文本，而是有“运行前准备”概念的。

6. 描述字段不是简介，而是“触发条件”

这是一个很容易被忽视、但极其关键的细节。

当 Claude Code 启动时，它会先看到所有 skill 的名称和 description，然后决定当前任务是否该调用某个 skill。所以 description 的职责不是对外宣传，而是准确描述“什么情况下应该触发我”。

如果 description 写得模糊，再好的 skill 也可能因为触发不上而失去价值。

7. 给模型脚本，比给模型长篇解释更有用

原文强调的一点我非常认同：你能给 agent 的最强工具之一就是代码本身。

如果 skill 里已经放好了常用脚本、辅助函数和模板，模型就不必把轮子反复重造，而可以把精力放在组合和决策上。这会显著提升复杂任务的成功率，也能减少样板代码带来的偏差。

Skill 不只是个人效率工具，还是团队知识分发机制

文章最后讨论了一个更偏组织层面的命题：这些 skill 该如何分发？

作者给了两种方式：

• 放进代码仓库，作为项目级 skill
• 做成 plugin，通过 marketplace 分发和安装

小团队、仓库不多时，把 skill 放在 repo 里通常更直接；但随着规模增大，skill 数量会迅速膨胀，它们会逐渐变成额外上下文负担。这时，引入插件市场，让团队按需安装 skill，会更合理。

这里面其实有一个很现实的管理问题：坏 skill 和重复 skill 非常容易产生。 所以在分发之前，必须有一定的筛选和治理机制。

原文还提到一个很实用的思路，就是通过 hook 记录 skill 的实际使用情况，观察哪些 skill 很受欢迎、哪些 skill 明明应该被调用却经常“触发不足”。这说明 skill 不只是要“被写出来”，还要被持续度量。

我的理解：Skill 本质上是在做“组织经验的软件化”

如果把整篇文章压缩成更抽象的一层，我会认为它讲的是一件更大的事：

skill 的意义，不在于给模型增加一段提示词，而在于把组织里的隐性经验转译成 agent 可以稳定复用的执行单元。

这些经验以前可能散落在：

• 资深工程师的口头提醒里
• 某个 Wiki 页面里
• 某个脚本仓库里
• 某次事故复盘里
• 某个团队默认但没人写清楚的流程里

而 skill 的价值，就是把这些东西重新组织成 agent 可以在正确时机调用的结构化能力。

从这个角度看，skill 更像是：

• 提示词的升级版
• 工作流的轻量封装
• 团队知识的可执行接口
• Agent 时代的新型工程资产

结语

这篇文章最打动我的一点，是它没有把 skill 神化成某种复杂框架，而是把它还原成一种可以从小处开始、在使用中迭代完善的实践。

很多好 skill 的起点并不宏大，可能只是几行说明和一个 gotcha。但只要它解决的是高频问题、能在真实任务中被反复调用，它就会不断积累价值。

所以，与其把 skill 看成“写给模型看的说明书”，不如把它看成一个持续生长的能力包。真正优秀的 skill，最终沉淀下来的不是文字，而是组织对任务、错误、流程和最佳实践的系统理解。

---

原文：Lessons from Building Claude Code: How We Use Skills