技能文件解剖:一份 SKILL.md 里必须有什么
技能装上了,模型从不打开,于是正文越写越长,指望长度能修好路由。
📜 目录
技能装了却从不被调用,看起来像内容问题,其实是路由问题。模型不会去翻你的文件夹。开工时它只看到每个技能的一行:名字和描述。那一行是它打开后面全部内容的唯一理由。
所以真正要问的不是"文件里怎么把提示词写好",而是:运行时到底读什么、推迟读什么、推迟的那部分里必须有什么,才能让一套流程被一个完全没参与写作的东西读懂还照着做完。
下面是 agentskills.io 在 2026 年 11 月 22 日发布的规范,加上 anthropics/skills 仓库里 19 个参考技能的实测数据(198,366 stars,最后推送 11 月 16 日,今天从 GitHub API 拉的)。文中每个计数都出自那个仓库,不出自厂商软文。
文件夹本身就是接口
一个技能就是一个目录。一个文件必须有,三个子目录是惯例:
release-notes/
├── SKILL.md # 必需:frontmatter + 指令
├── scripts/ # 可选:可执行代码
├── references/ # 可选:按需加载的文档
└── assets/ # 可选:模板、样例
别的都不强制。没有 manifest,没有构建步骤,没有服务端。能交付一个 Markdown 文件夹就能交付一个技能,这也是这个格式传播得比 tool-calling schema 快的主要原因。
frontmatter:六个字段,两个是关键
| 字段 | 必需 | 约束 | 决定什么 |
|---|---|---|---|
name | 是 | 1-64 字符,只能小写字母、数字、连字符;不能首尾连字符;不能连续连字符;必须与父目录同名 | 身份,以及校验过不过 |
description | 是 | 1-1024 字符 | 技能会不会被选中。这是激活之前模型唯一能看到的文字 |
license | 否 | 短名或附带许可证文件 | 运行无关;影响复用 |
compatibility | 否 | 最多 500 字符 | 声明依赖的程序、系统、网络 |
metadata | 否 | 字符串到字符串的映射 | 作者、版本,工具链想放什么放什么 |
allowed-tools | 否 | 空格分隔,实验性 | 预批准命令,如 Bash(git:*) Bash(jq:*) Read |
命名规则比看上去严,而且是最先崩的地方。PDF-Processing 卡在大写,-pdf 卡在首字符,pdf--processing 卡在双连字符,pdf-processing 放进名为 pdf_processing 的目录则卡在同名要求上。四种方式,把四个本来成立的思路在运行前就否掉。
渐进披露:三次加载,一份预算
规范只定义了文本进入上下文的三次时机:
| 阶段 | 加载什么 | 何时 | 公开预算 |
|---|---|---|---|
| 元数据 | 所有已安装技能的 name 和 description | 每次会话开始 | 每技能约 100 token |
| 指令 | 整个 SKILL.md 正文 | 技能被激活时 | 建议 5,000 token 以内 |
| 资源 | scripts/、references/、assets/ | 流程明确要文件时 | 按需 |
第一行我没信那个约数,直接量了。19 个参考技能的 description 合计 1,290 token,平均每个 68。装二十个也就 1,360 token 的空载成本,比二十个工具 schema 便宜得多。
第三行才是杠杆所在。一个技能可以带着 26,000 token 的参考手册,在没人问起之前只花 100 token。这个说法成立的前提是正文指向文件,而不是把文件粘进正文。
最容易写错的地方:description 是检索键
同样一个技能,两种写法:
description: Helps with release notes.
description: Writes release notes from a git commit range. Use when the user asks for a
changelog, release notes, what changed since v1.4, or a summary of commits between
two tags. Reads git log output only; never invents entries.
第二种能用,因为它含了人真正会敲进去的词,也写清了边界。规范的建议是同时描述"这个技能做什么"和"什么时候用它",并带上能识别的关键词。这不是文案技巧,这是检索键。
边界那句话比看上去重要。只读 git log 输出、绝不编造条目,是有牙的指令,而且在正文被截断或压缩的上下文里,它往往是唯一活下来的那句。
一份能过审的 SKILL.md
下面的例子把一件反复做的杂活,用 git 提交区间写发布会说明,变成技能。重点在形状:主文件短,一个脚本,一个参考,一个模板。
---
name: release-notes
description: Writes release notes from a git commit range. Use when the user asks for a
changelog, release notes, what changed since vX, or a summary between two tags.
Reads git output only and never invents entries.
compatibility: Requires git, plus Python 3.10 for scripts/collect.py
allowed-tools: Bash(git:*) Read
---
# Release notes
## Steps
1. Run scripts/collect.py FROM_TAG TO_TAG to dump commits as JSON.
2. Drop merge commits, and commits touching only tests or docs.
3. Group the rest into Added / Changed / Fixed using references/CLASSIFY.md.
4. Render with assets/RELEASE_TEMPLATE.md.
5. If a commit message is unclear, list it under Unclassified instead of guessing.
## Rules
- One line per user-visible change. No commit hashes in the output.
- Never describe a change the diff does not support.
- If the range is empty, say so and stop.
## Example
Input: v1.3.0..v1.4.0, 47 commits.
Output: 12 entries across three headings, 4 commits listed as unclassified.
里面有三种东西真在干活。步骤编号了,模型不会自己发明顺序。分类规则放在下一层的相对路径文件里,这正是规范说的"文件引用保持离 SKILL.md 一层"。再就是输入不清楚时有明确兜底,因为你真正怕的失败不是答空,是答得像真的。
500 行是拿来干什么的
规范建议主文件控制在 500 行内、正文 5,000 token 内。参考仓库正好展示了不这么做会怎样。19 个技能里有三个超了 5,000:claude-api 609 行、26,384 token,skill-creator 7,172,pptx 6,993。另外十六个平均 1,756。
这几个超标的不是失误。claude-api 就是一份在用的 API 参考,作者认这个成本,因为读它就是任务本身。结论要窄一点:600 行正文是一个想清楚的交换,你得知道自己站在哪一边。如果你的正文长,是因为把文档粘进去了,那就把文档挪到 references/,正文只留流程。
先校验,再安装
skills-ref validate ./release-notes
参考校验器会按命名和长度规则检查 frontmatter。装之前先跑,因为校验不过的技能在多数客户端里是静默失败的:它干脆不出现在列表里,你花一下午调模型,问题其实在一个 YAML 字段。
技能不是万能形状
给 agent 加能力有四种形状,解决的问题不同。2026-07-28 版 Model Context Protocol 规范把界线画得很清楚:
| 形状 | 谁触发 | 空载成本 | 适合 |
|---|---|---|---|
| MCP 工具 | 模型自己决定,按带类型的 inputSchema 调 tools/call | 每次会话带全量 schema | 一个有类型参数、结果可验证的动作 |
| MCP 资源 | 应用决定,用 resources/read 读 | 只有发现列表 | 应用取来喂给模型的上下文数据 |
| MCP 提示 | 用户主动选,参数一律是字符串 | 只有列表 | 人有意选择的复用模板 |
| 技能 | 模型按 description 判断,再读文件 | 约 100 token 元数据 | 多步流程、行文规范、脚本、参考资料 |
你想要的是"调这个接口拿 JSON 回来",那就是工具,写成技能只是给别人的工具套了层壳。你想要的是"按这九步、按我们的格式、用这个脚本",那就是技能,硬塞进 JSON schema 的工具没人读得懂。
两者可以叠。装一个 MCP 服务提供带类型的动作,再写一个技能说明先调哪个后调哪个。技能空载约 100 token;服务的 schema 照价计费,用不用都收。
常见问题
文件名必须是大写 SKILL.md 吗? 是。规范点名这个文件,发现机制按目录去扫。小写 skill.md 在遵循规范的客户端里等于不存在。
一个技能能调另一个吗? 不能按引用调。规范里没有 import 机制。实际做法是两个正文都指向同一份 references/ 文件,重复文字只留一处。
能装多少个? 参考集里每个技能元数据约 68 token,一百个大约 7,000 token 空载,能接受。真正的上限是描述撞车:两个技能都说自己"总结文档",流量会不可预测地分掉。
一定要写脚本吗? 不。纯 Markdown 技能合法,很多时候也够。脚本的价值在于某一步是确定性的,否则每次都要从描述里重新推导,漂移和凭空编造的参数就是这么来的。
这是 Anthropic 专属吗? 格式以开放规范形式发布在 agentskills.io,带校验器库,仓库里也附了 Claude Code 的插件清单。把 SKILL.md 当成可移植的文本格式看,别当厂商功能看。
接下来做什么
挑出这个月你已经跟 agent 解释过两遍以上的那套流程。先写 description,用你自己会去搜的词写。再写四步编号。其余全部挪进 references/。跑校验,装上,看它会不会在你没点名时自己触发。不触发就是 description 的问题,正文写再多都补不了路由。
相关:37 个 MCP 工具 schema 的 token 账、自托管 agent 记忆、LiteLLM 按 key 限额。
相关文章
本站文章由编辑人工撰写,收录的工具均经过实测或公开资料核验。文中链接指向工具官网或 GitHub 仓库,仅作信息参考,不构成付费推广。