第 22 章 · Agent Skills 标准与 SKILL.md
本章目标：理解 Agent Skills 开放标准的核心理念，掌握 SKILL.md 的 frontmatter 字段规范，知道技能如何在不撑爆上下文的前提下按需加载。
22.1 什么是 Agent Skills 标准
Agent Skills 是一个开放标准（specification），定义了 AI 编码智能体如何以统一格式分发能力包。它的核心贡献是：
- 统一接口：无论使用 Claude Code、Codex、Cursor 还是 Pi，技能的加载方式一致；
- 渐进披露：启动时只有
name+description进入系统提示，完整指令按需加载； - 自包含：技能目录可携带脚本、资源文件、参考文档，整体可迁移。
标准由 agentskills.io 发布，核心要求只有一条：技能的根目录必须有一个 SKILL.md 文件。
my-skill/
├── SKILL.md # 必需：frontmatter + 正文指令
├── scripts/
│ └── helper.py # 可选：辅助脚本
└── references/
└── api-reference.md # 可选：按需加载的详细文档这个目录结构可以被任何遵守标准的工具发现并加载——这就是"开放"二字的意义。
22.2 SKILL.md Frontmatter 字段详解
SKILL.md 的第一部分必须是 YAML frontmatter，用于给 agent 提供元数据。官方规范定义了以下字段：
| 字段 | 必需 | 限制 | 说明 |
|---|---|---|---|
name | ✅ | ≤64 字符，小写 + 数字 + 连字符 | 技能的唯一标识；不要求与目录名相同（这是 pi 对标准的宽容扩展） |
description | ✅ | ≤1024 字符 | 最关键的一行——决定 agent 何时触发加载；写得具体才有高命中率 |
license | — | — | 许可证名称或路径 |
compatibility | — | ≤500 字符 | 运行环境要求（如 Python ≥3.10） |
metadata | — | 任意键值 | 供工具扩展用的自定义字段 |
allowed-tools | — | 实验性 | 预批准工具列表，避免运行时权限询问 |
disable-model-invocation | — | 布尔值 | 为 true 时技能从系统提示隐藏，只能通过 /skill:name 手动调用 |
Name 校验规则
有效：changelog-check, pdf-merge, code-review
无效：Changelog-Check（大写）、-pdf（连字符开头）、data--analysis（连续连字符）Description 的设计原则
description 是触发器，不是功能说明书。好的 description 应该包含触发词和适用场景：
# 好：具体、包含触发词
description: >
Verify CHANGELOG.md covers all notable changes since the last git tag.
Use when preparing releases or the user mentions changelog.
# 差：模糊，agent 无法判断
description: Helps with PDFs.官方原话
"The description determines when the agent loads the skill. Be specific."
22.3 渐进披露机制
技能的"渐进披露（progressive disclosure）"是它区别于一次性 prompt 的核心设计：
启动时：
扫描所有技能 → 只把「name + description」注入 system prompt
（约 50–200 行，不撑爆上下文）
运行中：
agent 判断任务匹配某技能 → 用 read 工具加载完整 SKILL.md
（按需读取，而非全量加载）
执行时：
按 SKILL.md 中的指令行事，引用相对路径下的 scripts/references这意味着：你可以安装几十个技能，但常驻上下文的成本只有几十个描述。
22.4 与 MCP / AGENTS.md 的分工差异
很多读者会问：Skill 和 MCP 工具、AGENTS.md 有什么不同？三者的定位如下：
| 维度 | Agent Skill | MCP Tool | AGENTS.md |
|---|---|---|---|
| 形态 | Markdown 指令包 | 远程可调用函数 | 项目级说明文件 |
| 加载时机 | 按需 read | 持续注册到工具列表 | 启动时加载 |
| 作用范围 | 特定任务工作流 | 通用能力（搜索/数据库等） | 整个项目的上下文 |
| 动态性 | 可替换/可组合 | 独立服务 | 静态 |
| 典型场景 | "发版前检查 changelog" | "搜索 GitHub issues" | "本项目技术栈是 FastAPI+SQLModel" |
三者互补：AGENTS.md 给全局背景，MCP 提供跨项目通用的基础能力，Skills 封装针对特定任务的最佳实践。
22.5 校验规则速查
| 问题 | 行为 |
|---|---|
缺少 description | ❌ 不加载（唯一硬拦截） |
name 超长或含非法字符 | ⚠️ 警告，仍加载 |
name 与目录名不一致 | ✅ 允许（pi 的扩展） |
| 同名冲突（多处发现） | ⚠️ 警告，保留先发现者 |
| 未知 frontmatter 字段 | ✅ 忽略，不影响加载 |
本章小结
- Agent Skills 是开放标准，核心是
SKILL.md文件； description决定触发时机，必须具体化；- 渐进披露让上下文成本控制在几十个描述；
- 与 MCP/AGENTS.md 分工不同，三者可叠加使用；
- 缺
description是唯一硬拦截，其他问题仅警告。
🧪 随堂测验
点击你认为正确的选项。答错时会展示正确答案与原因解析。
1. Agent Skills 标准中，哪个 frontmatter 字段缺失会导致技能被拒绝加载？
2. 以下哪个 name 值是符合规范的？
3. 渐进披露的核心目的是什么？
4. 关于 name 与目录名的关系，以下说法正确的是？
🛠️ 动手实践
- 在
~/.pi/agent/skills/test-skill/SKILL.md创建一个名字为test-skill的技能，description 写明"当用户提到单元测试或 test coverage 时使用"。 - 故意写一个缺
description的技能，观察 agent 是否忽略它。 - 在 description 中分别测试"模糊版"和"具体版"，对比 agent 触发率。
完成练习后，进入下一章：编写高质量技能。