Agent Skills 开放格式与目录结构
本节目标
分清“规范要求”“推荐约定”和“client 实现”，并能设计一个最小 Skill 目录。
Skill 解决什么问题
普通提示可以告诉模型这一次怎么做，但团队的真实工作往往还依赖项目约定、固定步骤、校验脚本、模板和故障经验。Agent Skills 用一个可版本控制的文件夹打包这些内容，让兼容 client 能发现并在适当时机提供详细说明。
格式开放意味着不同产品可以读取同一基本结构；不意味着不同产品的安装路径、可调用工具、权限、冲突优先级、子 agent 继承和触发概率完全相同。有些 host 会按 description 自动选择，有些允许显式选择，有些配置会预加载完整正文。移植前需要阅读目标 client 的官方说明并实际测试；详见 定位、客户端差异与权限边界。
一个 Skill 应围绕一个连贯能力边界，而不是把整个团队手册塞进一个包。先从真实项目中的稳定做法、失败记录、模板和可验证脚本提炼；若两个任务的输入、风险或验收方式完全不同，应拆成两个 Skill。来源、许可证、版本和兼容性信息也属于可维护性契约。
最小与扩展目录
text-statistics/
├── SKILL.md # 必需：YAML frontmatter + Markdown 指令
├── scripts/ # 可选：可执行脚本
├── references/ # 可选：按需读取的参考材料
├── assets/ # 可选：模板、静态资源、查找表
└── evals/ # 常用评测目录；官方创作指南中的实践结构规范的最低要求是 Skill 目录中存在 SKILL.md。scripts/、references/、assets/ 是规范描述的可选目录；evals/ 是官方评测指南采用的工作结构，不应误称为必需格式字段。
如何决定放在哪里
- 每次激活都必须知道的步骤、边界和关键 gotchas 放
SKILL.md。 - 只在某个错误或子任务出现时需要的长说明放
references/，并在SKILL.md明确“何时读哪一篇”。 - 重复计算、格式转换或确定性校验放
scripts/，避免模型每次重新发明代码。 - 长模板、示例素材和静态 schema 放
assets/。
文件引用使用相对 Skill 根目录的路径，并尽量保持一层引用深度。深层“文档再链接文档”会让 agent 不知道何时继续加载，也增加遗漏风险。
规范与 client 的边界
| 问题 | 开放格式规定 | 具体 client 决定 |
|---|---|---|
| 必需文件 | SKILL.md | 去哪些目录发现它 |
| 核心 metadata | name、description | 如何匹配和展示 |
| 指令与资源 | Markdown body、可选目录 | 用什么工具读取/执行 |
| 权限 | allowed-tools 是实验字段；compatibility 只能描述环境要求 | 是否支持、如何向用户确认、身份与 scope 如何验证 |
| 触发 | description 是关键发现信息 | 实际模型与 harness 的匹配行为 |
常见误区
- 把任何长文档都叫 Skill：没有明确任务、触发和可执行流程，价值有限。
- 把产品专属安装命令写成开放规范：应标记 client 名称与版本/获取日期。
- 把所有知识塞进
SKILL.md：激活后全量进入上下文，反而干扰执行。 - 目录很多但
SKILL.md不说明何时读取：资源存在不等于 agent 会正确使用，更不等于资源内容可信。 - 把 Skill 当作授权：它可影响选择工具的上下文，却不能证明用户同意、令牌 scope 正确或动作已获审批。
练习与自测
- 为“审查本仓库 Python CLI”设计目录，只写文件名和每项用途，并说明这个能力为何足够内聚。
- 判断 API 错误码长表、每次必做的安全检查、输出报告模板、确定性 schema 验证器各放哪里。
- 自测：
evals/是规范必需目录吗？不是；它是官方评测指南推荐的实践结构。
下一步
参考资料
- Agent Skills Specification（核验日期：2026-07-22）
- GitHub Copilot: About agent skills（client 实现示例；核验日期：2026-07-22）