跳到主要内容

Agent Skills — 架构与原理

30 秒导读: Agent Skills 是一个开放格式——一个文件夹里放一个 SKILL.md(YAML 头 + Markdown 正文),就能给任意兼容的 AI agent 加一项“专长 + 操作手册”。它的核心不是某个运行时,而是一份约定:格式长什么样、agent 该怎么“按需”分三层加载它。这样同一个 skill 可以在 Claude Code、OpenAI Codex、VS Code Copilot 等众多客户端之间通用。

1. 这是什么(零基础也能懂)​

一句话定义: Agent Skills 是“给 AI agent 装外挂能力”的标准文件格式——把某类任务的专业知识、步骤、脚本打包成一个文件夹,agent 在需要时才把它读进上下文。

它解决谁的什么问题。 现在的大模型很聪明,但常常缺具体语境:

  • 它不知道你们公司那张 users 表用的是软删除,查询忘了加 WHERE deleted_at IS NULL 就会把停用账号也算进来;
  • 它不知道你们团队填 PDF 表单要先跑哪个校验脚本;
  • 它不知道某个冷门 API 的调用约定。

这些“agent 自己学不到、得有人告诉它”的知识,就被打包成一个 skill。

它能做什么:

  • 把领域专长(法务审查流程、数据管线、报表格式)写成可复用的指令 + 资源。
  • 把多步工作流固化成一致、可审计的流程。
  • 一次编写,跨产品复用——任何兼容 Skills 的 agent 都能用同一个 skill。

用起来什么样。 一个最小的 skill 就是一个文件夹 + 一个文件(README.md:13-20):

my-skill/
├── SKILL.md          # 必需:元数据 + 指令
├── scripts/          # 可选:可执行代码
├── references/       # 可选:参考文档
├── assets/           # 可选:模板、资源
└── ...               # 任意其他文件/目录

SKILL.md 本身长这样(最小形态只需要 name + description):

---
name: roll-dice
description: Roll dice using a random number generator. Use when asked to roll a die (d6, d20, etc.), roll dice, or generate a random dice roll.
---

To roll a die, run a command that generates a random number from 1 to the
number of sides:

    echo $((RANDOM % <sides> + 1))

这个例子取自官方 quickstart(docs/skill-creation/quickstart.mdx:21-34)。

一句话直觉/类比。 把 skill 想成一本工具书摆在书架上:agent 平时只看书脊(名字 + 一句话简介);遇到对得上的任务,才抽出那本书翻开正文(完整指令);正文里提到“详见附录 B”,才去翻附录(脚本/参考文件)。这套“先看书脊、按需翻页”的机制就叫渐进式披露(progressive disclosure)——本库的灵魂。

2. 顶层全景(它大概怎么转)​

这个仓库其实是三件东西合在一起,围绕同一个格式:

部件干什么在哪
格式规范(spec)用文字定义 SKILL.md 的目录结构、frontmatter 字段、渐进式披露分层docs/specification.mdx
参考库 skills-ref一个小 Python 库 + CLI:解析、校验 skill,生成喂给模型的 promptskills-ref/src/skills_ref/
集成 / 创作指南教 agent 厂商怎么支持 Skills、教用户怎么写好 skilldocs/client-implementation/、docs/skill-creation/

注意:这个仓库里没有“运行 skill 的引擎”。 规范只管“文件长什么样、该怎么分层加载”;真正去扫描、激活、把内容塞进模型上下文的,是各个 agent 客户端(Claude Code、Codex…)。本仓库的 skills-ref 只是给客户端开发者看的示范实现,README 明确写了“仅供演示、勿用于生产”(skills-ref/README.md:5-6)。

一张图:skill 从“躺在磁盘上”到“被 agent 用上”的全景(从左到右是时间顺序,渐进式披露的三层用 ① ② ③ 标出):

  磁盘上的 skill 文件夹                  agent 客户端(本仓库不实现,只给规范)        模型上下文
  ┌────────────────────┐
  │ my-skill/          │   ① 发现/披露      ┌───────────────────────┐
  │   SKILL.md  ───────┼──── 读 name+desc ─▶│ 扫描各 skills 目录     │── name+desc ─▶ <available_skills>
  │   scripts/         │                    │ (skills-ref: parser)  │   (~50-100 tokens/个)
  │   references/      │                    └───────────┬───────────┘
  │   assets/          │                                ② 激活│ 任务匹配上某条 description
  └────────────────────┘                                      ▼
                            读整个 SKILL.md 正文 ─────────▶ 完整指令进上下文 (<5000 tokens)
                                                            │
                            ③ 执行:正文说“跑 scripts/x”────┘
                                按需再读 scripts/ references/ ─▶ 资源进上下文 (按需)

主线走一遍(高层):

  1. 发现 + 披露(tier 1)。 agent 启动时扫描若干 skills 目录,只读每个 skill 的 name + description,拼成一个目录清单(常用 <available_skills> XML)塞进系统提示。代价极小,几十个 skill 也才几千 token。
  2. 激活(tier 2)。 当用户的任务和某条 description 对上了,agent 把那个 SKILL.md 的完整正文读进上下文,开始照着做。
  3. 执行(tier 3)。 正文若指示“运行 scripts/extract.py”或“读 references/api.md”,agent 这时才按需加载那些文件。

核心收益:基础上下文一直很小,专长只在真正用到时才占地方。

3. 阅读地图(建议顺序)​

按“由浅入深”读:

  1. 01-spec-format.md — 格式规范。 先把“SKILL.md 到底长什么样、有哪些字段、各自什么约束、渐进式披露的三层硬指标”搞清楚。这是整套体系的地基,任何后续都建立在它上面。
  2. 02-reference-library.md — 参考库逐文件走读。 想看“规范是怎么被代码落实的”就读这章:skills-ref 怎么解析 frontmatter(为什么用 strictyaml)、怎么校验名字(为什么支持中文/俄文)、怎么生成 <available_skills>。短源码 + file:line。
  3. 03-client-integration.md — 客户端集成生命周期。 想自己给 agent 加 Skills 支持就读这章:发现 → 解析 → 披露 → 激活 → 上下文保护 五步,以及“宽松校验”“信任门槛”“防压缩”等真实工程权衡。
  4. 04-authoring-and-edges.md — 创作经验 + 巧妙之处 + 边界 + 横向对比。 想写好一个 skill、想知道这套设计妙在哪、刻意不做什么、和 MCP/系统提示有何不同,读这章。

每章末尾都有「代码地图」(主题 | 文件 | 符号名)方便 grep 跳源码。