Agent Skills开放规范，附 Specification 原文与 SKILL.md 字段规则

是 否 +2 论坛币

k人 参与回答

经管之家送您一份

应届毕业生专属福利!

求职就业群

赵安豆老师微信：zhaoandou666

经管之家联合CDA

送您一个全额奖学金名额~ !

立即领取

感谢您参与论坛问题回答

经管之家送您两个论坛币！

+2 论坛币

资料名称： Agent Skills 开放规范的完整格式说明（Specification），即 agentskills.io 站点上的那一页规范正文，配套同一站点的 Overview 概览页与 GitHub 上的 agentskills/agentskills 规范仓库

　

帖内资料： 技能目录的标准结构、SKILL.md 的 YAML 前置字段逐项约束（必填与可选各是哪些、长度上限、命名规则）、正文体的写法建议、scripts／references／assets 三个可选目录各自的用途与写法要求、渐进披露的三级加载与 token 预算、文件引用的写法与深度限制，以及校验命令

　

时间覆盖： 规范仓库创建于 2025 年 12 月 16 日，最后推送为 2026 年 8 月 9 日

　

许可与引用： 规范仓库为 Apache-2.0 许可；文档站只提供页面内容，本贴只整理其中已公开的字段规则与结构约定，不复制原文段落

　

适用任务： 要给自己或团队写一个技能并保证别的智能体也能加载的，要查某个字段该填什么才合规的，要决定哪些内容放 references 而不是塞进 SKILL.md 的

　

这份规范是什么

　

Agent Skills 是一种用来给 AI 智能体加能力和专业知识的轻量开放格式。规范页把它定义得很直接：一个技能就是一个目录，里面至少放一个 SKILL.md；这个文件包含元数据（最少是 name 和 description）以及告诉智能体怎么完成某个具体任务的说明。技能还可以带上脚本、参考资料、模板等资源。

　

它想解决的问题是：智能体的能力越来越强，但往往缺少把活做稳所需的上下文。技能的做法是把流程性知识，以及公司、团队、用户特有的上下文，打包成可移植、可版本管理的文件夹，由智能体按需加载。官方列了三条收益：领域专长（把法律审查流程、数据分析管线、演示排版这类专门知识变成可复用的说明和资源）、可重复的工作流（把多步任务变成一致且可审计的流程）、跨产品复用（写一次，在任何兼容的智能体上用）。

　

目录结构：一个文件夹加一个 SKILL.md

　

规范给的标准结构是这样的：

　

1. skill-name/
2. ├── SKILL.md      # 必需：元数据 + 说明
3. ├── scripts/      # 可选：可执行代码
4. ├── references/   # 可选：文档
5. ├── assets/       # 可选：模板、资源
6. └── ...           # 任何额外文件或目录
7. 　

复制代码

　

目录里除了必需的 SKILL.md，可以放任何额外文件或目录；下面三个是推荐的组织约定，不是强制。

　

SKILL.md 的前置字段

　

SKILL.md 必须是 YAML frontmatter 加 Markdown 正文。frontmatter 有六个字段，两个必填、四个可选。

　

必填的 name：长度 1 到 64 字符，只允许小写字母、数字和连字符，不能以连字符开头或结尾，不能有连续连字符，而且必须与父目录名一致。规范给的合法例子是 pdf-processing、data-analysis、code-review；非法例子三条——PDF-Processing（大写不允许）、-pdf（不能以连字符开头）、pdf--processing（不能连续连字符）。

　

必填的 description：长度 1 到 1024 字符，不能为空，要同时说明这个技能做什么、什么时候该用它，并且最好带上能帮智能体识别出相关任务的具体关键词。规范给的对比很直白——好的写法是"从 PDF 文件提取文本和表格、填写 PDF 表单、合并多个 PDF。用于处理 PDF 文档，或当用户提到 PDF、表单、文档提取时"，差的写法是"帮助处理 PDF"。

　

可选的 license：写许可名称，或指向包里附带的许可文件名。规范建议写短一点，比如"Proprietary. LICENSE.txt has complete terms"。

　

可选的 compatibility：如果技能有特定运行环境要求才写，最多 500 字符，可以写面向的产品、需要哪些系统包、是否要联网等。规范给的例子是"Designed for Claude Code (or similar products)"、"Requires git, docker, jq, and access to the internet"、"Requires Python 3.14+ and uv"。

　

规范特别说明：大多数技能不需要这个字段。

　

可选的 metadata：字符串键到字符串值的映射，用来存规范本身没定义的额外属性；规范建议键名起得独特一些以免冲突，例子是 author: example-org 和 version: "1.0"。

　

可选的 allowed-tools：空格分隔的字符串，列出预先批准可运行的工具。规范标注这一项是实验性的，各家智能体实现的支持程度可能不同，例子是"allowed-tools: Bash(git:) Bash(jq:) Read"。

　

正文怎么写

　

正文是 frontmatter 之后的 Markdown，放技能说明本身，没有格式限制，写什么有助于智能体完成任务就行。规范推荐写三类内容：分步说明、输入输出示例、常见边界情况。

　

但有一条约束值得注意：智能体一旦决定启用某个技能，就会把整个 SKILL.md 一次性读进上下文。所以规范建议把更长的内容拆成被引用的文件，主 SKILL.md 保持在 500 行以内。

　

三个可选目录

　

scripts/ 放智能体可以运行的脚本，规范要求脚本要么自包含、要么把依赖写清楚，还要给出有用的错误信息、优雅处理边界情况；支持哪些语言取决于智能体实现，常见的是 Python、Bash 和 JavaScript。

　

references/ 放需要时才读的补充文档，规范给的命名习惯是 REFERENCE.md 放详细技术参考、FORMS.md 放表单模板或结构化数据格式，也可以按领域分文件如 finance.md、legal.md。规范提醒单个参考文件要保持聚焦，因为智能体是按需加载的，文件越小占用的上下文越少。

　

assets/ 放静态资源：模板（文档模板、配置模板）、图片（示意图、示例）、数据文件（查表、schema）。

　

渐进披露：文件是怎么被加载的

　

这是规范里最实用的一块，它解释了为什么目录要这么摆。

　

概览页把加载分成三步：发现阶段，智能体启动时只加载每个可用技能的 name 和 description，够判断它可能相关就行；激活阶段，当任务与某个技能的 description 匹配时，智能体把完整的 SKILL.md 读进上下文；执行阶段，智能体按说明执行，必要时运行自带的代码或加载被引用的文件。概览页那句总结是：完整说明只在任务匹配时才加载。

　

规范页给了三档 token 预算：元数据约 100 token，启动时对所有技能加载；说明部分建议不超过 5000 token，技能激活时加载；资源按需加载，只有需要时才读进来。

　

文件引用怎么写

　

引用技能里的其他文件时，用相对技能根目录的路径。规范给的例子是在 SKILL.md 里写"See the reference guide（references/REFERENCE.md） for details."，以及单独一行写"Run the extraction script:"再跟一行"scripts/extract.py"。

　

规范给了一条明确限制：文件引用保持在离 SKILL.md 一层深，避免嵌套的引用链。

　

怎么校验

　

规范给了一个校验办法：用 skills-ref 这个参考库检查，命令是"skills-ref validate ./my-skill"，它会检查 SKILL.md 的 frontmatter 是否有效、是否遵循全部命名约定。

　

原页在哪

　

规范页在 agentskills.io/specification，概览页在 agentskills.io，规范仓库在 GitHub 的 agentskills/agentskills。站点还提供一份完整的文档索引（/llms.txt）供检索。完整地址和引用提醒放在下面。

　

────────────────

规范页、概览页、仓库地址和文档索引都在下面，回复一下就能看到。

游客，如果您要查看本帖隐藏内容请回复

扫码加我 拉你入群

请注明：姓名-公司-职位

以便审核进群资格，未注明则拒绝

分享0 收藏0 回帖

谢谢楼主，先蹲一个