SKILL.md 不再是某家厂商的私产：我按新规范体检了自己的 114 个技能

【摘要】10 月 22 日，Anthropic 把 Agent Skills 捐给 Linux 基金会旗下的 Agentic AI Foundation，70 多个平台、约 100 万个 skill、累计 2.8 亿次安装，都开始读同一份格式规范。我照着规范原文写了个检查脚本，扫了自己的技能库：114 个技能，格式错误 0 个，但有 98 个用了规范外的顶层字段，还有 4 个正文超了 5000 token。这篇讲体检结果，也讲清一件事——description 才是整个机制里你唯一能控制的开关。

目录

一、事件：捐出去的是名字、logo、GitHub 组织和一个域名
二、真实的成本在哪：description 是唯一常驻上下文的一段文字
三、体检结果：我的 114 个技能，格式没错，元数据超了
四、三个层级，四个判断标准
五、还没解决的两件事
六、接下来我会怎么改

一、事件：捐出去的是名字、logo、GitHub 组织和一个域名

10 月 22 日，Anthropic 宣布把 Agent Skills 捐赠给 Agentic AI Foundation（AAIF）——Linux 基金会旗下的机构，去年 12 月由 Anthropic、Block、OpenAI 共同发起，此前已经托管了 MCP 和 AGENTS.md。

捐出去的东西很具体：Agent Skills 的名称、logo、GitHub 组织，以及 agentskills 这个域名。没有捐的：Anthropic 自己的产品文档和示例仓库。也就是说，查具体用法还是得看厂商文档，基金会不替你维护教程。

规范本身那天没有任何变化——还是六个 frontmatter 字段，没有版本号，没有打标签的发布。变的是归属：从一家公司的产品约定，变成了由 Anthropic、Google、OpenAI 的工程师以个人身份共同维护的标准。Lead Maintainers 是 David Soria Parra 和 Mahesh Murag。

官方口径的数据是：70 多个 agent 平台已接入，官方点名 ChatGPT、Cursor、GitHub Copilot、VS Code；已发布约 100 万个 skill，累计安装近 2.8 亿次。

这些数字全是 Anthropic 自己报的，没有第三方核对，安装次数怎么算也没说。平台名单可以验证（OpenAI 和微软的产品确实在列表里），具体数字当量级看就好。

一个可以传播的观点句：

当一份格式从"某家的实现细节"变成"多家共同维护的契约"，你为它写下的东西才真正开始保值。

二、真实的成本在哪：description 是唯一常驻上下文的一段文字

规范里最该被认真读的部分，是加载方式是三层渐进披露：

这张表解释了一个反直觉的事实：你装的每一个 skill，都会在每次对话开始时收费——哪怕这次任务跟你完全无关。

这就把 description 的分量顶到了第一位。它是唯一一段对所有 skill 常驻上下文的文字，agent 只能靠它来判断"这个任务要不要激活你"。写得太短，匹配不到；写得太长，每个 skill 都得多摊一份 token。

规范给 description 的上限是 1024 字符。但这只是上限，不是建议值。

一个 skill 写得好不好，一半写在 description 里，另一半写在它敢不敢把正文拆进 references/。

三、体检结果：我的 114 个技能，格式没错，元数据超了

我没跑官方校验工具（规范仓库自己标注了"For demonstration purposes only"），而是照着规范原文把每一条约束写成了检查脚本，扫了自己的技能库。

先说结论，比预想的复杂：

技能总数            114 个（7 个顶层 + 107 个分类子目录）
缺 SKILL.md          0
name 与目录名不一致   0
description 缺失      0
description 超 1024   0
正文超 5000 token    4 个
正文超 500 行        7 个
常驻 metadata 估算    ~6359 token
全部正文估算         ~144905 token

格式层面几乎全绿。但往下看，暴露了两个真问题。

问题一：98 个技能用了规范外的顶层字段

规范只认六个字段：name、description、license、compatibility、metadata、allowed-tools。其余的顶层字段，规范没有定义——换一个平台不一定能被识别。

我这儿的情况：

version           98 次
author            93 次
platforms         84 次
prerequisites     16 次
dependencies       2 次
tags               2 次
triggers           2 次
（另有 dependency / setup / title / environments / read_when /
  homepage / required_credential_files 等长尾，各 1 次）

前三个占了绝大多数。问题不在于这些字段本身没价值——author、version 对人很有用。问题在于位置错了。规范明确留了扩展位：

metadata:
  author: your-name
  version: "1.0"

放进 metadata，跨平台就有明确语义；放在顶层，换个平台就是未知字段。

问题二：常驻 metadata 已经 6359 token

这是我这次体检最意外的数字。

114 个技能，每个 name + description 估算约 100 token，加起来 ~6359 token——这是我每次对话开始时，无论任务是什么，都已经付出的固定成本。

对比一下：全部 114 个技能的正文字积是 ~144905 token。按规范的三级加载，正常情况下只有命中的那 1～2 个会被读进来，这个数字不会爆。

但那 6359 token 是无条件的。

我的 description 分布：

中位数    56 字符
最长     445 字符（self-improving-agent）
超 1024   0 个

中位数 56 字符挺健康，但头部有偏长的。规范建议每个约 100 token，对应约 160 字符。我的中位数远低于此，说明大部分 skill 写得很克制；但少数几个写到 300～450 字符的，等于在给每个 skill 的常驻成本加权。

如果我把这 114 个 skill 全部按 100 token 规范写，常驻成本就是 ~11400 token。 我现在的 6359，是靠"大部分写得短"省下来的，而不是靠"数量控制"。

一个反直觉的发现：数量不是主要矛盾，体量才是

我原本以为 114 个技能是"装太多"的体现。算完才发现不是：

• 114 个技能如果每个 description 写成 56 字符，总成本 6359 token —— 对比一个不装任何 skill 的裸 Agent，这是可接受的
• 但如果我只装 20 个、每个 description 写 400 字符，成本就是 8000 token —— 比现在还贵

装得多不等于贵，写得长才贵。 数量只影响"匹配准确率"和"维护成本"，不影响常驻 token 的量级；单个 description 的长度才是线性因子。

正文超标的 4 个，按体量从大到小是：一个群晖容器部署流程、一个网关运维流程、一个路由审计流程、一个 Agent 自身配置流程。

这四个都是"一次要讲完一整套操作流程"型的 skill——正是规范建议拆进 references/ 的对象。它们不是写得差，是没拆。

四、三个层级，四个判断标准

规范的三层加载机制，实际用起来是一套判断题。把体检结果对进去，我整理出四条：

标准一：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.

反面例子：

Helps with PDFs.

差别不在长度，在有没有触发词。“Use when…” 后面那些词，是 agent 拿去和用户的话做匹配的字面依据。你写 “Use when the user mentions PDFs, forms, or document extraction”，用户说"把这几个 PDF 的表填了"，就匹配得上。

标准二：正文超过 5000 token 就该拆

规范建议正文 < 5000 token / < 500 行，超了就往 references/ 搬。

我那 4 个超标 skill，拆法很直接：把"完整操作步骤"留在正文，把"字段清单 / 返回结构 / 错误码表 / 边界情况"搬进 references/xxx.md，正文里用相对路径引一下。

Agent 需要细节时会自己去读那个文件——这正是第三层加载存在的意义。不拆的话，那 8335 token 会在每次激活时一次性砸进上下文。

标准三：平台专属信息收进 metadata

version / author / platforms / prerequisites 这些，全部挪进 metadata：

---
name: synology-container-deployment
description: 在群晖 NAS 上安全部署 Docker 服务...
license: Apache-2.0
metadata:
  author: your-name
  version: "1.0"
  platforms: [synology-dsm]
---

迁移是纯机械的，metadata 里的键是大小写敏感的字符串，重复的保留第一个合法的并告警，不会导致 skill 加载失败。

标准四：装别人的 skill，等于把脚本放进你的环境

规范文档自己也点明了这点：skill 可以带可执行代码，allowed-tools 字段还能预先批准工具调用。

而 AAIF 的路线图里，"给写 skill 和装 skill 的人的安全指南"还是待办状态。

也就是说，在指南出来之前，这件事不会自动变好。装第三方 skill 前，至少先看一眼 scripts/ 里有什么。标准不提供沙箱，脚本是以你的权限跑的。

一个能传播的观点句：规范统一了格式，但没统一信任。装 skill 之前的那 30 秒阅读，是你自己给自己加的沙箱。

五、还没解决的两件事

第一，跨平台复用不等于跨平台对齐。

70 多个平台都"支持"Agent Skills，但渐进式披露这三层未必每家都做全了。格式统一了，能力没对齐。跨工具复用之前，还是得在目标平台上跑一遍验证。

第二，治理迁移还在进行中。

规范仓库的 README 目前仍写着"最初由 Anthropic 开发"，没提 AAIF。捐的是资产，实际治理要慢慢搬。路线图里的版本化发布、提案流程都还没落地，短期内规范怎么变缺乏可预期的节奏。

六、接下来我会怎么改

具体到我自己这份技能库，四件事：

1. 把 98 个 version / author / platforms 挪进 metadata。 纯机械操作，用脚本批量改，改完跑一遍校验确认没有 skill 因为字段位置变了而加载失败。

2. 拆那 4 个超标的正文。 优先那个群晖容器部署流程（8335 tok）和网关运维流程（7381 tok）——这两个是激活一次就吃掉大半个上下文窗口的量级。

3. 给最长的几个 description 收一遍。 445 字符那个挪进 metadata 或者压缩。目标是把常驻成本压到 5000 token 以内。

4. 装第三方 skill 前先看 scripts。 这条不靠工具，靠习惯。

有一件事我得说清楚：这次体检里所有的 token 数字都是估算。我用中英文字符混合的启发式公式算的，和实际分词器的结果会有出入。只看量级，不看精确值。

规范原文在 agentskills 站点的 specification 页面，建议直接读规范，别只看某家产品的文档——规范才是跨工具复用的依据。

你现在有多少个 skill？给它们做过体检吗？

欢迎在评论区聊聊你踩过的坑——尤其是"description 写太长导致每次对话都多付钱"这类隐形的成本。我自己也还在摸索中。