Skip to content

Agent Skills的渐进式披露 （Progressive Disclosure）

一、概念

渐进式披露：不要一次性把整套Skill超长规则全部塞给LLM；只在「意图匹配成功之后」，才动态加载这份Skill的完整流程、约束、权限。

传统模式（不使用渐进披露）：

启动会话，把全部几十份Skill的所有SKILL.md全文一次性注入系统提示词。 致命问题： - Token爆炸，大量无关规则污染上下文； - LLM信息过载，容易混淆多条Skill逻辑； - 浪费算力，95%的Skill本轮对话根本用不上。

渐进式披露模式（OpenClaw / agentskills.io 原生设计）： 1. 初始阶段：只加载 Skill 目录摘要清单 每条仅保留极简元信息：name + description 

mkdocs-builder: 处理mkdocs构建、预览、yaml语法排查
go-code-review: Go代码安全审查

这一段很短，常驻上下文，用于意图匹配路由。

  1. 用户提问 → 模型判断意图命中某条Skill
  2. 触发披露：把该Skill完整正文（流程、allowed-tools、约束、输出模板）追加进上下文
  3. LLM拿到完整SOP，严格按照Skill执行任务。

任务结束 / 切换到无关任务：不再保留完整Skill正文；下次需要时再重新披露。

二、两层信息边界（agentskills.io 规范隐含设计）

① 轻量索引层（常驻）

name + description 作用：路由、意图识别 不包含详细步骤、权限、输出格式。

② 完整规则层（按需披露）

整个SKILL.md正文： allowed-tools、执行流程、检查清单、禁止行为、输出模板。

平时不加载；匹配命中才注入上下文。

三、完整执行时序（对照你现在的OpenClaw小龙虾）

  1. 新建会话，网关读取所有 ~/.openclaw/skills/*/SKILL.md
  2. 提取索引摘要，生成简短目录清单，放入初始System Prompt 
    可用技能列表：
1. mkdocs-builder：mkdocs文档构建、serve、yaml错误排查
2. xxx：……
  3. 用户输入：帮我执行 mkdocs build
  4. LLM根据摘要判断：意图匹配 mkdocs-builder
  5. OpenClaw网关执行【渐进披露】： 把 mkdocs-builder/SKILL.md 全文追加发送给模型
  6. LLM获得完整权限、步骤、约束，开始调用 read_file/run_bash
  7. 任务完成；后续对话若无相关需求，不再持有完整Skill文本

四、渐进式披露带来的核心优势

1. 上下文Token极大节省

假设你有30个Skill，每份SKILL.md平均800token： - 全量预加载：≈24000 token - 渐进披露：常驻索引仅几百token；只加载命中那一份800token 对于DeepSeek v4-flash、Claude这类长上下文模型，直接降低推理成本、减少模型混淆。

2. 减少规则相互干扰

很多Skill约束互相冲突。 只在用到的时候加载完整规则，避免多条业务SOP同时存在造成模型错乱。

3. 天然模块化，支持大规模Skill库

当你积累50+、100+自动化技能时，这套架构才能稳定运行； 如果全部塞进全局System Prompt，模型会逐渐“失忆”、忽略指令。

4. 支持动态热更新

openclaw skills refresh 更新Skill文件； 下一次命中该Skill时，披露的就是新版本规则，无需重启会话。

五、容易踩的设计误区

误区1：description写得过长

很多人把详细步骤塞进description。 后果：索引层膨胀，违背渐进披露初衷。 ✅ 正确：description只写用途场景，流程全部放到正文。

误区2：模型匹配不准，无法触发披露

description描述模糊，LLM无法判断“要不要加载这份Skill”。 优化方案： description清晰写明触发关键词与场景，示例： 

description: >
  MkDocs文档自动化工具。
  用户提到 mkdocs build、mkdocs serve、排查mkdocs.yml语法报错时启用。

误区3：一次性披露多个Skill

尽量设计任务隔离，一个主任务只激活一份Skill； 多Skill同时披露极易产生指令冲突。

六、延伸：进阶形态——多级渐进披露（大型复杂Agent）

1级：技能摘要（常驻，意图路由） 2级：Skill总体框架（命中后披露） 3级：子步骤清单（执行到对应阶段再披露细分细则）

适合巨型工作流：代码重构、端到端项目迁移等超长SOP。

七、联系你当下环境总结

OpenClaw（小龙虾）原生实现了Agent Skills渐进式披露机制： - TUI/Web会话启动只会载入技能简短清单； - 只有模型判定意图匹配 mkdocs-builder，网关才把完整SKILL.md下发给LLM； - 修改SKILL.md后 skills refresh，下一次触发时披露新版内容。

如果你需要，我可以给你一份「最优SKILL.md撰写模板」，专门适配渐进式披露架构：精简description用于路由，复杂流程全部放在正文。