摘要

Anthropic 在《Lessons from building Claude Code: how we use Skills》里分享了一个很重要的实践信号：

Skill 正在成为 Claude Code 最重要的扩展点之一。

它不是一段更长的提示词，也不是一个 Markdown 文件，而是一个 Agent 可以主动发现、读取、执行和组合的能力包。

如果说 Prompt 解决的是“这一次怎么说清楚”，那么 Skill 解决的是：

团队反复遇到的这类任务，以后应该怎样稳定完成。

Claude Code Skills 把团队经验、脚本、参考资料、验证方法和 Gotchas 封装成 Agent 可以调用的能力包。

Skill 的价值不是让上下文更长，而是让团队经验变成可调用、可验证、可迭代的能力。

这篇 Playbook 不是对原文逐字翻译，而是把 Anthropic 的经验转成 ReelOS.ai 更适合使用的中文实操框架。

01. 先重新定义 Skill

很多团队第一次接触 Skill，会把它理解成：

一个专门给 Agent 看的说明文档。

这个理解还不够。

更准确地说，Skill 是一个小型能力目录，里面可以包含：

  • 触发说明
  • SKILL.md
  • 参考文档
  • 示例代码
  • 脚本
  • 模板
  • 配置
  • 资产文件
  • 历史记录
  • Hooks

一个有效 Skill 通常不只是 SKILL.md，而是由 instructions、references、scripts、assets、config 和 hooks 构成。

把 Skill 当成一个文件夹，而不是一段提示词。文件系统本身就是 Context Engineering。

一个好的 Skill，会让 Agent 在遇到某类任务时知道：

  • 什么时候应该调用它
  • 先读哪些文件
  • 用哪些脚本
  • 哪些坑不能踩
  • 怎么验证结果
  • 什么情况需要问人
  • 哪些动作必须加保护

所以 Skill 的本质不是“知识总结”，而是：

把团队知道但模型默认不知道的经验，封装成 Agent 可执行的操作接口。

02. 什么时候值得写 Skill？

不要为了写 Skill 而写 Skill。

一个任务值得做成 Skill，通常满足至少一个条件：

  1. 团队经常重复做
  2. Agent 经常在这里犯错
  3. 任务依赖内部库、CLI、API、数据表或监控系统
  4. 有固定 SOP，但 SOP 没有进入 Agent 上下文
  5. 输出质量必须验证，不能只靠模型自信
  6. 操作有风险，需要 Guardrails
  7. 任务会跨多个工具、文件和系统
  8. 结果需要长期沉淀，下一次执行要参考历史

值得写成 Skill 的任务通常兼具高频、易错、依赖内部上下文、需要验证和可复用。

高价值 Skill 往往来自团队的真实摩擦，而不是自上而下规划出来的宏大目录。

一句话判断：

如果一个老员工知道怎么做，但 Agent 每次都要重新猜，就值得写成 Skill。

03. Anthropic 总结的 9 类 Skill

Anthropic 把内部大量 Skill 归纳成 9 类。这个分类非常适合团队做 Skill Library 的第一版盘点。

团队 Skill Library 可以从九类高价值场景开始：库/API、验证、数据、自动化、脚手架、代码质量、CI/CD、Runbook 和基础设施。

不是所有 Skill 都同等重要。对生产质量影响最大的，通常是 Verification、Runbook、Deployment 和 Code Review。

1. Library / API Reference

用于告诉 Agent 内部库、CLI、SDK、API 应该怎么用。

适合沉淀：

  • 内部库的正确调用方式
  • 参数和返回值约定
  • 常见误用
  • 代码片段
  • 废弃接口
  • 环境和网络限制

如果没有这类 Skill，Agent 很容易凭常识猜内部系统，最后写出“看起来合理、实际上跑不通”的代码。

2. Product Verification

这是最该优先建设的 Skill 类型。

它解决的问题不是“能不能生成代码”，而是：

生成之后怎么证明它真的能工作。

适合沉淀：

  • Playwright 验证
  • 注册/登录/支付流程测试
  • CLI 交互测试
  • 状态断言
  • 录屏或截图
  • Smoke Test
  • 失败时的诊断路径

对 AI Coding 来说，Verification Skill 是从 Demo 走向生产的分水岭。

3. Data Fetching / Analysis

用于把数据表、指标口径、Dashboard、日志系统、监控系统交给 Agent。

适合场景：

  • 查漏斗
  • 看留存
  • 分析异常
  • 对比 Cohort
  • 找 Trace / Request ID
  • 读取 Grafana / Datadog / 内部 BI

这类 Skill 会让 Agent 从“回答问题”升级成“调查问题”。

4. Business Process / Team Automation

用于封装团队重复流程。

比如：

  • 站会更新
  • 周报
  • Ticket 创建
  • Slack 通知
  • 发布总结
  • PR 活动汇总

如果这类 Skill 还能保存上一次执行结果，它就不只是自动化工具，而是一个轻量团队记忆。

5. Code Scaffolding / Templates

用于生成符合团队规范的代码骨架。

比如：

  • 新建服务
  • 新建 Workflow
  • 新建 Migration
  • 新建内部 App
  • 生成带日志、鉴权、部署配置的模板

它适合那些“靠脚手架不够、还需要自然语言判断”的场景。

6. Code Quality / Review

用于把团队代码质量标准交给 Agent。

可以包括：

  • Review 清单
  • 测试策略
  • 风格约束
  • 安全检查
  • 子 Agent 复审
  • 自动修复循环

高质量 Review Skill 不只是“挑问题”，而是让 Agent 知道什么是这个团队里的“好代码”。

7. CI/CD / Deployment

用于帮助 Agent 看 CI、修 CI、部署、回滚和发布。

适合沉淀：

  • 失败日志怎么读
  • flaky test 怎么处理
  • 哪些服务怎么部署
  • 灰度发布流程
  • 错误率对比
  • 自动回滚规则
  • 生产发布禁忌

这类 Skill 尤其需要 Guardrails，因为它可能触达生产系统。

8. Runbooks

Runbook Skill 从一个症状出发，带 Agent 走完整调查路径。

比如：

  • 某服务延迟升高
  • 某条 Slack 报警
  • 某个错误码激增
  • 某个请求 ID 失败
  • 某个用户状态异常

一个好的 Runbook Skill 应该产出结构化报告，而不是只输出一堆日志。

9. Infrastructure Operations

用于处理基础设施维护和高风险操作。

比如：

  • 清理孤儿资源
  • 成本异常调查
  • 依赖升级
  • 权限审批
  • 存储/网络/集群问题

这类 Skill 的重点是：流程、确认、审计和保护，而不是让 Agent “更大胆”。

04. 写 Skill 的关键不是写更多，而是写更有信号

Anthropic 的一个重要提醒是：不要在 Skill 里写模型本来就知道的东西。

Claude 已经会写代码，也能读代码库。低价值 Skill 通常只是重复常识：

请写清晰代码。
请注意边界情况。
请运行测试。

这类内容会增加上下文负担，但不会增加能力。

高价值 Skill 应该写的是模型默认不知道的东西：

  • 内部系统的特殊规则
  • 团队真实踩过的坑
  • 业务口径
  • 环境差异
  • 不符合直觉的字段
  • 验证结果的真实来源
  • 什么时候不要自动行动

好的 Skill 不重复常识，而是把模型默认不知道的团队经验、边界条件和失败案例放进去。

Gotchas 是 Skill 里信号密度最高的部分。它应该从真实失败中持续长出来。

最值得专门维护的是 Gotchas。

例如：

  • 某张表是 append-only，不能按最新创建时间取
  • API Gateway 叫 request_id，Billing 里叫 trace_id，但它们其实是同一个值
  • Staging 返回 200 不代表 webhook 真处理成功，真实状态要看事件表
  • 某个 CLI 默认连生产环境，必须显式指定 staging
  • 某个测试必须在带 TTY 的终端里跑

这些才是团队经验。

05. 用渐进式披露管理上下文

Skill 不应该把所有内容塞进 SKILL.md。

更好的方式是：

SKILL.md
  说明什么时候用这个 Skill
  告诉 Agent 任务流程
  指向必要参考文件

references/
  API 细节
  表结构
  口径说明
  常见错误

scripts/
  可执行脚本
  验证工具
  查询工具

assets/
  模板
  示例输出
  报告格式

config.json
  团队或用户配置

Skill 应该通过文件系统进行渐进式披露：主说明保持短，细节放到 references、scripts、assets 和 config。

让 Agent 在需要时再读细节，而不是一开始就吞下所有上下文。

SKILL.md 的任务不是承载全部知识，而是做路由：

  • 任务是什么
  • 什么时候触发
  • 先读什么
  • 哪些情况读哪个文件
  • 用哪个脚本验证
  • 输出格式是什么

这样 Skill 才能保持清晰，也不会把每次会话都拖得很重。

06. 把确定性部分交给脚本

Skill 里最有价值的资产之一是脚本。

原因很简单：

模型适合判断、组合和解释；脚本适合执行、查询和验证。

如果每次都让 Agent 重新写数据库查询、重新拼 API 请求、重新搭测试流程，它就会在低价值步骤上消耗上下文，还会增加错误率。

更好的做法是把稳定动作做成脚本：

  • 拉取数据
  • 跑验证
  • 生成报告
  • 检查状态
  • 格式化输出
  • 查询日志
  • 对比指标
  • 驱动浏览器

把确定性动作交给 scripts，让 Agent 负责组合、判断、解释和下一步决策。

代码是给 Agent 最强的工具之一。脚本越稳定，Agent 越能把精力放在决策上。

一个成熟 Skill 的目标不是让 Agent “每次都更聪明”，而是让它少做不稳定的事。

07. 描述字段要写给模型，不是写给人

很多团队会把 Skill 描述写成营销文案：

帮助团队提升工程效率的综合性工具。

这对模型没什么用。

因为 Claude Code 在启动时会扫描可用 Skill 的描述，用它来判断“当前请求是否应该触发这个 Skill”。

所以描述字段应该写成触发条件：

Use when debugging checkout payment failures, Stripe webhook status, invoice mismatch, or payment_events inconsistencies.

也就是说，Skill 描述不是摘要，而是路由规则。

一个好描述应该包含：

  • 适用任务
  • 触发词
  • 输入类型
  • 不适用边界
  • 关键系统名

08. Skill 要能分发、组合和度量

当 Skill 变多以后，真正的问题会从“怎么写”变成“怎么治理”。

小团队可以把 Skill 直接放在仓库里，例如 .claude/skills。

这样最简单，也最贴近项目上下文。

但随着组织变大，Skill 会遇到三个问题：

  1. 每个仓库都放 Skill，会增加上下文负担
  2. 很多 Skill 只对部分团队有用
  3. 好 Skill 很难被发现和复用

这时就需要内部 Skill Marketplace 或 Plugin 机制。

Anthropic 的经验是，不一定要一开始就建立中央审核团队。更自然的方式是：

  • 先让个人或团队在 sandbox 里分享
  • 通过 Slack、GitHub、内部论坛获得使用反馈
  • 有真实 traction 后再进入正式市场
  • 让使用者自行安装需要的 Skill
  • 用日志观察哪些 Skill 触发过少或过多

Skill Library 的成熟路径：个人经验、团队试用、市场分发、组合调用、使用度量和持续迭代。

Skill Library 不该一次性设计完，而应该像产品一样被使用、度量和迭代。

组合也很重要。

例如：

  • CSV 生成 Skill 可以调用文件上传 Skill
  • CI 修复 Skill 可以调用代码审查 Skill
  • Runbook Skill 可以调用数据分析 Skill
  • 发布 Skill 可以调用 smoke test Skill

即使平台没有完整依赖管理，也可以在 Skill 说明里明确引用其他 Skill，让模型在已安装时自动组合。

09. ReelOS.ai 建议的 Skill 写作模板

可以从这个模板开始：

# Skill Name

## When to use
- 当前请求满足什么条件时使用
- 触发词是什么
- 不适用什么情况

## Goal
- 这个 Skill 要稳定完成什么结果

## Inputs
- 需要用户或环境提供什么信息

## Workflow
1. 先确认上下文
2. 读取必要 references
3. 执行 scripts
4. 生成结果
5. 验证结果
6. 输出报告

## Gotchas
- 常见失败
- 内部系统特殊规则
- 不能靠直觉猜的地方

## Verification
- 怎样证明完成
- 哪些状态必须检查
- 哪些测试必须跑

## Guardrails
- 哪些动作需要确认
- 哪些命令禁止自动执行
- 哪些环境不能触碰

## Output
- 最终交付物格式

这个模板不追求复杂，而是保证一个 Skill 至少回答四个问题：

什么时候用？ 怎么做？ 怎么避免坑？ 怎么证明完成？

10. 最小可行 Skill Library

如果一个团队刚开始建设 Skill Library，不建议一口气做几十个。

更好的第一阶段是 5 个：

  1. Code Review Skill：把团队代码审查标准沉淀下来
  2. Product Verification Skill：让 Agent 做完以后必须验证
  3. Runbook Skill：让 Agent 会调查线上问题
  4. Internal API Skill：让 Agent 正确使用内部库和 CLI
  5. Deployment Skill：让 Agent 理解发布、回滚和风险边界

这 5 个 Skill 能覆盖从开发、验证、排障到上线的核心路径。

等这些 Skill 被真实使用、修过几轮 Gotchas，再扩展到数据分析、业务自动化、脚手架和基础设施。

最终判断

Skill 的真正价值，不是让 Agent 读到更多文字，而是让团队经验进入 Agent 的执行回路。

它把分散在老员工脑子里、Slack 里、Wiki 里、脚本里、PR 评论里和事故复盘里的知识，压缩成 Agent 可以主动调用的能力模块。

所以，Agent 时代的团队知识管理会从：

人读文档，再手动执行

变成：

Agent 调用 Skill，按团队方式执行，并持续把失败沉淀回 Skill

一句话：

Skill 不是提示词资产，而是团队经验的运行时接口。

参考来源

本文基于 Anthropic Claude Code 团队文章整理、翻译与再结构化：