前言技能文件越写越长触发词失效、推理链丢失、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 里的触发词在长文本里权重下降SkillReducerarXiv:2603.29919对 600 个技能的实测description 平均可压 48%body 平均可压 39%且不影响任务完成率。SKILL.md 该干什么Anthropic 官方指南的定位SKILL.md 路由表 核心规则摘要详细规则在references/按需加载。SKILL.md 是目录告诉 Agent「去哪里找什么」不把知识全塞进来。菜单写「宫保鸡丁 — 38 元」就够烹饪步骤放厨房references/。十一个压缩技术技术 1渐进式披露SKILL.md 只放触发条件和关键输出检查清单下沉到 reference。路径 BReview新增「需求完成度审查」「接口文档对齐」时最初把检查表、四档判定、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 表项已在何处写过output-contract.md— 每次执行步骤 2 第 55 行skill-inference.md— 推理链前步骤 4.5 第 136 行expression-dna.md— 写代码/Review路径 A/Barchitecture-patterns.md— 写代码路径 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跨节去重不同章节之间对同一概念的分散描述。步骤 418 行已写了 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指标压缩前压缩后变化总行数372287-23%章节数1210-2合并新增功能04 个完成度审查、内平台处理、接口对齐、see 反模式references 文件13141review-extensions.md第二轮v2.8.1 → v2.8.2指标压缩前压缩后变化总行数287249-13%省行数—-38技术 6~11两轮总览轮次版本行数省行数省比例涉及技术第一轮v2.8.0 → v2.8.1372 → 287-85-23%技术 1~5第二轮v2.8.1 → v2.8.2287 → 249-38-13%技术 6~11合计372 → 249-123-33%11 种技术行数少 33%功能反而增加 4 个。11 种技术分类速查类别技术核心思路结构级1. 渐进式披露检查清单下沉到 reference2. 去重合并消掉同一文件内的重复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 只需知道「调用什么、得到什么」。下次技能「不听话」先看文件是不是太长了再考虑加规则。