Agent Skill 从使用到原理

#AI #Agent #Skills #OpenAI #Claude 共 3,059 字 约 7 分钟

Skill 不是“更长的 Prompt”，也不是又一个模型能力名词。更准确地说，它是一种把可重复工作流、领域知识、脚本和资源打包起来的文件夹规范。Agent 平时只看到这批能力的目录，需要时再展开细节。

0. 文章地图

这篇按“用法 → 结构 → 原理”排：

#问题回答
1Skill 是什么一个带入口说明的能力文件夹
2怎么使用可以显式调用，也可以由 Agent 自动选择
3放在哪里不同宿主有不同扫描路径
4为什么能省上下文靠渐进披露：先索引，再展开
5和 Agent Loop 什么关系它是运行时上下文，不是训练参数
6和 MCP / Subagent / Tool 什么关系它负责流程，不负责替代工具和执行隔离
7怎么写触发条件、执行路径、自由度要分清
8风险在哪里Skill 能带指令和代码，所以必须审查来源

1. Skill 是什么

我现在更愿意把 Skill 理解成 Agent 的能力包。

它的最小形态不是一个 API，也不是一个提示词片段，而是一个目录。目录里必须有一个 SKILL.md，这个文件负责两件事：

  1. 告诉 Agent：这个 Skill 叫什么，什么时候该用。
  2. 告诉 Agent：一旦决定使用，接下来应该怎么做。

旁边还可以放 scripts/、references/、assets/。这几个目录不是强制的，但它们决定了 Skill 和普通 Prompt 的差异：Prompt 只能写说明，Skill 可以连同脚本、模板、参考资料一起交给 Agent。

一个典型结构长这样：

my-skill/
├── SKILL.md
├── scripts/
├── references/
└── assets/

其中最关键的是 SKILL.md frontmatter 里的 description。它不是写给人看的简介，而是写给 Agent 做路由判断的触发条件。

错误写法：

description: 用于分析营销数据

更好的写法：

description: 当用户提供 CSV 格式的营销活动数据，并要求分析漏斗、ROAS、CPA 或预算分配建议时使用。

前者只说“它是什么”，后者才说“什么时候该用它”。Skill 能不能被正确触发，主要看这里。

2. 怎么使用

从使用者角度看，Skill 有两种入口。

第一种是显式调用。比如在支持 Skill 的环境里，用命令、选择器或斜杠命令直接点名一个 Skill。Claude Code 里常见的形态是 /skill-name，Codex 里则有自己的命令和选择器入口。

第二种是自动触发。Agent 会先看到所有可用 Skill 的 name 和 description，再根据当前任务判断是否需要加载某个 Skill。用户并不一定要说“使用某某 Skill”，只要任务语义匹配，它就可能被激活。

这也是为什么 description 要写成触发条件，而不是产品介绍。

3. 目录结构与加载位置

Skill 的目录格式在走向统一，但不同宿主的“去哪找 Skill”仍然不一样。

在 Codex 体系里，仓库级 Skill 通常放在 .agents/skills。Codex 会从当前工作目录向上扫描，直到 repo root。除此之外，还有用户级、管理员级和系统级位置。

在 Claude Code 体系里，常见路径是：

  • 个人 Skill：~/.claude/skills/<skill-name>/SKILL.md
  • 项目 Skill：.claude/skills/<skill-name>/SKILL.md
  • 插件 Skill：<plugin>/skills/<skill-name>/SKILL.md

这件事有个实际影响：Skill 不是只属于“全局助手”的东西。它可以跟着项目走，也可以跟着团队工作流走。一个 repo 可以把自己的发布流程、测试策略、文档风格写成 Skill，Agent 进入这个项目时自然获得这部分能力。

4. 为什么要渐进披露

Skill 最重要的设计不是“能放很多文件”，而是 渐进披露。

如果一个 Agent 装了几十个甚至上百个 Skill，每次对话都把所有 SKILL.md 全文塞进上下文，窗口会很快被吃光。Skill 的做法是三层加载：

层级加载内容何时加载作用
L1name + description会话开始或能力索引阶段让 Agent 知道有哪些能力
L2完整 SKILL.md判断某个 Skill 相关时读取具体执行说明
L3scripts/、references/、assets/执行过程中按需读取获取脚本、模板、长文档、素材

这个结构解决的是上下文预算问题。

description 是索引，SKILL.md 是操作手册，references/ 和 scripts/ 是仓库。Agent 先看索引，确认相关后再打开手册，真正执行时才去翻仓库里的细节。

这也是 Skill 和“把一大段 Prompt 粘进去”的本质区别：Prompt 是一次性注入，Skill 是按需展开。

5. 它和 Agent Loop 的关系

要理解 Skill 的位置，需要先看 Agent Loop。

一个典型 Agent 回合大致是：

  1. 系统把用户输入、项目说明、权限边界、可用工具、可用 Skill 信息组织成模型输入。
  2. 模型决定直接回答，或者请求调用某个工具。
  3. Agent 执行工具，把结果追加回上下文。
  4. 模型继续判断下一步，直到任务完成。

Skill 进入的是第 1 步和后续执行过程。它不是训练数据，不会改变模型参数；它是在运行时被放进上下文里的工作流说明，以及按需可读取的文件资源。

因此，Skill 更像“给 Agent 临时装上的操作规程”，不是“把模型永久训练成某个专家”。

6. 它和 MCP / Subagent / Tool 的边界

这一层很容易混在一起，但它们其实解决的是不同问题。

概念解决什么形态
Tool单次原子能力API / 函数
MCP外部数据和服务接入长连接协议
Skill工作流 + 领域知识文件夹
Subagent隔离的执行上下文独立 Agent 实例

我的理解是：

  • Tool 和 MCP 是“能力供给”
  • Skill 是“怎么做事”
  • Subagent 是“把某段活单独派出去做”

所以 Skill 不该被写成一个个工具清单。真正合理的写法是：Skill 定义流程、边界和输出标准，工具和数据源交给它调用。

举个简单例子：

  • Skill 负责定义客户反馈分类规则、洞察输出格式
  • MCP 负责接入原始访谈、问卷或文档系统
  • Subagent 负责并行分析不同数据集
  • Tool 负责文件读写、代码执行这类原子动作

这也是为什么 Skill 的 scripts/ 不是 Tool 定义。它们只是这个工作流里按需调用的小工具。

7. 写 Skill 时，我会看的几个约束

我会按这几条判断一个 Skill 写得好不好：

  1. description 写的是触发条件，不是宣传文案。
  2. SKILL.md 只放执行路径，长知识拆到 references/。
  3. 确定性、重复性、容易出错的机械步骤交给 scripts/。
  4. 目录结构保持浅，不要让 Agent 层层找文件。
  5. 对外部系统、密钥、部署、删除操作保持显式确认。

再往前一步，可以把 Skill 的自由度分成三档：

  • 高自由度：目标明确，但方法开放，适合创意类任务。
  • 中自由度：有推荐模式，但允许偏离，适合半结构化任务。
  • 低自由度：步骤固定，必须按流程跑，适合生产型工作流。

我更喜欢把 Skill 写成一份“小而准的操作手册”：

  • 入口清楚
  • 步骤稳定
  • 必要资料都在旁边
  • 该固定的地方固定，别让 Agent 自由发挥到跑偏

8. 安全边界

Skill 的能力强，风险也来自同一个地方：它可以带指令、文件和代码。

一个不可信的 Skill 可能在说明里诱导 Agent 做错误操作，也可能在脚本里连接外部网络、读取敏感文件或执行不该执行的命令。即使宿主有扫描和权限控制，也不能替代人工审查。

我会把 Skill 当成“可执行的项目依赖”来看待，而不是普通 Markdown：

  1. 先读 SKILL.md。
  2. 再看 scripts/ 里有没有实际代码。
  3. 检查是否有网络访问、文件写入、密钥读取、部署发布等行为。
  4. 对高风险 Skill 保持人工确认，不让它静默执行。

9. 结论

Agent Skill 的关键价值不是“多写了一份提示词”，而是把可复用经验变成一个稳定的、可发现的、可分发的能力包。

它同时服务三件事：

  1. 对用户：少重复解释同一套流程。
  2. 对 Agent：先看到能力索引，再按需加载细节。
  3. 对组织：把团队规范、业务流程、模板和脚本沉淀成文件资产。

所以我对 Skill 的一句话总结是：

Skill 是 Agent 时代的工作流包。它把“知道怎么做”从一次性对话里拿出来，放进一个可复用、可审查、可迭代的目录里。

如果再压缩一点，我会说它做了三件事：

  1. 把经验从口头提示变成文件资产。
  2. 把上下文从一次性注入变成渐进加载。
  3. 把工作流从临场发挥变成可重复执行。

参考