Agent Skills 完全指南：从目录规范到渐进式加载的工程实践

从零到一深入理解 Agent Skills：概念、结构与构建指南

让 Agent 从"临时发挥"走向"稳定复用"

前言

随着大模型能力的不断进化，我们正从"模型会不会回答"转向"模型能不能稳定完成一类任务"。在这个背景下，Agent Skills 作为一种开放格式，正在成为 AI Agent 工程化落地的关键一环。

本文基于当前公开的 Agent Skills 规范，结合 Codex、VS Code、Claude Code 及自研 Agent 的工程实践，系统性地梳理 Skill 的概念、目录结构、加载机制、构建方法及落地实现。无论你是 Agent 开发者、业务工程师，还是技术决策者，这篇文章都将帮你建立起对 Agent Skills 的完整认知框架。

一、先理解：Skill 到底是什么？

1.1 一个形象的类比

一个 Skill 不是一个新的模型，也不是一个独立的 API。它更像是 Agent 的 "可装载工作手册"：

• 告诉 Agent 什么时候应该使用这个能力
• 告诉 Agent 按什么步骤执行
• 告诉 Agent 可以调用哪些脚本
• 告诉 Agent 遇到异常如何处理
• 告诉 Agent 最终应该如何验证结果

1.2 Agent 能力的四层架构

为了更清晰地理解 Skill 在整个系统中的位置，我们可以把 Agent 的能力拆解为四个层次：

概念	解决的问题	典型内容
Skill	怎样稳定完成一类任务	说明、流程、判断规则、脚本、参考资料、模板
Tool	怎样执行一个动作	读文件、调用 API、运行命令、写入数据库
MCP	怎样以标准方式连接外部能力	服务器、资源、工具、授权和协议适配
Plugin	怎样分发一组完整扩展能力	多个 Skill、MCP、命令、Hooks、资源和配置

在这四层中：模型 负责理解和决策，Tool 负责执行单个动作，MCP 负责连接外部系统，而 Skill 负责把知识、流程和资源组织成可重复执行的任务方案。

⚠️ 关键认知：Skill 通常会编排 Tool 或 MCP，但它本身不等于 Tool 或 MCP。

1.3 什么时候应该沉淀一个 Skill？

一个实用的判断标准是：

如果某类任务会重复发生 ，并且"步骤顺序、质量标准、边界条件、输出格式"比临时发挥更重要，就值得沉淀成 Skill。

但这里有一个值得警惕的趋势：随着基模能力越来越强（Opus 5、GPT-5.6、Kimi 3 等），一些沉重、繁杂的 Skill 反而会成为 Agent 的枷锁。我们需要根据垂类业务来写特定的 Skill，这恰恰是通用 Agent 无法触达的深度定制地带。

二、当前公开规范的核心结构

2.1 完整目录结构

Agent Skills 规范定义了清晰的目录结构，区分了必需项、规范可选项与工程附属文件：

skill-name/
├── SKILL.md                # 必需：YAML元数据 + Markdown执行说明
├── agents/                 # 可选：客户端扩展
│   └── openai.yaml         # 示例：display_name、short_description、default_prompt
├── scripts/                # 可选：可执行脚本、校验器、生成器
│   ├── extract.py          # 示例：数据提取脚本
│   └── validate.ps1        # 示例：Windows/PowerShell校验脚本
├── references/             # 可选：按需读取的长篇参考资料
│   ├── REFERENCE.md        # 示例：详细技术规范
│   └── decision-table.md   # 示例：决策表、错误码或边界条件
├── assets/                 # 可选：模板、图片、样例数据、配置骨架
│   ├── template.md         # 示例：输出模板
│   └── sample.json         # 示例：输入/输出样例
├── evals/                  # 可选：Skill的触发与质量评测用例
│   ├── evals.json          # 示例：prompt、expected_output、files、assertions
│   └── files/              # 可选：评测输入文件
│       └── sample.csv
└── LICENSE.txt             # 可选：许可证文件

2.2 三层理解

我们可以将上述目录结构从三个层次来理解：

• 第一层 ：Agent Skills 开放规范的核心 ------ SKILL.md 是必需的，scripts/、references/、assets/ 是规范明确支持的可选目录。
• 第二层 ：客户端扩展 ------ 例如 Codex 中常见的 agents/openai.yaml，用于技能列表和 UI 展示。
• 第三层 ：质量工程目录 ------ 例如 evals/，用于保存评测用例，而不是 Skill 运行时必须加载的资源。

2.3 各目录的设计职责

每个目录都有其特定的设计职责：

• scripts/ ：承载确定性操作（脚本）
• references/ ：承载较长知识（参考资料）
• assets/ ：承载静态资源（模板、示例）
• evals/ ：承载质量验证（评测用例）

⚠️ 注意事项：

• 目录可以继续扩展，但应避免把密钥、个人数据或未经审查的可执行文件直接打包进 Skill。
• evals/ 中每轮评测生成的 grading.json、timing.json、benchmark.json 等输出，建议放在 Skill 旁边的独立 workspace 中，不要混入运行时 Skill 包。
• README.md、CHANGELOG 和安装说明更适合放在仓库层，而不是让 Agent 把它们当作 Skill 内容。

2.4 Skill 结构全景图

┌─────────────────────────────────────────────────────────────────┐
│                       skill-name/                              │
├─────────────────────────────────────────────────────────────────┤
│  ████████████████████████████████████████████████████████████ │
│  █  SKILL.md          █  必填：元数据 + 工作流              █ │
│  ████████████████████████████████████████████████████████████ │
│                                                               │
│  ┌─────────────────┐  ┌─────────────────┐  ┌───────────────┐ │
│  │  scripts/       │  │  references/    │  │  assets/      │ │
│  │  确定性脚本      │  │  长尾知识库      │  │  模板与静态资源│ │
│  └─────────────────┘  └─────────────────┘  └───────────────┘ │
│        核心规范可选             核心规范可选        核心规范可选 │
│                                                               │
│  ┌─────────────────────────────────────────────────────────┐  │
│  │  agents/openai.yaml      客户端扩展：UI 展示元数据      │  │
│  └─────────────────────────────────────────────────────────┘  │
│                                                               │
│  ┌─────────────────────────────────────────────────────────┐  │
│  │  evals/evals.json       质量工程：评测用例              │  │
│  │  evals/files/           评测输入文件                    │  │
│  └─────────────────────────────────────────────────────────┘  │
│                                                               │
│  ┌─────────────────────────────────────────────────────────┐  │
│  │  LICENSE.txt             分发附属：许可证文件            │  │
│  └─────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────┘

2.5 SKILL.md 的两部分

SKILL.md 由 YAML frontmatter 和 Markdown 正文 组成：

• Frontmatter：负责让 Agent 在"发现阶段"快速判断是否相关
• 正文：负责在"激活阶段"提供详细的执行指令

Frontmatter 字段说明

字段	是否必需	当前约束与用途
name	✅ 是	1-64 个字符；使用小写字母、数字和连字符；不能以连字符开头或结尾；不能出现连续连字符；必须与父目录一致
description	✅ 是	1-1024 个字符；说明 Skill 做什么以及什么时候使用，是 Agent 判断是否激活的主要依据
license	❌ 否	许可证名称，或指向 Skill 内许可证文件的说明
compatibility	❌ 否	环境要求，例如操作系统、依赖包、网络访问、目标客户端等；最多 500 个字符
metadata	❌ 否	自定义键值元数据，例如作者、团队、版本、变更编号
allowed-tools	❌ 否	以空格分隔的预授权工具列表，当前属于实验性字段，不能替代完整的权限系统

正文应该写什么？

正文没有强制模板，但应写清楚任务边界和可执行步骤。推荐包含以下内容：

• ✅ 适用场景
• ✅ 输入和前置条件
• ✅ 标准工作流
• ✅ 判断分支
• ✅ 输出格式
• ✅ 异常与边界
• ✅ 验证步骤
• ✅ 对脚本和参考文件的相对路径引用

💡 重要提示 ：正文不是百科全书。通用知识、重复的模型常识和大段背景介绍会增加上下文成本。正确的做法是：

• 把经常变化、篇幅较大的资料拆到 references/
• 把确定性计算或机械操作交给 scripts/
• 把固定格式交给 assets/

三、加载方式：渐进式披露

3.1 核心设计思想

当前规范的关键设计是 Progressive Disclosure（渐进式披露） ，把 Skill 内容分成三层加载：

层级	加载内容	发生时机	设计目标
1. Catalog（发现）	name + description，必要时加路径	会话启动或 Skill 扫描时	让 Agent 知道有哪些能力，但不提前消耗完整上下文
2. Instructions（激活）	完整的 SKILL.md 正文	任务与 description 匹配后	向 Agent 注入本次任务需要的流程和规则
3. Resources（执行）	scripts/、references/、assets/ 中的具体文件	正文明确引用且任务确实需要时	只加载当前步骤需要的资源

3.2 渐进式加载链路图

用户任务
    │
    ▼
┌─────────────────────────────────────┐
│  Catalog                            │
│  扫描 name + description            │
└─────────────────────────────────────┘
    │
    ▼
description 是否匹配？
    │
    ├── 否 ──► 继续普通 Agent 流程
    │
    └── 是
         │
         ▼
┌─────────────────────────────────────┐
│  Instructions                       │
│  读取 SKILL.md                      │
└─────────────────────────────────────┘
    │
    ▼
当前步骤需要资源？
    │
    ├── 否 ──► 按流程执行
    │
    └── 是
         │
         ▼
┌─────────────────────────────────────┐
│  Resources                          │
│  按需读取 scripts / references /   │
│  assets                             │
└─────────────────────────────────────┘
    │
    ▼
调用 Tool / MCP
    │
    ▼
执行、验证并记录风险
    │
    ▼
输出结果与下一步

📌 阅读这张图时请抓住一个重点 ：Skill 不是一次性把所有内容塞进上下文，而是先用短描述完成发现，再在确实相关时逐层展开。

四、Skill 通常放在哪里？

Agent Skills 规范定义了 Skill 文件格式，但没有强制所有客户端使用同一个安装目录。实际项目中最通用的约定是使用 .agents/skills/：

作用域	建议路径	适用范围
项目级	<project>/.agents/skills/<skill-name>/	只对当前仓库或项目生效，适合业务规则和仓库流程
用户级	~/.agents/skills/<skill-name>/	对当前用户的多个项目复用，适合通用开发、写作和运维流程
客户端原生目录	由具体 Agent 产品定义	可提供额外能力，但跨客户端复用性取决于实现
组织级或内置目录	由部署平台、插件或管理端提供	适合企业标准流程、合规检查和团队共享能力

优先级规则

如果同名 Skill 同时存在，建议采用确定性的优先级：

项目级 > 用户级 > 内置默认值

同一作用域内也要固定先后规则，并记录冲突告警。

⚠️ 安全提示 ：项目级 Skill 来自代码仓库，可能是不可信内容。生产级 Agent 应在加载前做项目信任判断。

五、如何从零构建一个 Skill

💡 实践经验 ：一般选择 SOTA Agent 的 skill-creator 这个 Skill 来辅助创建。人写的 Skill 很容易出现很多问题和遗漏。工程师的职责是规划 Skill 的架构 和审查 Skill 是否符合预期。

5.1 第一步：选择一个足够窄的任务

❌ 不要从"帮助我做所有后端开发"开始

✅ 更好的切入点：

• "审查 Go HTTP 服务的变更"
• "生成 Java 服务的接口测试"
• "把会议纪要转换为可追踪任务"

🎯 核心原则 ：Skill 不能宽泛 ，一定是面对一个够垂类、够窄的场景 来写，description 够清晰，Agent 才容易选到这个 Skill。

5.2 第二步：先写触发描述，再写正文

先用一句话回答两个问题：

1. 这个 Skill 做什么？
2. 用户在什么情况下会需要它？

description 中应该加入同义表达 和典型输入 ，但不要 把完整流程塞进 description。

5.3 第三步：把流程写成 Agent 可以执行的步骤

每一步都尽量包含：动作 + 判断依据 + 下一步

❌ 不要只写：

"认真检查，确保质量"

✅ 而要写：

"先读取变更范围，再运行指定测试；如果测试失败，保留错误输出并停止发布"
⚠️ 高风险操作 ：涉及写入、删除、发送消息、部署等高风险动作时，明确要求预览、确认、幂等键、回滚或人工审批。

5.4 第四步：按需拆分资源

• scripts/：放确定性强、值得复用的程序（数据提取、格式检查、生成报告等）。脚本要有清晰的输入输出、错误提示和依赖说明。
• references/：放较长的领域规范、API 约定、错误码、示例和决策表。正文只在需要时引用具体文件。
• assets/：放模板、样例数据、图标、配置骨架和其他静态资源。

5.5 第五步：验证 Skill，而不是只验证文案

至少准备一组：

• ✅ 正向触发
• ✅ 负向不触发
• ✅ 边界条件
• ✅ 异常输入

验证 Agent 是否：

• 在正确任务上激活 Skill
• 真的读取了脚本或参考资料
• 遵守了输出格式
• 失败时停止在安全边界内

验证工具链：

• 基础层面：使用 skills-ref validate ./my-skill 检查目录、frontmatter 和命名约束
• 质量层面：在 evals/evals.json 中维护 2-3 个真实用例，分别运行 with-skill 与 without-skill（或旧版本）进行对照

5.6 第六步：版本化和维护

• 把 Skill 放进 Git
• 给变更写明原因和影响范围
• 流程、工具接口、依赖版本或安全规则变化时，同步更新正文、脚本和测试样例
• 对 description 的修改尤其要做回归测试，因为它会直接影响激活召回

六、一个可直接复制的最小示例

下面是一个面向 Go 服务变更审查的示例。它刻意保持短小，把详细规则留给后续的 references/ 文件。

目录结构

go-review/
├── SKILL.md
├── scripts/
│   └── check-coverage.sh
├── references/
│   ├── go-coding-standards.md
│   └── common-bugs.md
└── assets/
    └── review-template.md

SKILL.md 示例

---
name: go-review
description: 审查 Go HTTP 服务的变更，检查代码规范、测试覆盖率和潜在 bug。适用于 Go 服务的 PR 审查或代码提交前检查。
license: MIT
compatibility: Go 1.21+, Linux/macOS
metadata:
  author: platform-team
  version: 1.0.0
---

# Go HTTP 服务变更审查

## 适用场景
- Go 服务的 Pull Request 审查
- 代码提交前的质量门禁

## 输入
- 变更的文件列表（Git diff）
- 目标分支名称

## 工作流

1. 读取 `git diff` 获取变更范围
2. 对每个变更的 `.go` 文件运行 `go vet`
3. 检查测试覆盖率是否下降超过 2%
4. 依据 `references/go-coding-standards.md` 检查代码规范
5. 输出审查报告到 `assets/review-template.md`

## 异常处理
- 如果 `go vet` 失败，输出错误详情并停止流程
- 如果覆盖率下降超过 2%，标记为需要人工审核

## 验证
- 运行 `scripts/check-coverage.sh` 验证覆盖率报告

七、如果你在建造自己的 Agent：如何实现 Skill 支持

自研 Agent 不需要把 Skill 做成一个复杂的插件系统。最小实现可以围绕 七个环节 展开：

7.1 七个核心环节

环节	说明	关键点
1. 发现	扫描项目级、用户级和组织级目录	只识别包含 SKILL.md 的子目录；跳过 .git、node_modules 等目录；设置最大深度和数量上限
2. 解析	读取 YAML frontmatter	至少提取 name、description 和 SKILL.md 的绝对路径；解析失败时记录诊断；缺少 description 的 Skill 不应进入目录
3. 建立目录	把 name、description、路径和 Skill 根目录提供给模型	目录应该短小，不能把所有 Skill 正文一次性注入上下文
4. 激活	优先让模型根据 description 判断是否相关	然后读取完整 SKILL.md；也可以提供显式的 activate_skill 工具支持用户点名激活
5. 资源访问	以 Skill 根目录解析正文中的相对路径	按需读取脚本、参考资料和资产，不要默认把整个目录全部加载
6. 权限与信任	对项目级 Skill 做信任判断	对脚本、网络、文件写入和高风险命令做权限控制；不要把 allowed-tools 当成唯一安全边界
7. 观测	记录发现、冲突、激活、资源读取、脚本执行和失败原因	便于解释"为什么某个 Skill 被使用或没有被使用"

7.2 实现伪代码

# 1. 发现
catalog = discover(project_dirs, user_dirs, org_dirs)

# 2. 解析
catalog = parse_frontmatter(catalog)

# 3. 过滤
catalog = filter_by_trust_and_policy(catalog)

# 4. 目录注入
model_context.add(skill_catalog(catalog))

# 5. 激活与执行
if model_or_user_selects(skill):
    instructions = load(skill.SKILL.md)
    model_context.add(instructions)
    resources = resolve_referenced_files(skill.root)
    run_only_the_resources_needed_for_current_step(resources)

7.3 设计原则

📌 自研 Agent 的实现应把 "格式兼容" 和 "产品特性" 分开：

• Agent Skills 规范定义了目录、SKILL.md 和渐进式加载的通用约定
• 具体客户端可以增加自己的安装路径、显式命令、权限模型、生命周期钩子或打包方式
• 但这些扩展不能破坏最小格式的可移植性

八、常见失败方式与改进建议

问题	表现	改进建议
description 太泛	任务一多就误触发，Agent 不知道边界	加入明确的对象、动作、输入和适用场景；必要时拆成多个 Skill
SKILL.md 太长	激活后上下文膨胀，关键步骤被淹没	正文保留工作流，长规范迁移到 references/；正文建议控制在约 5000 token 以内
只有原则没有动作	写了"保证安全"，却没有说明怎样预览、确认和回滚	把质量要求改写为可执行的检查、命令、判断分支和输出格式
脚本不可复现	依赖隐藏环境变量、当前目录或未说明的第三方包	记录依赖，使用明确参数，提供错误信息和退出码，并增加样例测试
把 Skill 当权限系统	Skill 中写了"可以执行某命令"，就绕过安全控制	由 Harness 在工具层实施最小权限、路径限制、审批、超时、审计和取消
不做负向测试	任何包含关键词的任务都触发 Skill	增加相似但不应触发的提示，验证召回率和误触发率

九、发布前检查清单

在发布一个 Skill 之前，请逐项确认：

• SKILL.md 的 name 与父目录一致，符合命名约束
• description 清晰说明了 Skill 做什么及何时使用（1-1024 字符）
• 正文包含了可执行的步骤，而非泛泛的原则
• 长篇幅内容已拆分到 references/
• scripts/ 中的脚本有明确的输入输出和依赖说明
• 至少准备了 2-3 个 evals/ 评测用例（含正向和负向）
• 高风险操作明确了预览、确认或回滚机制
• 没有在 Skill 中硬编码密钥或个人数据
• 已用 skills-ref validate 通过基础检查
• 已做 with-skill 与 without-skill 的对比测试
• Git 提交信息清晰说明了变更原因和影响范围

十、结论：把 Skill 当成可测试的"流程产品"

Agent Skills 本质上是一套将隐性知识显性化、将显性知识可执行化的工程框架。它并不复杂，但需要我们从几个维度转变思维：

1. 从"写提示词"到"设计流程" ：Skill 不只是给模型的指令，更是一套完整的操作规范
2. 从"一次性的"到"可复用的" ：每个 Skill 都应该是经过测试、版本管理和持续优化的
3. 从"大而全"到"小而精" ：垂类、窄场景的 Skill 更容易被正确触发和执行
4. 从"模型依赖"到"流程保障" ：Skill 让确定性操作回归脚本，让判断逻辑回归规则，让知识沉淀到参考资料

🎯 最终目标 ：把 Skill 当成可测试的"流程产品" 来对待，而不是一段写着"随便发挥"的提示词。这是 Agent 从"酷炫 Demo"走向"生产级工具"的关键一步。

---

本文基于 2026-08-02 更新的 Agent Skills 公开规范整理，并结合了 Codex、VS Code、Claude Code 及自研 Agent 的工程实践。