OpenClaw Skills 优化实践：用 Progressive Disclosure 原则压缩 AI Agent 的上下文开销

一个互联网技术玩家一个爱聊技术的家伙。在工作和学习中不断思考把这些思考总结出来并分享和大家一起交流进步。最近在用 OpenClaw 为自己的工作流开发了几个自动化 Skill跑了一段时间后发现一个问题随着 Skill 越写越详细响应质量反而开始下降有时候 Agent 会忽略某些关键步骤或者混淆不同 Skill 的指令。排查一圈后发现根本原因SKILL.md 写得太长把无关细节都塞进了上下文窗口产生了认知噪音。这篇文章记录我把三个 Skill 从事无巨细优化为按需加载的全过程以及背后的设计原理。一、OpenClaw Skill 是什么OpenClaw 的 Skill 系统可以理解为给 AI Agent 的专项说明书。每个 Skill 是一个目录包含skill-name/ ├── SKILL.md # 核心指令必须 ├── scripts/ # 可执行脚本 ├── references/ # 参考文档按需加载 └── assets/ # 模板/图片等资产Agent 在每次对话时会把所有 Skill 的frontmattername description约 100 词常驻在上下文里。当用户的请求命中某个 Skill 时才加载它的 SKILL.md 正文。references/里的文件则由 Agent 在需要时自行读取不会自动进入上下文。这个三级加载机制就是Progressive Disclosure渐进式披露Level 1Metadataname description → 始终在上下文~100 词 Level 2SKILL.md body → Skill 触发时加载建议 500 行 Level 3references/ 文件 → Agent 按需读取无大小限制二、问题Skills 越写越臃肿我开发的三个主要 SkillSkill功能优化前 SKILL.md 行数tech-news-fetcher抓取10个 RSS 源生成科技新闻日报76 行blog-writer生成 Hugo 博客文章并提交 PR120 行file-manager分析和整理开发项目文件结构531 行file-manager是重灾区。531 行里混杂着常见场景举例、最佳实践清单、故障排查手册、高级用法、批量处理脚本……全部堆在 SKILL.md一旦触发就全部进入上下文。另外发现几个具体问题1. frontmatter description 信息失真tech-news-fetcher的 description 里写着「CSDN」作为新闻源但早已替换为 IT之家——触发词和实际行为对不上影响 Agent 的 Skill 选择判断。2. 细节与流程混在一起blog-writer的 SKILL.md 里Step 2.5生成 Banner这一节嵌入了大段图标映射规则像这样- 机器人 → AI / Agent / LLM 主题 - 盾牌 → 安全 / 风险主题 - 放大镜 → 搜索 / 分析主题 - 灯泡 → 创新 / 思考主题 - 齿轮 → 工程 / 架构主题这些细节在每次博客流程中几乎不需要查阅——它们本应是脚本内部逻辑放进 SKILL.md 只会增加噪音。3. 角色定位写死了个人信息blog-writer的 description 里硬编码了 “helight”技术上这个 Skill 若被分享出去触发逻辑会产生歧义。三、优化原则只放不在这里就找不到的内容新版 skill-creator 的核心指导思想总结成一句话Default assumption: Claude is already very smart. Only add context Claude doesn’t already have.每加一行内容都要问自己“这件事 Claude 不查这里也知道吗” → 如果是删掉“这个细节只在特定场景下用到吗” → 如果是移到references/“这是步骤How还是背景Why/What” → 步骤留 SKILL.md背景移 references三层内容分配原则SKILL.md body500行 ✅ 核心工作流每次执行都要看的步骤 ✅ 关键命令带最常用参数 ✅ 安全边界必须注意的约束 ❌ FAQ 和常见问题 ❌ 常见场景举例 ❌ 细节参数说明 references/按需加载 ✅ 参数详细说明 ✅ 常见场景与最佳实践 ✅ 故障排查手册 ✅ 领域模板/规则文档四、三个 Skill 的实际改造4.1 tech-news-fetcher问题分析这个 Skill 的问题看起来不大但实际上有两处隐性错误会悄悄影响 Agent 的判断质量。第一个问题description 信息过期。原版 description 里明确列出了10个新闻源其中包括「CSDN」。但在开发早期CSDN 的 RSS 接口返回 HTTP 401已经替换为「IT之家」。description 是 Agent 判断这个 Skill 能干什么的唯一依据——如果 description 和实际行为不一致Agent 在推理时会产生一个微妙的认知偏差它以为自己会抓 CSDN结果没有但又不知道原因。更深层的问题是description 里把10个来源全部罗列出来显得像是一份功能清单而非触发说明。触发一个 Skill 的关键信息应该是什么场景下用它而不是它内部包含哪些资源。第二个问题主要用法没有体现在 SKILL.md 里。随着使用深入Hugo Blog 模式已经成为主要用途直接生成博客内容并提交 PR但原版 SKILL.md 只写了 Obsidian 模式。Agent 每次执行时要么需要用户额外说明要么凭记忆推断——这两种情况都不可靠。改造内容description 删掉来源清单改为场景触发词为主并加入生成今日新闻博客这类 Hugo 触发词SKILL.md 重构为Hugo 模式优先Obsidian 模式次之主用法第一眼就能看到FAQ某些源抓不到怎么办、图片慢怎么办和反封禁机制细节UA 轮换逻辑、请求间隔参数→ 新建references/usage.md这些是偶发场景才需要查的内容## 主要用法Hugo Blog 模式 python3 scripts/fetch_news.py --hugo-blog /projects/hxblog --date 2026-03-10 ## Obsidian 模式 python3 scripts/fetch_news.py --output-dir ~/Documents/Obsidian/科技新闻结果76 行 → 40 行↓47%。更重要的是description 和实际行为重新对齐Agent 的 Skill 选择判断准确率会提升。4.2 blog-writer问题分析blog-writer的问题集中在两个层面信息结构错位和可复用性缺陷。第一个问题步骤中嵌入了规格说明。Step 2.5生成 Banner这一步写成这样**Banner 设计规范312×240** - 手绘 sketch 风米白底炭笔线条 - 左侧标题 副标题 关键词彩色胶囊 - 右侧1~2 个手绘卡通图标自动根据关键词选取 - 机器人 → AI / Agent / LLM 主题 - 盾牌 → 安全 / 风险主题 - 放大镜 → 搜索 / 分析主题 - 灯泡 → 创新 / 思考主题 - 齿轮 → 工程 / 架构主题 - 多留白不堆砌元素这段内容的性质是脚本规格说明描述的是gen_banner.py的内部设计逻辑而不是怎么执行这一步的操作指令。Agent 每次执行博客生成流程都会把这段塞进上下文——但实际上除非用户要求定制 banner 风格否则这段内容从来不会被用到。每次白白占用几十个 token换来的是零收益。第二个问题description 里硬编码了个人信息。原版 description 写的是帮助 helight 写技术博客文章。这在功能上没问题但一旦把这个 Skill 分享给其他人触发逻辑就会歧义Agent 会认为这个 Skill 是专属于 helight 的在其他用户的语境下可能不触发或者触发后产生奇怪的行为比如在文章里自动填写 helight 的信息。好的 Skill 应该在 description 里描述任务类型不应该绑定具体的使用者身份。第三个问题流程有缺漏。PR merge 后需要同步推送到 Gitee但原版 Step 5 没有这一步。这不是细节问题而是实际执行时每次都要额外补一条命令——说明 SKILL.md 的工作流描述与实际操作存在断层。改造内容description 改为通用表述“帮助写技术博客文章并提交到 Hugo 博客仓库”去掉 “helight” 的绑定 Banner 规格说明尺寸、图标映射、配色逻辑→ 新建references/banner-spec.mdStep 2.5 只保留执行命令Step 5 补充git push gitee main流程与实际操作完全对齐结果120 行 → 60 行↓50%。更重要的是Skill 的可复用性提升流程不再有缺漏。4.3 file-manager问题分析这是三个 Skill 里问题最严重的也是最典型的反面教材——把 Skill 写成了用户手册。531 行的 SKILL.md 包含了四步工作流这是必要的每步详细说明包括What it does逐条列举大量冗余四个典型使用场景每个场景都展开成完整的操作步骤典型的防御性写作最佳实践清单DO / DON’T 各5条这是给人读的故障排查4类问题 × 详细解决方案偶发场景不该常驻上下文高级用法自定义配置、批量处理脚本极低频需求限制说明6条已知局限这是写给读者看的不是 Agent 执行时需要的根本问题是写这个 Skill 的时候假设的受众是人类用户在读文档而不是AI Agent 在执行任务。两者的信息需求截然不同人类读文档需要背景、需要 Why、需要举例、需要边界说明越完整越好AI Agent 执行任务只需要 How、只需要当前步骤、需要约束条件越精简越好防御性写法“万一用户问到场景X这里有答案”在人类文档里是美德在 AI Skill 里是负担——因为 Agent 在处理file-manager相关请求时会把全部 531 行一次性加载进上下文不管当前任务用不用得到场景X的内容。以最佳实践这节为例原版是这样的- ✅ DO: Always use dry-run first - ✅ DO: Create backups before major changes - ✅ DO: Commit to Git before reorganizing - ✅ DO: Review reports before executing - ✅ DO: Test project functionality after changes - ❌ DONT: Skip dry-run mode - ❌ DONT: Delete backups immediately ...这10条里有效信息只有两条核心约束先 dry-run、先备份其余都是这两条的变体或推论。Agent 其实完全能从先 dry-run、先备份推导出后面8条——重复写出来只是在消耗上下文配额。改造内容核心原则每一行 SKILL.md 都必须是执行时必看的内容。移出到references/scenarios.md四个典型场景的详细操作步骤按需查阅不是每次都需要定期维护建议属于最佳实践不是执行指令批量处理多个项目的脚本高级用法极低频已知限制说明背景信息不影响执行保留在 SKILL.md四步工作流表格执行时必看决策入口每步一条核心命令执行时必须知道5 条安全规则执行时必须遵守的约束4 条故障排查一行一条精简到只有原因解法重构后核心部分## Workflow | Step | When to use | Script | |------|---------------------|----------------------| | 1. Analyze | 首次/变更前 | file_analyzer.py | | 2. Plan | 预览目标结构 | structure_planner.py | | 3. Organize | 执行迁移 | file_organizer.py | | 4. Clean up | 清理冗余 | cleanup_manager.py |四步、四个脚本、决策标准一目了然。需要了解某步骤的典型场景读references/scenarios.md。需要知道清理规则的细节读references/cleanup_rules.md。这些文件只在真正需要时才被加载。结果531 行 → 87 行↓84%。上下文开销减少了五分之四而实际执行能力没有任何损失——因为所有细节都在 references 里待命。五、总结这次优化让我重新理解了给 AI 写文档和给人写文档的本质区别给人写文档越全越好用户可以跳读信息冗余有益无害。给 AI 写文档越精越好上下文窗口是共享资源每一行都有成本。塞进去的信息不是备用知识而是会参与每次推理的噪音候选。Progressive Disclosure 原则在 AI 场景里格外重要——不是因为 AI 读不懂复杂文档而是因为加载了不需要的内容会降低需要的内容的权重。三个 Skill 优化后的整体效果Skill优化前优化后压缩率tech-news-fetcher76 行40 行↓47%blog-writer120 行60 行↓50%file-manager531 行87 行↓84%下一步计划把 references 文件也做结构化索引让 Agent 能更精准地判断什么情况下读哪个文件进一步减少不必要的文件加载。