02 AgentSkills 渐进式披露机制与上下文优化策略关键词渐进式披露、Progressive Disclosure、SkillRegistry、上下文窗口、Token 预算、懒加载、技能激活、上下文优化、多技能协同一、上下文窗口Agent 的稀缺资产要理解渐进式披露得先理解上下文窗口对 Agent 意味着什么。不同于普通的对话场景Agent 在执行复杂任务时上下文里需要同时塞入很多东西系统提示、工具描述、对话历史、任务状态、中间结果……每一项都要消耗 Token。而上下文窗口是有硬上限的——哪怕是当前最大的模型这个资源也不是无限的。问题的关键在于一个矛盾Agent 需要访问的领域知识越多上下文压力就越大但提前加载所有知识又会让真正有用的内容被淹没。传统方案通常走两个极端极端一全量加载。把所有工具描述、技能指令一股脑塞进系统提示。优点是 Agent 随时能想起任何技能缺点是 Token 消耗爆炸甚至还没开始工作就超出预算。极端二按需手动指定。每次任务都由工程师手动选择要加载哪些技能。优点是精准缺点是失去了自动化的意义——Agent 反而需要人来驾驶。Agent Skills 选择了第三条路渐进式披露。二、渐进式披露的核心逻辑渐进式披露Progressive Disclosure这个词最早来自 UI 设计领域意思是先展示用户最需要的信息在需要时再提供更多细节。Agent Skills 把这个理念搬到了上下文管理里。核心思路上下文里的信息量应该动态匹配当前任务的实际需求。实现方式是三级分层结构 | Level 1: Discovery发现层 | | -------------------------------------------------- | | 技能目录Skills Catalog | | 每个技能: name description 摘要约 10 tokens | | 100 个技能总计约 1000 tokens常驻上下文 | | [任务与技能描述匹配] | v | Level 2: Activation激活层 | | -------------------------------------------------- | | 完整 SKILL.md 正文 5000 tokens | | 仅在技能被激活后加载到上下文 | | [执行步骤引用外部资源] | v | Level 3: Execution执行层 | | -------------------------------------------------- | | references/按需读取参考文档 | | scripts/按需执行代码脚本 | | 资产按需加载不占用常驻上下文 | 这个设计的本质是一种信息惰性化策略Information Laziness信息只在真正需要时才进入上下文用完后可以释放。三、SkillRegistry管理技能的中枢渐进式披露的实现依赖一个核心组件——SkillRegistry技能注册表。它是整个机制的调度中心。3.1 SkillRegistry 的职责SkillRegistry 负责三件事技能注册接收来自不同 Provider文件系统、HTTP 远端、数据库的技能包建立技能目录。技能发现提供get_skills_catalog()接口输出当前所有技能的摘要列表供注入到系统提示的 Discovery 层。技能激活提供load_skill(name)接口在需要时读取完整的 SKILL.md 内容返回给 Agent 上下文。3.2 技能目录的 XML 格式SkillRegistry 生成的技能目录通常以 XML 格式注入系统提示这种格式对 LLM 的解析更友好skills_catalogskillnamepdf-processing/namedescription处理 PDF 文档。适用文本提取、表单填写、合并拆分、OCR 识别。/description/skillskillnamecode-review/namedescription结构化代码审查。适用PR 审查、安全审计。输出问题分级报告。/description/skillskillnamedata-analysis/namedescription数据清洗与统计分析。适用处理 CSV/Excel生成可视化图表。/description/skill/skills_catalog整个目录块注入系统提示Agent 每次生成回复前都能看到现有技能列表在判断任务需求时自主决定是否激活某个技能。3.3 激活触发机制技能激活有两种路径各有适用场景LLM 自主推断Agent 根据用户请求的语义对照技能目录描述自行判断是否调用。这是最灵活的方式适合通用场景。激活的调用方式通常是让 Agent 直接读取 SKILL.md 文件或者框架层自动注入。规则匹配平台预设关键词或模式规则如果用户消息命中规则则自动激活对应技能。这种方式确定性强适合高频、明确的场景例如用户每次提到部署上线就自动激活deploy-checklist技能。两种方式并不互斥实践中往往组合使用。四、Token 预算控制的量化策略渐进式披露的价值可以用数字来衡量。场景假设Agent 平台管理 50 个技能每个技能的完整 SKILL.md 约 2000 tokens。加载策略上下文消耗可用于任务推理的 Token全量加载50 × 2000 100,000 tokens所剩无几在 128K 窗口下渐进式披露只激活 1 个技能50 × 10 2000 2,500 tokens充裕渐进式披露激活 5 个技能500 10,000 10,500 tokens仍然充裕这个对比直观地展示了渐进式披露的价值——它让管理大量技能和保持上下文精简这两件本来矛盾的事情得以共存。Token 预算控制的几个设计原则Discovery 层预算硬上限每个技能的摘要不超过 100 tokens强制要求 description 简洁。Activation 层预算硬上限SKILL.md 正文不超过 5000 tokens超出部分必须拆分到 references。Execution 层按需释放references 文件读取后可以随任务结束而释放不长期占用上下文。五、多技能协同的上下文管理实际任务往往不是恰好用一个技能能解决。复杂任务可能需要多个技能协同工作这时的上下文管理更具挑战性。5.1 技能间依赖关系某些技能存在逻辑依赖关系。例如数据清洗技能 (data-cleaning) | v数据清洗后 数据分析技能 (data-analysis) | v分析完成后 报告生成技能 (report-generation)在这个链条里三个技能是顺序激活的。只要设计好每个技能的 description明确说明本技能的输入是什么格式的数据Agent 就能自主完成这个调用链不需要手动干预。5.2 并行技能协同有些任务可以同时激活多个独立技能。例如代码审查任务可能同时需要code-style-check检查代码风格security-audit检查安全漏洞performance-review检查性能瓶颈这三个技能相互独立可以同时加载。但要注意多技能同时激活时总 Token 消耗是叠加的需要评估是否超过上下文预算。5.3 避免技能冲突当两个技能的指令存在潜在冲突时例如一个要求所有变量用驼峰命名另一个要求所有变量用下划线命名Agent 会陷入矛盾。预防策略技能设计时明确技能的适用范围在 description 里注明适用于 Python 项目还是适用于 JavaScript 项目使用metadata.tags字段对技能分组同组技能通常不应同时激活在系统提示中加入冲突解决规则“同时激活多个技能时以后激活的技能指令优先级更高”。六、上下文生命周期管理上下文不仅仅是静态的加载/不加载还涉及整个任务过程中的状态维护。[任务开始] | v 加载 Skills Catalog常驻 | v 接收用户请求 -- 识别意图 -- 匹配技能 | v 激活技能注入 SKILL.md | v 执行任务步骤 |--- 按需读取 references |--- 按需执行 scripts | v 任务完成 -- 释放技能上下文可选 | v 等待下一个用户请求回到 Discovery 层关于技能上下文的释放这一点各平台实现不同。有些平台在任务完成后自动清理有些则保留激活的技能直到对话结束。对于长对话场景主动清理不再需要的技能上下文可以为后续任务腾出更多空间。七、实战设计一个 Token 友好的技能把上面的原则落到一个具体例子里。假设要设计一个生产环境部署检查技能。低效设计Token 浪费---name:deploy-checklistdescription:这是一个用于生产环境部署的完整检查清单技能包含代码检查、环境验证、 数据库迁移确认、监控配置检查、回滚方案验证等所有步骤的详细说明...description 写了 500 字把所有细节都堆进来了---高效设计---name:deploy-checklistdescription:生产环境部署前检查。适用代码上线前的安全验证包含 9 项必检项。license:MITmetadata:version:1.3tags:[devops,deploy,production]allowed-tools:Bash Read---## 目标执行生产部署前的系统性安全检查确保每次上线符合团队标准。## 检查清单### P0 必须通过阻塞发布1. 单元测试覆盖率 ≥ 80%运行 scripts/run_tests.sh 验证 2. 无已知 P0/P1 安全漏洞依赖扫描结果 3. 数据库迁移已测试有回滚脚本 4. 环境变量配置完整参考 references/env-checklist.md### P1 建议通过不阻塞但需记录5. 性能基准测试结果在基线 ±10% 以内 6. 监控告警配置已更新### P2 最佳实践7. 变更日志已更新 8. 技术文档已同步 9. 已通知相关团队## 输出格式逐项输出检查结果通过/失败/跳过并给出总体发布建议。这个 SKILL.md 大约 400 tokensdescription 只有 30 tokens。技能内容清晰、步骤可执行references 目录里存放详细的环境变量清单只在需要时读取。八、小结渐进式披露不是一个复杂的技术——它的本质是一种信息节制的哲学用分层加载的方式让上下文里的信息量始终和任务需求保持匹配。SkillRegistry 是这个机制的调度者负责在合适的时机把合适的信息注入上下文。Token 预算控制策略提供了量化的约束让设计决策有据可依。多技能协同则是这套机制在复杂场景下的自然延伸。掌握这些原则后你设计出来的技能包不只是能用而是高效且可持续地使用。下一篇将展开 Agent Skills 的生态全景——主流平台的支持情况、官方技能库资源、社区工具链以及技能如何在不同工具间共享。