跳到主要内容

第 1 章 · SKILL.md 格式规范

本章讲清楚 skill 文件到底长什么样:目录结构、frontmatter 的 6 个字段及各自约束、正文怎么写、以及把这一切串起来的“渐进式披露三层”。读完你能手写一个合规的 SKILL.md,也能看懂校验器在卡什么。来源:docs/specification.mdx。

1.1 目录结构:一个文件夹 + 一个必需文件​

skill 的最小单位是一个目录,里面至少有一个 SKILL.md(docs/specification.mdx:8-17):

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

三个可选目录各有分工(docs/specification.mdx:187-212):

目录放什么何时被加载
scripts/可执行代码(Python / Bash / JS),agent 直接跑正文指示运行时
references/按需读的文档(REFERENCE.md、finance.md…)正文指示阅读时
assets/静态资源:模板、图片、数据表、schema用到时

规范强调:引用文件保持“离 SKILL.md 一层深”,别搞深层嵌套引用链(docs/specification.mdx:235)。

1.2 SKILL.md 两段式:frontmatter + 正文​

一个 SKILL.md 由两部分组成(docs/specification.mdx:21):

  1. YAML frontmatter——夹在两道 --- 之间的元数据;
  2. Markdown 正文——闭合 --- 之后的全部内容,就是给 agent 的指令。

最小例子只需两个必填字段(docs/specification.mdx:37-42):

---
name: skill-name
description: A description of what this skill does and when to use it.
---

1.3 frontmatter 的 6 个字段​

规范定义了 6 个字段,只有 name、description 必填(docs/specification.mdx:25-32):

字段必填约束
name是≤64 字符;小写字母 / 数字 / 连字符;不得以 - 开头或结尾
description是≤1024 字符;非空;说明“做什么 + 何时用”
license否许可证名,或指向打包进来的许可证文件
compatibility否≤500 字符;声明环境要求(目标产品、系统包、网络等)
metadata否任意 key-value 映射,放规范没定义的额外属性
allowed-tools否空格分隔的预批准工具串(实验性)

下面逐个看关键约束(也是校验器真正在卡的点,见第 2 章)。

name:不只是“小写带横线”​

规范列出的规则比表格更细(docs/specification.mdx:58-66):

  • 长度 1–64;
  • 只能含 unicode 小写字母、数字、连字符;
  • 不能以 - 开头或结尾;
  • 不能含连续连字符 --;
  • 必须和父目录名一致。

最后一条(name == 目录名)是个容易忽略的硬约束——它让“文件夹名”成为 skill 的稳定标识。

注意规范写的是 unicode 小写字母,不是 ASCII。也就是说 技能、мой-навык 这类名字也合法(第 2 章会看到校验器用 str.isalnum() + NFKC 归一化来实现这点)。

description:触发的全部赌注押在这一句​

description 不只是“介绍”,它是 agent 决定要不要加载这个 skill 的唯一依据(docs/specification.mdx:93-96):

  • 长度 1–1024;
  • 应同时说明做什么和何时用;
  • 应包含具体关键词帮 agent 匹配相关任务。

规范给的好/坏对照(docs/specification.mdx:99-108):

# 好:既说做什么,又说何时用,关键词具体
description: Extracts text and tables from PDF files, fills PDF forms, and merges multiple PDFs. Use when working with PDF documents or when the user mentions PDFs, forms, or document extraction.

# 差:太空,agent 无从判断何时该用
description: Helps with PDFs.

compatibility:大多数 skill 用不到​

声明环境要求,≤500 字符,只在确有特殊要求时才写(docs/specification.mdx:124-145)。例如:

compatibility: Requires git, docker, jq, and access to the internet

allowed-tools:实验性,预批准工具​

空格分隔的工具串,声明这个 skill 可以免确认直接跑的工具(docs/specification.mdx:163-174)。注意它是实验性的,不同实现支持程度不一:

allowed-tools: Bash(git:*) Bash(jq:*) Read

1.4 正文:没有格式限制,但有篇幅纪律​

闭合 --- 之后的 Markdown 就是 skill 指令,格式不限——怎么写有助于 agent 完成任务就怎么写(docs/specification.mdx:176-185)。规范建议包含:分步指令、输入/输出示例、常见边界情况。

但有一条关键提醒:激活时整篇正文都会进上下文,所以

  • 主 SKILL.md 建议 ≤500 行;
  • 更长的内容应拆到 references/ 等独立文件,按需加载(docs/specification.mdx:222)。

1.5 渐进式披露:三层 token 预算​

这是整个格式的设计目的——让 agent 能同时挂很多 skill,却只付很小的常驻上下文成本。规范把加载分成三层(docs/specification.mdx:214-222):

层加载什么何时token 量级
① 元数据name + description启动时,所有 skill 都加载~100 / 个
② 指令整个 SKILL.md 正文skill 被激活时建议 <5000
③ 资源scripts/ references/ assets/ 里的文件正文用到时视情况

怎么读这张表: 从上往下是“越来越贵、越来越晚加载”。tier 1 给所有 skill 付一笔小钱让模型“知道有什么”;只有被选中的 skill 才升级到 tier 2;tier 2 里被点名的文件才升级到 tier 3。

这就是为什么 §1.3 反复强调 description 要精准、正文要短、引用文件要浅——每一层都是为了把“贵的内容”推迟到“真正需要”那一刻。

1.6 文件引用与校验​

文件引用用相对 skill 根的相对路径,且保持一层深(docs/specification.mdx:224-235):

See [the reference guide](references/REFERENCE.md) for details.

Run the extraction script:
scripts/extract.py

校验用本仓库的 skills-ref 参考库(docs/specification.mdx:237-245):

skills-ref validate ./my-skill

它检查 frontmatter 是否合法、命名是否合规。这条命令背后的代码,正是下一章的主题。

1.7 代码地图​

主题文件符号 / 锚点
目录结构docs/specification.mdx“Directory structure” 节(:6-17)
frontmatter 字段总表docs/specification.mdx“Frontmatter” 表(:25-32)
name 约束docs/specification.mdx“name field”(:58-66)
description 约束docs/specification.mdx“description field”(:93-108)
渐进式披露三层docs/specification.mdx“Progressive disclosure”(:214-222)
可选目录docs/specification.mdxscripts/ references/ assets/(:187-212)