Agent Skills 开放规范精读笔记

Agent Skills, "Specification," agentskills.io, 2026. [Online]. Available: https://agentskills.io/specification。源码与参考实现 agentskills/agentskills，固定提交 69ef37e9（2026-08-09），代码 Apache-2.0、文档 CC-BY-4.0。格式最初由 Anthropic 开发，后作为开放标准发布（home.mdx「Open development」节）。

一句话定位：Agent Skills 是一份刻意做小的开放格式——一个技能就是一个目录加一份带 YAML 头的 SKILL.md。规范只规定「包里装什么」，不规定「包放哪、谁可信、怎么分发」。它的全部工程价值压在一个结构性约定上：客户端每个会话只付极小的常驻代价（每个技能一个名字加一句用途），就能知道「柜里有什么」；真正的指令和附件推迟到用得上时再读。

总类比：公司手册柜。员工（客户端 Agent）上岗时不会把柜里所有手册摊上桌，只扫一眼每本的书脊（name + description，即目录卡）。遇到对口的活，才抽出整本来读（激活时加载 SKILL.md 正文）。手册里写「见附录 B」时，才去翻附录（scripts/ references/ assets/ 按需加载）。书脊编号必须和抽屉标签一致（name = 目录名）。新书上架前有图书管理员检查格式（skills-ref validate）。封底夹着一张预授权门禁卡（allowed-tools，实验性），但各单位认不认这张卡并不统一。

怎么读这篇笔记：

• 三拍结构：每个机制按「类比 → 机制 → 原型实景」走。
• 原型：实景取自配套最小原型 assets/agent_skills_lab.py。它是纯标准库、474 行的确定性原型，已随笔记入库：--selftest 秒级跑完，--break B1..B5 复现破坏性实验，--audit-repo 只读审计本仓技能。文中所有日志均为实际运行输出。
• 配套产物：Agent Skills ↔ negentropy 机制映射报告。
• 引用记号：
  • S:行号 指 specification.mdx。
  • G:行号 指 客户端实现指南 adding-skills-support.mdx。
  • V: / P: / T: 分别指 skills-ref 的 validator.py / parser.py / prompt.py。
  • 以上行号均以固定提交为准。

#1. 它要解决什么问题：没有手册柜的新员工

首页开宗明义：Agent 能力越来越强，却常常「don't have the context they need to do real work reliably」（home.mdx「Why Agent Skills?」）。给 Agent 补上下文，传统上只有两条路，各有一个结构性死穴：

• 什么都不给：通用模型不知道你们团队的报销流程、代码评审口径、PDF 表单的坑。能力再强也只能靠猜。
• 什么都塞进开场白：把全部操作手册拼进 system prompt。上下文成本跟「装了多少」挂钩，而不是跟「用了多少」挂钩。客户端指南的账算得很直白：装 20 个技能的 Agent，不该为 20 套完整指令预付代价（G:30）。

Agent Skills 的破局点，是把成本函数的自变量从「装机数」换成「使用数」。它用一个几乎不需要基础设施的载体来做这件事：文件夹。由此引出六条设计规格，规范的每个决策都能映射回其中一条：

#2. 全貌：两相与因果脉络

Agent Skills 天然分成两相：

• 作者相：写手册、打包、上架检查。
• 运行相：员工上岗扫书脊、抽整本、翻附录。

规范正文主要管作者相的「包里装什么」。运行相的细节（去哪扫、同名谁赢、激活后怎么保护）几乎全在非规范的客户端实现指南里。这一区分是理解全篇的钥匙：AGENTS.md:14-17 明言规范正文是唯一权威，「Explanatory documentation, examples, tests, and implementations do not add requirements to the format」。

图 1 · 运行相：发现 → 解析 → Tier 1 目录 → Tier 2 激活 → Tier 3 资源。图源：.mmd · 交互版 HTML（下载到本地打开）

#2.1 最重要的几个部分（分层矩阵）

#2.2 核心关系与因果脉络链

观察：Agent 缺团队/领域的程序性知识；全塞进 prompt 则成本随「装机数」线性膨胀、无关指令干扰行为
  ↓ 归因
成本函数的自变量选错了：上下文开销应随「使用数」而非「装机数」增长
  ↓ 设计规格（§1 六条：可移植 × 按需 × 可寻址 × 可触发 × 可校验 × 格式小）
  ↓ 机制
作者相：目录即单元（SKILL.md = YAML 头 + Markdown 正文 + 可选附件）→ 上架校验
                         ↕ 唯一接口：name + description
运行相：Tier 1 目录（常驻）→ Tier 2 正文（激活时）→ Tier 3 资源（被引用时）
  ↓ 证据闭环
⚠ 材料内无量化实验：证据形态 = 规范文本 + 参考实现 + 生态采纳（46 家客户端展示）
  → 本笔记用原型实测补上「机制是否自洽」这一环（§9）

#2.3 基础层 vs 学习焦点

(a) 前置门槛（Phase 0 由 Learner Subagent 代管自测，三题自评「高 / 中高 / 中高」）：

• YAML frontmatter：key: value 语法，以及「未加引号的值里再出现冒号 + 空格即非法」这一坑。
• 上下文窗口与 Token 预算：模型一次能看到的文本总量上限。
• 文件系统即接口：用约定文件名分发能力，任何能读文件的 Agent 都能消费。

自测暴露的唯一认知难点是「冒号坑只在冒号后跟空格时触发」。补课建议一句话：先读 G:117-126 的 malformed YAML 一节，再看 §3 的原型实测。

(b) 最值得学的五个焦点（按价值排序）：

1. 三级渐进披露的成本结构：全篇的存在理由。
2. description 即路由：激活质量几乎完全由一句话决定。
3. name = 目录名：借文件系统白拿唯一性。
4. 规范与实现的权威边界：遇到分歧以谁为准。
5. 客户端指南的非规范建议：信任门、同名优先级、压缩豁免。真实系统的安全性多半取决于这一层。

(c) 批判性边界：见 §10（五条材料没有证明的事）。

#3. 机制一：技能包——目录即单元，SKILL.md 即契约

类比：一本手册就是一个抽屉。抽屉标签（目录名）与书脊编号（name）必须一字不差；书脊上印两行字，一行名字、一行「何时用我」；正文写操作步骤；附录另装。图书管理员上架前只查书脊和格式，不审内容好坏。

机制：规范只有一个必需文件和两个必填字段（S:8-32）：

• 正文与可选目录：正文「no format restrictions」，但激活时会整份加载，所以长内容应拆到被引用的文件里（S:176-185）。scripts/ references/ assets/ 三个可选目录只是组织约定，不是强制结构（S:187-214）。
• 文件引用：一律用相对技能根目录的路径，并「Keep file references one level deep from SKILL.md」（S:226-237）。

图 2 · 作者相：技能包结构 × skills-ref 三命令 × 规范 ↔ 实现分歧。图源：.mmd · 交互版 HTML（下载到本地打开）

为什么 name 必须等于目录名（规范没写动机，以下是 Mentor 推演，已由原型实证）：

• 唯一性：同一父目录下不可能有两个同名子目录，所以 name = 目录名把文件系统的唯一性白送给了技能身份。这是格式层唯一的唯一性保证，规范没有全局命名空间。
• 可寻址：知道名字就能推出路径，用户用 /skill-name 显式激活（G:260）、安装与卸载都依赖这一点。

拔掉这条约束，身份就退化为「谁先被扫到谁算」。§9 的 B2 实测显示，同一仓库在顺序扫描和逆序扫描下会激活出两份不同的正文。

原型实景（实际运行输出，--selftest 节选）：

[M1 解析]
  ✔ 行锚定切分：值内的 '---' 不截断 frontmatter
  ✔ 未加引号的冒号：严格模式拒绝，宽容模式按引号串重读并告警
[M2 校验]
  ✔ 规范反例 PDF-Processing / -pdf / pdf--processing 与 65 字符名均被拒
  ✔ 目录名一致、description ≤1024（1024 过 / 1025 拒）、compatibility 1–500（空串与 501 均拒）
  ✔ 未知字段 disable-model-invocation 在严格校验下被拒（客户端指南却引用它——分歧 #3）
  ✔ 名称字符集分歧：按规范列举的 a-z/0-9 拒「技能」，按 skills-ref 的 isalnum 口径放行

原型刻意实现了两种「口径」：

• 行锚定切分（split_frontmatter）对照 skills-ref 的 split("---", 2)。
• 规范列举字符集对照 skills-ref 的 isalnum（validate 的 unicode_names 参数）。

两处分歧不是纸面推演。用固定提交的真实 skills-ref 跑探针技能（uvx --from "git+…agentskills@69ef37e9#subdirectory=skills-ref" skills-ref validate，临时环境，不入仓），实测输出如下：

== 技能/            → Valid skill: .context/skills-ref-probe/技能
== md-tables/       → Validation failed …
  - Invalid YAML in frontmatter: while scanning a quoted scalar
    description: "Converts Markdown tables
found unexpected end of stream
== extra-field/     → Validation failed …
  - Unexpected fields in frontmatter: disable-model-invocation. Only ['allowed-tools', 'compatibility', 'description', 'license', 'metadata', 'name'] are allowed.

• md-tables 的 description 是合法的引号串，里面含 ---。skills-ref 的非行锚定切分从值的中间切断了 YAML。
• 同一个 extra-field 探针的 allowed-tools: Read, Write 用的是逗号分隔，违反规范的「space-separated」，validate 却一字未报：skills-ref 根本不校验这个字段的语法。

#4. 机制二：三级渐进披露——上下文的成本结构

类比：书脊墙是租来的固定墙面，每进一本书就多占一格，不管这本一年被翻几次；抽出来的整本和翻开的附录才是按次付费。渐进披露把「按藏书付费」的部分压到最小，但没有把它变成零。

机制：规范给出三级预算（S:216-224）：

客户端指南把这三级落成五步流水线（G:32-335）。其中决定成败的是几条「契约」：

• 目录格式不限，XML / JSON / 列表都行（G:165），但要附一段简短的行为说明，告诉模型怎样激活（G:196-218）。
• 激活两种路径：
  • 读文件激活：模型用自带读文件工具读 location（G:244）。
  • 专用工具激活：注册 activate_skill（G:246-252）。指南特别提示：name 参数应做枚举约束以防模型编造技能名；「If no skills are available, don't register the tool at all」（G:254-256）。无技能时也不输出空目录（G:230-232）。
  • 这两条合起来是一个目录—激活契约：目录承诺的激活路径必须真实存在，反之亦然。
• 激活后：资源只列清单、不预读（G:304-308）；技能内容应豁免上下文压缩（G:318-325）；重复激活去重（G:327-329）。

原型实景：同一组 4 个任务（PDF 表单 / Markdown 表转 CSV / 代码评审 / 无关闲聊），在 19 个技能的库上跑会话账本（run_session）：

[M4 目录]
  ✔ 目录 1113 tokens / 19 技能 ≈ 59 tokens/技能；无技能时不出目录
[M5 激活]
  ✔ 激活注入正文 + 资源清单但不预读资源内容；重复激活被去重
[M6 资源]
  ✔ 被正文引用的资源可载；嵌套引用（DEEP.md）与未引用资源拒载；../ 与绝对路径越界拒绝
[会话账本]
  ✔ 渐进披露 {'catalog': 1113, 'instructions': 203, 'resources': 1005, 'total': 2321} vs 全量预载 total=39222（16.9×）

读法：

• 59 tokens/技能落在指南给的 50–100 区间内。原型用 ceil(字符数/4) 代理计数，材料没有给 tokenizer 口径。
• 16.9× 是玩具域数字，只证明方向（成本随使用数而非装机数增长），不可外推为真实收益。
• 账本里 Tier 1 的 1,113 tokens 是每个会话都要付的「固定墙面」：装机数翻倍，它就翻倍。

#5. 机制三：description 即路由——触发全靠一句话

类比：员工只看书脊决定抽不抽这本。书脊只写「帮忙处理 PDF」，他拿不准该不该伸手；写清「提取表格、填表单；用户提到 PDF、表单、文档提取时用」，他才会去抽。

机制：

• 由模型判断，而非关键词匹配：指南明言多数实现依靠模型自身判断激活，「rather than implementing harness-side trigger matching or keyword detection」（G:240）。于是 description 成了激活决策的唯一输入。作者指南直说：「The description carries the entire burden of triggering」（optimizing-descriptions.mdx:15）。
• 写法要求：规范要求描述写「做什么 + 何时用」并含关键词（S:95-96），并给出正反例（S:99-107）。
• 格式合规 ≠ 能被触发：反例「Helps with PDFs.」完全合规（非空、远小于 1024），validate 一定放行，却几乎不可能被触发。
• 作者侧评测方法：约 20 条查询（8–10 条应触发、8–10 条不应触发），每条跑 3 次，触发率阈值 0.5，按 60/40 切分训练集与验证集，迭代约 5 轮后按验证集通过率选最佳版本，而不是选最后一版（optimizing-descriptions.mdx:39,89,139,158,160）。

原型实景：原型用确定性关键词重叠替身 mock_model_pick 代替模型判断。这只为可复现，不代表真实模型的行为方式。规范的正反例原文直接进场：

[M5 激活]
  ✔ 好描述（规范正例）命中 PDF 任务；只装「Helps with PDFs.」时同一任务落空；无关任务不激活

同一任务「Extract the tables from this quarterly report PDF and fill the attached form」：

• 规范正例描述重叠 5 个关键词，命中。
• 只装反例时重叠 1 个，低于阈值，任务落空。

退化完全静默：没有报错，技能形同不存在。

#6. 五条底层规律（正交分解）

#规律 1：目录即单元（Package as Directory）

最简解释：一个技能就是一个文件夹，谁能读文件谁就能用。 理论锚点：[3]（Anthropic 首发文把技能定义为「organized folders of instructions, scripts, and resources」）；Unix「一切皆文件」的接口哲学。 解决什么问题：没有它，每家产品要各自发明分发 API，技能只能两两适配。 演示：规范只需 1 个必需文件、2 个必填字段（S:8-32）；46 家客户端展示（docs/snippets/clients.jsx）构成采纳面。反面代价：一旦格式膨胀（AGENTS.md：「new requirements impose costs on every implementation」），每一家实现都要跟着付成本。

#规律 2：身份借文件系统（Identity by Filesystem）

最简解释：书脊编号等于抽屉标签，同一个柜里就不可能有两本同号手册。 理论锚点：[6]（NFKC 归一化，skills-ref 在比较前先归一，V:37,61）。 解决什么问题：没有它，身份由扫描顺序决定，不同客户端、不同文件系统会激活出不同的技能。 演示：§9 的 B2。拔掉目录一致校验后，同一仓库顺序扫描激活 PROJECT code-review rules…，逆序扫描激活 IMPOSTOR rules…。

#规律 3：成本随使用而非装机（Pay per Use, not per Install）

最简解释：书脊常驻、整本按需、附录更按需。 理论锚点：[7]（渐进披露作为界面设计原则）；[9]（长上下文中的信息定位随长度退化，塞得越多越难用）。 解决什么问题：没有它，上下文成本与装机数线性绑定，技能生态越大越用不起。 演示：§4 的账本，渐进披露 2,321 vs 全量预载 39,222 tokens（16.9×，玩具域）。反面：B1 实测 16.3×（含破坏样本）。

#规律 4：路由即描述（Routing by Description）

最简解释：模型只凭一句话决定用不用你，那句话就是你的全部广告位。 理论锚点：[10]（大规模工具库须靠检索或描述路由选工具，规模上去后靠「全列给模型看」不可持续）；optimizing-descriptions.mdx:15。 解决什么问题：没有好描述，技能合规却永远不被触发（静默退化）。 演示：§5 的正反例对照（5 词命中 vs 1 词落空）。反面：B3，一条 12,159 字符的描述让目录从 1,206 涨到 4,285 tokens（+255%），单条等于其余 20 条之和的 2.4×。路由位被一条广告吃掉。

#规律 5：信任与执行不在格式内（Trust Lives Outside the Format）

最简解释：手册格式只管排版，不管这本手册是不是外人塞进柜里的。 理论锚点：[11]（OWASP LLM01 提示注入）；G:89-91（项目级技能可能来自不可信仓库，建议信任门）。 解决什么问题：没有这层意识，客户端会把「格式合规」误当成「内容可信」。 演示：§9 的 B5。目录构建关掉转义后，一条合规 description 在模型视图里伪造出第 21 条 admin-override 条目，注册表里却只有 20 条。规范对 description 内容零约束，转义是客户端的责任（skills-ref 在 T:43,46 做了）。

正交声明：五条规律恰好覆盖**封装（打包）/ 身份（寻址）/ 成本（披露）/ 路由（触发）/ 信任（执行）**五个维度——这本身就是 Agent Skills 的领域地图。

#7. 三个核心争议

#争议 1：严格校验 vs 宽容解析——图书管理员该退稿还是先上架？

通俗版：

• 严格派图书管理员：书脊编号和抽屉标签不符，退回重做。
• 宽容派柜子管理员：先上架，贴张黄条提醒，别让员工无书可看。

分歧为什么产生：

• 两派看到的失败模式不同。skills-ref 只有硬失败一档（V:150-177）；客户端指南则刻意放宽，名称与目录不符、超长都只告警、照样加载（G:128-141），对 malformed YAML 还建议「补引号重试」的回退（G:117-126）。
  • 严格派看到的是：放宽会让身份歧义重新出现。原型实测，宽容模式下 B2 的冒名顶替照样发生，只多一行 WARN。
  • 宽容派看到的是：别家客户端写出的技能大量「技术上非法、别人的解析器却接受」，一刀切会让跨客户端生态碎掉。
• 生态已经分叉：Google Antigravity 把 name 设为可选，缺省取文件夹名 [12]，这与规范「必填」直接冲突。
• 本质：这是互联网协议史上「鲁棒性原则」的老争论。IAB 的 RFC 9413 [8] 的立场是：静默容忍错误输入会随时间侵蚀互操作性，可更新的实现应走向「virtuous intolerance」。

难以克服吗：工程问题为主。可对冲（作者侧严格校验 + 客户端宽容加载 + 诊断必须可见），无法消除：只要存在多个独立实现，就一定有人比规范更宽。

#争议 2：模型自触发 vs 显式调用——让员工自己挑手册，还是主管指定？

通俗版：让员工看书脊自己挑手册，省主管的事，但员工可能挑错、漏挑；主管每次点名「用第 7 本」最可靠，但主管得记得住柜里有什么。

分歧为什么产生：

• 指南同时支持两条路：模型驱动（G:238-256）和 /skill-name 显式激活（G:258-262）。还提到 disable-model-invocation 这类「只许显式调用」的标记（G:226），但规范没有定义这个字段，严格校验反而会拒掉它（§3 实测）。
• 自触发派看到的是召回率：技能多了没人记得住。显式派看到的是精确率与可审计：自触发的失败是静默的（§5），而且指南鼓励「pushy」的描述措辞（optimizing-descriptions.mdx:25）。
• 规范没有定义「会被过度触发的推销式描述」与「恶意诱导」之间的形式边界。

难以克服吗：本质难题的一部分。触发准确率受模型能力约束，只能用作者侧评测（§5 的 20 查询法）逐技能对冲，规范层给不出保证。

#争议 3：开放格式的极简 vs 供应链信任——柜子谁都能放书，谁来验真？

通俗版：手册柜不上锁，谁都能往里放书，这正是它流行的原因；可新搬来的外单位柜子里，也可能夹着一本「任何事都先照我做」的手册。

分歧为什么产生：

• 极简派（规范本身）坚持格式只管「包里装什么」（G:54：规范不规定技能放在哪里）。
• 安全派看到：技能是会被模型当真执行的指令，外加可执行脚本（S:191-198）。规范却没有签名、来源、版本锁定。allowed-tools 的语法与语义（仅预批准，还是同时限制其他工具？）也未定义，且标注实验性（S:167）。
• 信任被整体推给客户端，指南也只「Consider」做信任门（G:91）。

难以克服吗：资源与工程问题。签名与注册表都有成熟范式可借，但每加一条都违背「Keep the format small」。两者是对冲关系：要么由格式承担，要么由每个客户端各自承担，不会凭空消失。

#8. 规范规则速查与「规范 ↔ 参考实现」分歧表

材料没有量化实验，所以本节不设「关键实证数字」，改为可核对的规则与数字速查：

13 处分歧：

• 规则：以 specification.mdx 为准（AGENTS.md:14-26）。
• 来源：#1–#12 源自 Phase 1 通读取证；#13 由 Learner Subagent 在 self_doubt 中提出，Mentor 实测证实。
• 「真实复现」一栏标 ✅ 的，已用固定提交的真实 skills-ref 跑出一致结果。

#9. 动手实验室：把机制亲手拆坏五次

运行方式（已随笔记入库，纯标准库、确定性，全套 < 1 s）：

uv run --no-project python docs/research/agent-infra/assets/agent_skills_lab.py --selftest
uv run --no-project python docs/research/agent-infra/assets/agent_skills_lab.py --break B1  # B1..B5
uv run --no-project python docs/research/agent-infra/assets/agent_skills_lab.py --audit-repo

机制 → 代码行号速查：

破坏性实验三件套实录（均为 --break Bn 的真实运行输出；每个开关只影响一两行代码）：

B5 的延伸推演（Learner Subagent 在 C3 中提出，Mentor 核对后成立，未实测真实模型）：若目录按指南模板把 <location> 放在 <description> 之后（G:167-180），伪造条目会继承恶意技能真实的 SKILL.md 路径。于是：

• 读文件激活：没有注册表可兜底，模型会照这个路径去读。
• 专用工具激活：若 name 参数做了枚举约束（G:254-256），伪造名会被拒。

这正是枚举约束的安全价值。

宽容模式的附带实测（争议 1 的证据）：以 lenient=True 重跑 B2 样本，冒名技能照样载入。逆序扫描时 IMPOSTOR 同时遮蔽项目级和用户级两本 code-review，防线只剩两行 WARN：

逆序 'IMPOSTOR rules copied from ano' ["WARN  project:zz-review-copy — name: 'code-review' must match directory 'zz-review-copy'", "WARN  collision 'code-review': keep project:zz-review-copy, shadow project:code-review", "WARN  collision 'code-review': keep project:zz-review-copy, shadow user:code-review"]

本仓审计（--audit-repo，只读扫描 .agent/skills/）：

合计 11：校验通过 11，缺「何时用」 3，逗号分隔 allowed-tools 10，带可选目录 0

逐项对照与处置建议见 091 映射报告。

原型位于 docs/research/agent-infra/assets/，已随笔记入库（沿 142 / 144 先例）；真实 skills-ref 探针位于 .context/（gitignored），可按 §3 命令复刻。

#10. 批判性边界（材料没有证明的事）

1. 渐进披露的收益没有任何量化证据。
   • 「~100 tokens」「< 5000 tokens」都没有 tokenizer 口径，规范与指南的数字还不一致。
   • 材料里没有一个「目录规模 × 触发准确率」或「预载 vs 渐进」的测量。
   • 本笔记的 16.9× 来自玩具域，只证明方向。
2. 目录本身的规模上限未被讨论。
   • 指南的论证锚点是「20 个技能」「dozens」（G:30、G:184）。
   • 到数百个技能时，Tier 1 常驻成本（每个 ~100 tokens）会重新变成瓶颈。
   • 规范没有目录预算、分页或检索式披露的任何设计。
3. 触发可靠性没有规范级保证。
   • 激活完全依赖模型判断，description 的写法只有「should」。
   • 评测方法在作者指南里，没有一致性测试套件；skills-ref 也不测触发。
4. 没有信任、来源与版本模型。
   • 没有签名、没有版本字段（metadata.version 只是示例）、没有规范版本号；仓库无 tag、无 release。
   • allowed-tools 的语法与语义未定义。
   • 同名冲突的处理只在非规范指南里；命名空间只保证到单个父目录内。
5. 参考实现不是一致性判据。
   • skills-ref 自称 demo，已与规范漂移（13 处分歧），且不接受代码贡献（CONTRIBUTING.md）。
   • 「过了 validate」既不等于「合规」（逗号分隔的 allowed-tools 照过），也不等于「可用」（「Helps with PDFs.」照过）。

另有若干未定义项，不单列成条，但工程上会咬人：

• 文本编码与换行符（UTF-8 / BOM / CRLF）。
• YAML 版本与子集。
• 「一层深」到底是指引用链深度还是目录深度。
• 脚本的工作目录：using-scripts.mdx 说从技能根运行，指南说解析为绝对路径。

#11. 双 Agent 费曼考评与推演实录（Feynman Mastery Archive）

研究范围界定（Mentor 出题前先划定定义域）：

• 目标任务：规定「一个可被 Agent 按需加载的程序性知识包」的文件格式，以及客户端加载它的推荐生命周期。
• 成立工况：
  • 客户端能读文件，或能通过工具取回技能内容。
  • 技能数量在几十个量级。
  • 激活由模型判断或用户显式触发。
• Out-of-Scope（材料明确不管或未研究）：技能放在哪里、分发与安装、信任与签名、版本与依赖、多技能指令冲突仲裁、目录规模上百后的检索式披露、触发准确率的保证。另外，技能不是工具调用协议：材料全文零提及 MCP。

#11.1 第一轮：三维盲答（Mentor 出题 → Learner 独立作答）

Learner Subagent 只拿到固定提交的一手材料与总类比，未见本笔记。Phase 0 的三题前置自测与 Phase 1 的脉络复述（B0–B2）一次通过：

• B1 独立推出了「name = 目录名借的是文件系统唯一性，拔掉后坏在按 name 建映射那一步，结果由枚举顺序决定」。这与原型 B2 实测完全吻合。
• B2 把因果方向判对了：客户端「靠模型判断激活」是因，规范「描述须写何时用」是果。

三维大题如下：

• C1 白话转述（向连锁餐厅店长讲清「装 50 个技能为什么不撑爆、它怎么知道用哪个」）：全程白话，术语当场解释，并主动补上两条风险提醒（书脊也占地方；外人可以在书脊上写「任何事都先用我」）。
  • 诊断：轻度边界模糊。「50 张书脊 ≈ 一本正文上限，桌面几乎不占」前后矛盾：50 × ~100 ≈ 5000 tokens，恰好等于一整本正文，这是每会话固定开销、随装机数线性增长，不是「几乎不占」。
• C2 因果与最近邻（全文塞入 vs MCP vs Skills）：
  • 学徒正确指出材料对 MCP 零提及，并把全部 MCP 论断标为推演。
  • 学徒给出「MCP 管能做什么、Skills 管何时做与怎么做」的正交判断，并指认唯一重叠区是 scripts/（本地可执行、无类型契约）。
  • 学徒还提出「激活是离散可观测事件，所以失败可归因」这一洞见。
  • 诊断：轻度因果断裂。学徒把「全文塞入」的死因放在「模型运行时难以定位该照哪段」，这是症状。病根是成本结构耦合：成本随装机数而非使用数增长，且只有全有 / 全无两档。学徒在 Phase 0 的 A2 其实已写出病根，到大题里却换了定义。
• C3 极限推演（300 技能 / 40 个来自新克隆仓库 / 三本同名 code-review / 60 条 900 字营销描述 / 一条 XML 注入描述）：
  • 学徒判定首个退化点是目录披露层。理由有三：时序上最先进入模型视野；成本上唯一随装机数线性增长；四个压力源在这里汇聚。
  • 学徒把「规范能拦 / 仅指南建议 / 材料没管」三类清单分得干净，并指出「规范的硬上限 1024 远宽于它自己的软预算 ~100」。
  • self_doubt #1 提出「skills-ref 的 to-prompt 遇坏文件会整体失败」，经 Mentor 实测成立，已记为分歧 #13。
  • 诊断：轻度边界模糊。「3–7 万 tokens」没写语言假设（英文约 4 字符/token，中文约 1 字/token，相差 3–4 倍）；「首个退化点」依赖客户端的实现选择（目录格式、激活方式、是否转义），这个条件应写进判词，而不是只放在 self_doubt 里。

#11.2 针对性补课（三板斧）与同构变式复考

Mentor 对三个薄弱点分别补课：

• 世界观微类比：书脊墙是「租来的固定墙面」，整本才按次付费（§4 类比即由此而来）。
• 第一性溯源：成本函数从 Σ(全部正文) 变为 Σ(全部书脊) + Σ(被用到的正文)，病根是自变量选错了，而不是模型「看不清」。
• 破坏性反例：原型 B1（16.9×）与 B3（目录 +255%）的实测数字。

随后用全新场景的同构变式复考，每题带一道硬门：

• R1：换到三甲医院护士长与 200 份护理规程。硬门：必须量化固定开销 vs 按需开销，并写明估算假设。
• R2：换成每轮向量检索（RAG）vs Skills。硬门：病根必须落在成本 / 决策结构层，每条论断标证据等级。
• R3：换成云端沙箱 + 管理员 API 下发 150 技能 + 目录嵌在枚举化激活工具的描述里 + 逐行列表格式 + 换行注入 + 2000 行正文。硬门：结论必须写成「在客户端选择 X/Y 下首个退化点是 Z」的条件式。

复考结论：全绿通过。学徒先逐条认账、订正上轮三处薄弱点，然后三道硬门全部落实：

• R1 固定 vs 按需：
  • 学徒先写明假设：1 汉字 ≈ 1 token、书脊约 100 字、窗口约 20 万字（各产品差异大）。
  • 然后给出对照：全量 200 × 3,000 = 60 万字，放不下；书脊固定开销 2 万字，约占一成；按需抽 3 本约 9,000 字。
  • 学徒还指出「吃力」的两个拐点：收到 1,000 份，或书脊写成 500 字长介绍，固定墙面都会吃掉半个台面。另一个隐患是书脊彼此太像，会导致抽错本。
• R2 RAG vs Skills：
  • 核心判断：RAG 修好了成本函数的自变量（每轮固定捞 k 段，与装机数脱钩），却把「加载什么」的决策交给了模型之外、目标错配的相似度函数，病根从成本结构层移到了决策结构层。
  • 每条论断都标了证据等级。材料对 RAG 零提及，相关论断一律标推演；「相似 ≠ 适用」锚到 best-practices 的「非显然坑点连 Agent 都可能认不出触发」原文。
  • 可观测性差异：Skills 激活是显式事件，能算触发率；RAG 的失败是「该来的段落没来」，对话里不留痕迹。
• R3 条件式判词：
  • 在「枚举激活工具 + 逐行列表目录」下，首个退化点是那个 2,000 行、被频繁激活的技能。学徒的算法是：期望成本 = 激活概率 × 正文长度，激活概率趋近 1 时，按次付费就退化成固定墙面；而且它受压缩豁免，会整场会话钉在上下文里。
  • 若工具描述有长度上限，首个退化点前移到目录层。学徒诚实标注未核实。
  • 若改为「XML 目录 + 读文件激活」，首个退化点变为注入劫持。
  • 换行注入的对照：在列表格式下，因为 html.escape 不处理换行，会伪造出与真条目外观无异的幽灵条目，但它会被枚举校验拒绝，后果止于浪费轮次；在 XML + 读文件激活下，伪造条目继承真实路径，后果升级为冒名劫持。差异的根源在于谁是事实源：客户端内部的 name → 内容映射，还是目录文本本身。

复考 self_doubt 保留的一条值得记下：枚举拒绝的真实表现可能是「模型改填一个最接近的合法名」，这会让诱导落到一个真实技能上，后果比浪费轮次更重。该点未验证，列为开放问题。

#11.3 归档说明

盲答全文与复考全文（含各自的 self_doubt 清单）随工作过程归档。本笔记沉淀了这轮对抗的三处产物：

• §4 的「固定墙面」类比与账本读法。
• §8 的分歧 #13。
• §9 的 B5 延伸推演。

#12. 用户自测与费曼研讨套件（Self-Assessment Kit）

通览本笔记后，可用这三道题自我考核。题目没有标准答案，欢迎带着作答来对练：

1. 成本题：你的团队有 120 个技能，平均描述 400 字符（英文），平均正文 300 行。估算每会话的 Tier 1 固定开销，再估算一次典型任务激活 2 个技能后的总开销；装机数翻到 500 时，哪一级先成为瓶颈？请写出你的 token 换算假设。——考核点：§4 的成本结构，以及 §10 边界 2。
2. 反事实题：如果规范删掉「name 必须等于目录名」，改为「name 全局唯一，由注册表分配」，§6 的五条规律里哪条会被改写？这会让 Agent Skills 更像哪一类系统（包管理器？域名系统？），「Keep the format small」要付出什么代价？——考核点：规律 2 与争议 3 的对冲关系。
3. 迁移题：本仓的技能目录块写成 - {name}: {description} 的逐行列表，并提示模型调用 expand_skill(name)。结合 §4 的「目录—激活契约」与 §9 的 B5，检查这个设计在注入防护和激活路径上各还缺什么。——考核点：从规范到自家系统的映射能力，可对照 091 映射报告 的 M3 / M4。

#13. 与本仓的关联

• Agent Skills ↔ negentropy 机制映射报告：12 条机制对照本仓三套「skill」实现（运行时 skills 表 / Definition Registry harness_skill 物化 / 翻译 workdir 物化）。头号发现是 Layer 1 目录指示调用 expand_skill，而该工具从未挂载到任何 Agent。
• Skills 模块设计：本仓 Skills 的设计 SSOT（DB-first、三层披露、enforcement_mode）。
• 谱系：
  • 172 Claude Code 规划与协调 的「技能渐进披露」讲的是教学实现的两层加载。
  • 141 Skill 进化闭环 讲的是技能内容如何被进化与度量。
  • 本文讲的是这些实现共同遵循的格式契约。

#参考

• [1] Agent Skills, "Specification," agentskills.io, 2026. [Online]. Available: https://agentskills.io/specification（源 docs/specification.mdx @ 69ef37e9，accessed Sep. 23, 2026）
• [2] Agent Skills, "How to add skills support to your agent," agentskills.io, 2026. [Online]. Available: https://agentskills.io/client-implementation/adding-skills-support
• [3] B. Zhang, K. Lazuka, and M. Murag, "Equipping agents for the real world with Agent Skills," Anthropic Engineering Blog, Oct. 16, 2025 (updated Dec. 18, 2025). [Online]. Available: https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills
• [4] Agent Skills, "Optimizing skill descriptions," agentskills.io, 2026. [Online]. Available: https://agentskills.io/skill-creation/optimizing-descriptions
• [5] agentskills/agentskills, "skills-ref: reference library," GitHub, commit 69ef37e9, Aug. 2026. [Online]. Available: https://github.com/agentskills/agentskills/tree/69ef37e9424c0a7ea9dd2293b559e43ec8176379/skills-ref
• [6] The Unicode Consortium, "Unicode Normalization Forms," Unicode Standard Annex #15. [Online]. Available: https://unicode.org/reports/tr15/
• [7] J. Nielsen, "Progressive Disclosure," Nielsen Norman Group, Dec. 2006. [Online]. Available: https://www.nngroup.com/articles/progressive-disclosure/
• [8] M. Thomson and D. Schinazi, "Maintaining Robust Protocols," RFC 9413, IAB, Jun. 2023. [Online]. Available: https://www.rfc-editor.org/rfc/rfc9413.html
• [9] N. F. Liu, K. Lin, J. Hewitt, A. Paranjape, M. Bevilacqua, F. Petroni, and P. Liang, "Lost in the Middle: How Language Models Use Long Contexts," Trans. Assoc. Comput. Linguistics, vol. 12, pp. 157–173, 2024.
• [10] Y. Qin et al., "ToolLLM: Facilitating Large Language Models to Master 16000+ Real-world APIs," in Proc. ICLR, 2024.（大规模工具库需要检索器做路由）
• [11] OWASP GenAI Security Project, "LLM01:2025 Prompt Injection," 2025. [Online]. Available: https://genai.owasp.org/llmrisk/llm01-prompt-injection/
• [12] Google, "Agent Skills," Google Antigravity Docs, 2026. [Online]. Available: https://antigravity.google/docs/skills（accessed Sep. 23, 2026：工作区默认 .agents/skills/，向后兼容 .agent/skills/；name 可选、缺省取文件夹名）