Skill 把「完成某类任务该按什么流程、遵守什么约束、参考什么资料」打包成一个可被 Agent 发现、按需加载的能力单元。本文讲清它与 Prompt、Tool、MCP 的职责边界，SKILL.md 的组织方式与发现加载机制，以及渐进式披露如何用最少上下文换取最大能力覆盖。

它解决什么问题

假设你要让 Agent 做代码审查：检查维度、项目约定、输出模板、参考资料，一次会话里临时粘贴还能应付，换个会话又得重贴一遍。如果干脆把所有 SOP 全局塞入系统提示，又会撞上另外两堵墙：上下文窗口有限，塞得越多，每条规则被遵守的概率越低；无关内容还会稀释注意力，模型对夹在长文中间的关键句容易「看漏」。

Skill 解决的正是这组矛盾：让每类任务的领域知识按需出现——不命中时只占一行元数据的上下文，命中时才加载完整说明。它本质上是把隐性的团队经验显性化、文件化、可版本化，同时把上下文成本从「常驻」变为「按次付费」。

核心原理

Skill 是什么：指令 + 资源 + 脚本

一个 Skill 的最小形态是一个目录加一个主文件（通常叫 SKILL.md），复杂场景下会附带脚本与参考资料：

reviewing-code/
├── SKILL.md          # 主文件：元数据 + 流程与约束，命中时加载
├── scripts/          # 可执行脚本：运行即可，源码不进上下文
├── references/       # 参考资料：按需读取
└── assets/           # 模板等静态资源：按需使用

SKILL.md 分两段：开头是 YAML 元数据（name 与 description），回答「我是谁、什么时候该用我」；正文写具体流程、硬约束、失败处理与验收清单，回答「怎么做」。因此 Skill 的完整定义是：指令（主文件正文）+ 资源（references/assets）+ 脚本（scripts）的封装，三者共用同一个触发入口。

与 Tool 的关系：使用手册与能力接口

Tool（工具）是能力接口，告诉 Agent「你能执行什么动作」；Skill 是使用手册，告诉 Agent「这类任务该何时动手、按什么顺序、检查什么、何时停下」。两者是互补而非替代：一个数据库迁移 Skill 会规定命令、校验步骤与回滚条件，但真正执行命令仍靠 Shell 工具。也有的 Skill 不带任何工具——纯审查类 Skill 只约束分析框架与输出格式，同样成立。

放进同一条执行链路看四个概念的分工：用户说的话是 Prompt；模型输出结构化调用意图靠 Function Calling；工具由远端标准协议提供时走 MCP；而「先确认字段含义、再查异常值、最后给业务结论」这类流程知识，属于 Skill。

深入机制

发现与加载：两段式按需注入

Skill 的运行时机制可以概括为「常驻元数据，延迟加载正文」：

  1. 启动阶段，宿主只把每个 Skill 的 name 和 description 放进上下文，成本极小；
  2. 模型判断当前任务命中某个 Skill（或用户显式调用）；
  3. 宿主读取完整 SKILL.md 注入上下文；
  4. 正文里引用的 references/、scripts/ 在执行到对应步骤时才读取或运行。

这意味着 description 是路由的唯一依据，写法直接决定 Skill 能否在该触发时被触发。好的描述要说清两件事：这个 Skill 做什么、在什么场景下用，最好带上用户可能说出的触发词：

# 好：能力 + 场景 + 触发词
description: 从 PDF 提取文本与表格、填充表单。处理 PDF 文件或用户提到 PDF、表单、文档提取时使用。

# 差：只写能力，没写何时用
description: 处理 PDF 文件

渐进式披露：三层信息结构

渐进式披露（Progressive Disclosure）是 Skill 省上下文的核心设计，把信息按使用时机分三层：

  1. 广告层：元数据常驻，几十个 Skill 也只占几百 token，让模型「知道有这个东西」；
  2. 指令层：命中后才加载主文件正文，因此正文要克制——社区实践建议控制在几百行内，只放主流程与硬约束；
  3. 资源层：正文用指针代替全文，例如「需要做 SOLID 设计检查时，读取 references/solid-checklist.md」，不涉及的检查项永远不占用上下文。

这套设计对抗的是「上下文腐化」：窗口装得多不代表模型用得好，关键规则埋在海量资料中间反而更容易被忽略。Skill 不该写成资料库，而该写成「目录 + 按需翻页」。

自由度的分级控制

不同风险的任务，Skill 的写法应该不同：

  • 低风险高自由（代码审查、方案评估）：只固定检查维度与输出格式，具体判断留给模型；
  • 中风险（有固定模板但允许调整）：给模板、参数边界与示例；
  • 高风险低自由（数据库迁移、生产部署、删文件）：写死命令、参数、校验与回滚条件，并明确「命令失败即停止并上报」。

判断原则很简单：出错代价越高、可逆性越差，自由度越低。

工程实践

  • 用脚本做确定性工作：格式转换、批量处理、精确计算交给 scripts/ 里的程序，LLM 只负责判断与编排；脚本错误信息要可操作（缺文件就明说缺哪个），不能只抛底层异常让模型猜。
  • 给默认路径而非罗列选项：「默认用 pdfplumber，扫描版再切 OCR」远好于平铺四个库让模型每次重新选。
  • 版本化与评测：Skill 进 Git，用任务成功率 × 触发率的交叉表验证价值；从未成功触发过的 Skill 要么改写 description，要么删除。
  • 定期精简：Skill 越多路由越难，低频、职责重叠的要及时清理，别让 Skill 库变成第二个混乱的 Prompt 堆。

对比与权衡

维度 Prompt Skill Tool / Function Calling MCP
本质 一次性指令 可复用的任务知识包 可执行的能力接口 工具接入的标准协议
加载时机 每轮手写 命中时按需加载 模型决策调用时 连接后发现与调用
提供方 用户/开发者 团队沉淀、版本化 Server/宿主 远端 MCP Server
适用 临时、单次任务 重复出现的任务模式 读写外部世界 跨宿主复用工具

面试视角

Skill 和 Tool 有什么区别？ Tool 是能力接口，解决「能做什么」；Skill 是任务知识，解决「该怎么做」。Skill 可以引用若干工具，也可以完全不依赖工具（如纯审查规范）。判断标准：删掉它之后，Agent 是失去了一种能力，还是失去了做一类事的方法论——前者是 Tool，后者是 Skill。

渐进式披露为什么能省上下文？ 它把信息分三层：元数据常驻做路由、正文命中才加载、细节资料执行到才读取。不相关任务的 Skill 全文永远不进入上下文，从而把成本从「全量常驻」变成「按次加载」，同时避免长上下文带来的注意力稀释。

怎么保证 Skill 被正确触发？ 关键在于 description：同时包含能力描述、适用场景和用户可能的触发词。Skill 数量多时可以引入独立路由：用名称、描述、典型 query 样本做向量粗召回，再精排加阈值，低于阈值宁可不加载走默认流程。

哪些内容不该写进 Skill？ 三类：通用常识（模型本来就会）、格式化工具能强制执行的规则（交给 linter）、大段参考资料（放 references/ 按需读）。每条规则都应能通过「删掉它错误会不会复现」的检验。

Skill 多了怎么治理？ 按问题边界拆分而非追求大而全；统一进 Git 版本化；监控误触发率与任务成功率；定期精简低频与重叠的 Skill。路由空间越大，误触发概率越高，克制本身就是质量手段。

小结

  1. Skill 是「指令 + 资源 + 脚本」的能力封装，与 Tool 是手册和接口的互补关系，与 Prompt、MCP 各居链路不同位置。
  2. description 决定路由质量，必须同时写清能力与触发场景。
  3. 渐进式披露用三层结构把上下文成本按需化，是 Skill 区别于「全局长 Prompt」的根本设计。
  4. 工程上把 Skill 当 API 文档维护：精悍、可测、版本化、可精简。