SKILL-SPEC：114 个技能为什么不撑爆上下文

🎒 预备知识：完成上一课「L05」（零基础入口：第 0 课）

一、基础：一个技能目录的合法解剖（规范逐条）

先看规范（SKILL-SPEC.md v0.3）规定的完整结构，再逐条说为什么：

skill-xxx/
├── SKILL.md        # 必须，<200 行硬上限；frontmatter 只许 3 个字段
├── references/     # 领域知识，执行中按需读取，不常驻
├── scripts/        # 可执行脚本，代码永不进 prompt
├── tests/          # test1.prompt + test1.expected（关键词匹配）
└── EASEL-META.md   # 来源/收录信息

为什么 SKILL.md 硬性 <200 行：SKILL.md 会被整个读进上下文（触发时）， 它是 token 预算的单位——200 行 ≈ 2K token，114 个里哪怕一轮触发 3 个也只有 6K。 没有上限的技能会悄悄长成 2000 行的百科全书，触发一次半轮窗口没了。上限是预算工具， 不是文风建议。

为什么 frontmatter 只许 name/description/layer 三个字段：frontmatter 是 常驻部分（每轮都在上下文里做路由），字段越多常驻越贵。规范还显式禁止 version、tags、allowed-tools 等——禁令本身是设计：把"感觉有用"的字段挡在常驻区外 （要记录来源？去 EASEL-META.md，那不常驻）。A5 的预算纪律被写成了 schema。

三层加载时机表：

二、description 是路由器，不是说明书

agent 靠常驻的 description 决定"要不要加载这个技能"——它是 114 选 N 的路由键。 规范要求 description 用中文写清能力 + 触发场景/用户说法 + 与相邻技能的边界。 看 social-content 的写法（大意）："多平台社媒文案撰写……小红书整套笔记找 xhs-note-creator、 带货转化找 copywriting"——负空间也是路由信息：明确"不是我"才能让相邻技能被正确触发。 这与 L7 的工具 description 纪律完全同构——Easel 把它升级成了制度。

三、token 经济学（出口检验的算术）

常驻：114 技能 × frontmatter ≈ 60 token ≈ 7K
触发：一次任务 2 个技能 × SKILL.md（≤2K）≈ 4K
执行：references 按引用读若干（0–5K 浮动）
对比：把 114 个 SKILL.md 全塞进系统提示 ≈ 230K —— 直接爆窗

差距的本质（A2 讲过，这里用 Easel 的真实数字）：常驻成本被压到索引级， 正文成本按用量付。这也是"敢做 114 个技能"的底气——A2 的算术在真实仓库的验证。

四、规范怎么被执行（不是靠自觉）

scripts/validate_skills.py 全库校验：frontmatter 合法性、相对链接、内联资源引用、 产物目录布局（禁止根目录散文件、禁止泛名项目目录、系统目录必须 _ 前缀）； 另一个脚本 validate_skill_commands.py 解析 SKILL 里的命令、对照脚本 argparse 检查参数漂移（文档写了 --foo 而脚本没有 = 报错）。规范 CI 化是 文档类工程和代码工程的分水岭——写下来的规则没有守护就是许愿。

五、常见踩坑

坑 1：description 写成文档摘要。"本技能用于内容创作"——路由不了任何东西； 要写触发场景原话和边界。坑 2：SKILL.md 里贴大段参考知识。应该进 references/ 按需读，正文只留流程。坑 3：脚本参数改了文档不改。没校验脚本的仓库必患此病—— 参数漂移让 agent 照文档调用必然失败。

六、检索练习

七、出口检验

任选一轮真实任务（如"写小红书笔记并发布"），列出：哪些内容常驻、哪些触发加载、 哪些执行中才读、哪些永不进 prompt。算出总 token 构成讲给我听。

一手源：docs/SKILL-SPEC.md（v0.3）+ scripts/validate_skills.py 看规范如何被 CI 化执行。