Agent Skills 渐进式披露
为什么需要从静态提示工程转向动态提示词？
- 膨胀: 业务场景变多后，客服退款规则、编程代码规范、文档格式要求全塞进一个系统提示词;
- 问题一: 浪费 token——大部分内容与当前任务无关;
- 问题二: 注意力被稀释——无关信息过多会削弱模型对关键内容的注意力，即 上下文腐化;
- 演进: 不是把所有知识一次性塞给 Agent，而是让它按需加载;
- 定义: Agent Skills 是把 Agent 能力模块化为独立、可按需加载的知识包的机制;
- 本质: 每个 Skill 是一套包含专业领域指导的提示词集合，像某个专项任务的操作手册;
- 比喻: 不把公司所有部门的操作手册都堆到新员工桌上，而是先给总目录，需要哪本再取;
Skills 的渐进式披露分哪三层？
| 层 | 内容 | 时机 |
|---|---|---|
| 元数据 | SKILL.md 顶部的 YAML frontmatter（name、description） | 主体正文加载前对 Agent 可见 |
| 核心流程 | 完整 SKILL.md 正文 | Agent 判断任务需要该 Skill 时加载 |
| 细则 | 被引用的子文档，如 html2pptx.md、reference.md | 按具体需求选择性深入 |
- 目录的作用: 提供可发现性，让 Agent 先判断是否需要某项能力，而不必为所有能力支付完整上下文成本;
- 目录位置: 不同运行时可以把目录放在不同的上下文层，但都服务于可发现性而非承载完整流程;
- 细则例子: PPTX Skill 中，
html2pptx.md给出通过 HTML 模板创建 PowerPoint 的工作流，reference.md给出格式技术细节; - 核心流程例子: 如何用 markitdown（Microsoft 开源的文档转 Markdown 工具）提取文本、如何解压 PPTX 访问 XML 结构、关键文件路径约定;
description 字段应该怎么写？
- 定位: 是路由决策的关键，既要足够短（控制常驻 token 量），又要像路由条件而非功能介绍;
- 写法: 明确“何时使用”和“何时不使用”的边界;
- 反例库: 给出几条典型反例，减少宽泛匹配带来的误触发;
- 反面示范: “help with backend”等于任何后端工作都能触发，路由必然失准;
- 原则: “何时该用我”比“我能做什么”重要得多;
- 定位澄清: 这是路由提示的写作建议，不是额外的格式字段;
Skill 有哪些触发方式？
- 触发方式一（斜杠命令）: 用户显式输入
/pptx，由客户端在本地拦截并展开，模型不必先发起一次工具调用; - 触发方式二（模型自主）: 模型读过元数据目录后判断需要某 Skill，调用专用 Skill 工具，比前者多一次 ReAct 往返;
- 落点一致: 两条路径最终都把 Skill 正文在调用位置注入会话;
- Claude Code 细节: 正文作为 user message 加入；模型自主触发时返回的 tool result 只是一句“正在启动 Skill”的占位符，不承载正文;
- 无专用激活工具时: 用通用文件读取工具去读
SKILL.md，正文以 tool result 形式进入上下文; - 状态追踪: 模型自主触发时，轨迹里能看到完整的
Skill(skill: "pptx")tool_use → 占位符 tool_result → 正文作为独立 user 消息;
Skills 在上下文中具体处于什么位置？
- 标准层: 规范规定的是加载时序，而不是消息角色——目录必须先于正文可发现，正文在 Skill 被选中后按需加载;
- 实现自由度: 具体消息角色、包装方式以及目录是否每轮重建，都由 Agent Harness 决定;
- Claude Code: 采用渐进式目录与调用时追加正文——目录作为运行时上下文消息提供，完整指令在调用位置作为 user message 注入;
- 术语澄清: “system prompt”可用于描述逻辑上的稳定指令层，但不应被理解为所有客户端都使用 API 的
role: "system"; - OpenAI Codex: 在每轮上下文构造阶段重新渲染 Skills catalog 作为
developer上下文片段；显式选中的 Skill 正文以带<skill>标记的user片段注入；其他来源的 Skill 可经专用工具按需读取; - 共同原则: 少量目录常驻、完整正文按需加载——这是 Skills 兼顾动态加载能力与上下文开销的关键;
- 版本风险: Agent Harness 发展很快，读到文档时实现可能已经改变;
- 缓存代价: “对 KV Cache 友好”并非“零成本”——目录首次进入请求需要处理，完整正文首次加载也会产生新增计算;
- 缓存收益: 前缀保持稳定时后续请求可复用缓存，无需启动时加载所有 Skill 正文，也无需每次调用新 Skill 时回头改写已建立的上下文;
Skills 与工具（Tools）是什么关系？
- 对比: 把所有专用代码工具定义都放在系统提示词，数量膨胀会消耗大量 token 并干扰注意力;
- 替代: Skill + 通用执行器模式下，工具数量始终很少（如第五章所示仅需七个核心工具）;
- 收益: Skill 内容通过渐进式披露按需加载，不影响已缓存的前缀;
- 定位: 从上下文管理角度看，Skills 机制对 KV Cache 极为友好;
- 展开: 两种形态的详细对比与选择框架见第四章；一项经验应写成知识、指令、程序还是模型参数见第九章;