技能文件解剖:一份 SKILL.md 里必须有什么

📘 教程 2026-11-22 约 24 分钟阅读

技能装上了,模型从不打开,于是正文越写越长,指望长度能修好路由。

📜 目录

技能装了却从不被调用,看起来像内容问题,其实是路由问题。模型不会去翻你的文件夹。开工时它只看到每个技能的一行:名字和描述。那一行是它打开后面全部内容的唯一理由。

所以真正要问的不是"文件里怎么把提示词写好",而是:运行时到底读什么、推迟读什么、推迟的那部分里必须有什么,才能让一套流程被一个完全没参与写作的东西读懂还照着做完。

下面是 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 限额。

相关文章

延伸阅读 · 含推广链接

API 账单分散在几家平台时,续费和管理都费神。合到一个账号下,成本和额度一眼看得清。

合并到一个账号 →

相关文章
2026-08-13
Cursor Rules 示例 2026:Python、React、数据工程的 12 条真实规则
2026-08-11
LLM安全2026:OWASP十大LLM应用风险详解与修复
2026-11-02
本周GitHub Stars排行:Codex涨1865星领跑
2026-08-01
LLM微调工具包对比:Unsloth vs Axolotl vs TRL
2026-08-07
AI老照片修复:用开源工具让旧照片重获新生
2026-08-01
本地LLM搭建:Reddit网友真实推荐

本站文章由编辑人工撰写,收录的工具均经过实测或公开资料核验。文中链接指向工具官网或 GitHub 仓库,仅作信息参考,不构成付费推广。

💬 评论 (0)

暂无评论,来说两句吧~

登录后评论