SKILL.md 瘦身指南：372 行压到 287 行的十一个压缩技术实战拆解
前言
技能文件越写越长，触发词失效、推理链丢失、Agent 跳过流程——多半是写得太多。
一次「分身」失灵引发的瘦身
上周说「分身帮我看下」，Agent 跳过技能流程，自己去查代码。
事后它承认：「你说的是『分身帮我看下』，这是明确的技能触发，我应该调 my-digital-human，但我直接跳过去看代码了。」
这不是第一次。2026-07-03 修过一回（v2.4.0），在 SKILL.md 顶部加了「强制前置检查」。
今天又复现。
修完触发问题后，SKILL.md 已经 372 行，比很多项目 README 还长。
于是做了一次压缩：372 → 287 行（-23%），同时加了 4 个功能（需求完成度审查、内部平台链接处理、接口文档对齐、@see 反模式）。
下面是这次压缩用到的方法。
为什么 SKILL.md 不能太长？
上下文窗口的隐性成本
Claude Code 每次对话都会把 SKILL.md 塞进上下文。文件越长：
•Token 越贵— 冗余内容每次都付费
•注意力被稀释— 规则埋在大段文字里，Agent 更容易漏
•触发更不稳— description 里的触发词在长文本里权重下降
SkillReducer（arXiv:2603.29919）对 600 个技能的实测：description 平均可压 48%，body 平均可压 39%，且不影响任务完成率。
SKILL.md 该干什么
Anthropic 官方指南的定位：
SKILL.md = 路由表 + 核心规则摘要
详细规则在
references/，按需加载。
SKILL.md 是目录：告诉 Agent「去哪里找什么」，不把知识全塞进来。
菜单写「宫保鸡丁 — 38 元」就够，烹饪步骤放厨房（references/）。
十一个压缩技术
技术 1：渐进式披露
SKILL.md 只放触发条件和关键输出，检查清单下沉到 reference。
路径 B（Review）新增「需求完成度审查」「接口文档对齐」时，最初把检查表、四档判定、@see 规则全写进 SKILL.md，占 35 行。
压缩后只留 3 行触发：
-**B1. 需求完成度审查** — 触发：用户问「完成度/是不是好了」 或存在 OpenSpec 目录。核对 tasks.md + Open Questions + 接口对齐， 输出四档判定（可上线/待联调/待测试/代码完成） -**B2. 接口文档对齐检查** — 触发：Review 涉及 api/ 层或用户 提供接口文档链接。检查 @see 注释完整性、参数一致性、同文件一致性完整表格、判定标准、输出格式 →references/review-extensions.md
-33 行，功能零丢失。
技术 2：去重合并
消掉 SKILL.md 内部、以及和 references/ 的重复。
原来三处在说同一件事：
区域 | 内容 | 重复度 |
核心原则 | 「必须展示技能推理链」 | 100% |
强制前置检查 | 「展示技能推理链（步骤 4.5）」 | 100% |
步骤 4.5 | 推理链格式规范 | 原始定义 |
删「核心原则」，把推理链要求并进「强制前置检查」第 3 条。
「When NOT to Use」和「诚实边界」也高度重叠（后端/运维/业务领域不处理）——删前者，留后者。
-24 行。
技术 3：路由表模式
路径表（A/B/C/D/E）只写「加载什么文件」，不写「文件里有什么」。
内部平台链接识别，最初在步骤 1 放完整域名表：
| 域名模式 | 平台 | 声明话术 | 替代方案 | |---------|------|---------|---------| | yapi.* | YApi | 「需要登录，无法访问」 | 截图/粘贴 | | figma.com | Figma | ... | ... |压成 1 行规则 + 指针：
检测到 yapi.*、figma.com、confluence.*、*.internal 等域名时， 在步骤 1 显式声明无法访问并提出替代方案。 详细域名模式与话术见 references/review-extensions.md-9 行。Agent 仍知道该做什么，详细话术从 reference 读。
技术 4：符号化表达
用分隔符、缩写、单行列表替代多行展开。
「NEVER」清单原 5 行，压成 1 行：
**NEVER**：❌ 第一轮直接查代码未调 Skill 工具 · ❌ 跳过推理链 · ❌ 不展示决策依据 · ❌ 不按 Output Contract 格式用·分隔，语义不变，5 → 1 行。
Loop Engineering 六个落户点同理：
Maker/Checker · Reflexion · 风格巡检 · Darwin Loop · 多 Loop 类型 · Exit Rules-16 行。
技术 5：删掉 AI 已知知识
别教 AI 它已经会的东西。
原来有一段 Darwin 脚本顺序：
**Darwin 闭环**：darwin-eval.sh --json → generate-rule-hypothesis.sh → close-loop-verification.shAgent 拿到 reference 自己能读懂调用顺序。删掉，只留：
发现问题 → skill-issues.jsonl → 假设 → Darwin 评估 → 更新规则-5 行，信息密度更高。
技术 6：删除镜像表
写完主文后又总结一遍的"镜像冗余"是常见膨胀源。
文件底部的 Bundled Resources 表（17 行）是步骤 2 中路径 A~E 文件加载指引的逐条复述：
Bundled Resources 表项 | 已在何处写过 |
— 每次执行 | 步骤 2 第 55 行 |
— 推理链前 | 步骤 4.5 第 136 行 |
— 写代码/Review | 路径 A/B |
— 写代码 | 路径 A |
…共 17 项 | 路径 C/D/E、步骤 4 |
整表替换为 1 行指针：
## Bundled Resources 各文件的加载时机已在步骤 2（路径 A~E）和步骤 4 中标注，不再重复列出。-14 行，零信息丢失。与去重合并的区别：这里删除的是"总结性镜像"，即写完详细内容后又在文末重新列一遍的冗余。
技术 7：默认值隐式化
只写「例外」，不写「默认」。Agent 的常规行为不需要重复声明。
Checkpoints 原来 7 行（标题 + 说明 + 5 项列表），压成 1 行直接陈述：
**Checkpoints**：修改公共代码（components/utils/mixins/） · 调整接口层（api/） · 修改构建配置/环境变量 · 删除/重构影响其他模块的代码 · 引入新依赖（package.json）。不需要再写"以下情况必须暂停并请求用户确认"——Agent 已知 Checkpoint 的含义。
-6 行。与符号化的区别：这里省掉的是"解释性前缀"，只保留事实陈述。
技术 8：跨节去重
不同章节之间对同一概念的分散描述。
步骤 4（18 行）已写了 Maker → Checker → Reflexion 的完整流程，后面又有一个独立的"Loop Engineering & Eval"节（4 行）重复列举 6 个落户点。
合并为 2 行指针：
## Loop Engineering & Eval > 详细规则 + 6 个落户点：references/loop-engineering.md > Darwin 闭环：发现问题 → skill-issues.jsonl → 假设 → Darwin 评估 → 更新规则-2 行。与技术 2（去重合并）的区别：技术 2 是同一文件内的重复，技术 8 是跨章节的分散描述合并。
技术 9：已完成状态压缩
历史记录全是"已完成"时，表格可以压缩为单行概述，留扩展点。
Correction 表格原来 4 行（3 条 ✅ 记录 + 表头）：
**已纠正**：变量 camelCase（禁 PascalCase） · 注释解释 WHY · 接口层独立在 api/ （2026-07-02 全部 ✅）。新增纠正在下方追加行。-4 行。当有新纠正时再恢复表格形式。
技术 10：引用指针化
步骤中复述 reference 里已有的格式定义，压缩为指向具体章节的指针。
步骤 3 中「拆解需求额外要求」复述了 Open Questions 矩阵的格式，而路径 C 已要求加载decision-heuristics.md§7（里面有完整定义）。
从 3 行压缩为 1 行指针：
输出格式见 references/decision-heuristics.md §7（拆解需求时）。-2 行。与技术 3（路由表模式）思路一致，但应用于"输出格式定义"而非"文件加载"。
技术 11：列表符号化（补充应用）
符号化不仅适用于 NEVER 清单，也适用于其他多行列表。
「踩过的坑」4 行列表压成 1 行：
**踩过的坑**：iOS API 兼容性 → 先查 + polyfill · 多环境域名 → env + 变换工具 · 轮询无停止条件 → 完成/销毁时清理 · 需求变更 → 对比差异后增量修改-3 行。
压缩前后对比
第一轮（v2.8.0 → v2.8.1）
指标 | 压缩前 | 压缩后 | 变化 |
总行数 | 372 | 287 | -23% |
章节数 | 12 | 10 | -2（合并） |
新增功能 | 0 | 4 个 | 完成度审查、内平台处理、接口对齐、@see 反模式 |
references 文件 | 13 | 14 | +1（review-extensions.md） |
第二轮（v2.8.1 → v2.8.2）
指标 | 压缩前 | 压缩后 | 变化 |
总行数 | 287 | 249 | -13% |
省行数 | — | -38 | 技术 6~11 |
两轮总览
轮次 | 版本 | 行数 | 省行数 | 省比例 | 涉及技术 |
第一轮 | v2.8.0 → v2.8.1 | 372 → 287 | -85 | -23% | 技术 1~5 |
第二轮 | v2.8.1 → v2.8.2 | 287 → 249 | -38 | -13% | 技术 6~11 |
合计 | 372 → 249 | -123 | -33% | 11 种技术 |
行数少 33%，功能反而增加 4 个。
11 种技术分类速查
类别 | 技术 | 核心思路 |
结构级 | 1. 渐进式披露 | 检查清单下沉到 reference |
2. 去重合并 | 消掉同一文件内的重复 | |
6. 删除镜像表 | 消掉"写完又总结一遍"的冗余 | |
8. 跨节去重 | 合并不同章节对同一概念的描述 | |
路由级 | 3. 路由表模式 | 只写"加载什么"，不写"里面有什么" |
10. 引用指针化 | 复述 reference 已有定义 → 指向具体章节 | |
表达级 | 4. 符号化表达 | 分隔符/缩写替代多行展开 |
7. 默认值隐式化 | 只写例外，不写默认 | |
9. 已完成状态压缩 | 全完成的表格 → 单行概述 | |
11. 列表符号化 | 多行列表压成 1~2 行 | |
知识级 | 5. 删掉 AI 已知知识 | 不教 AI 已经会的东西 |
什么时候该压缩？
三个信号：
1.触发词失效— Agent 忽略触发词、跳过技能流程。说明关键词权重已被稀释。
2.行数超过 300— 经验阈值，多半有可压空间。
3.references/ 比 SKILL.md 还短— 主文件扛了太多本该下沉的内容。
压缩检查清单
动手前过这 11 项：
•[ ] 有没有与 references/ 重复的完整规则？→ 删，留指针（技术 1）
•[ ] 有没有两个章节在说同一件事？→ 合并（技术 2）
•[ ] 多行列表能不能用·压成一行？→ 符号化（技术 4/11）
•[ ] 有没有在教 AI 已知的东西（脚本顺序、工具用法）？→ 删（技术 5）
•[ ] 新功能能不能只写触发条件，细则放 reference？→ 渐进式披露（技术 1）
•[ ] 有没有"写完又总结一遍"的镜像表？→ 删，留指针（技术 6）
•[ ] 标题/说明/前缀能不能省略？Agent 已知默认行为 → 只写事实（技术 7）
•[ ] 不同章节有没有分散描述同一概念？→ 跨节合并（技术 8）
•[ ] 历史记录表格是不是全 ✅？→ 单行概述（技术 9）
•[ ] 步骤中有没有复述 reference 已有的定义？→ 指向具体章节（技术 10）
•[ ] 路由表是否只写"加载什么"而非"里面有什么"？（技术 3）
最后
SKILL.md 压缩是在重排信息层级：对外简洁接口，对内复杂实现。Agent 只需知道「调用什么、得到什么」。
下次技能「不听话」，先看文件是不是太长了，再考虑加规则。