Agent Skills

随着 agent 覆盖的业务场景越来越多，系统提示词会不断膨胀——客服场景的退款规则、编程场景的代码规范、文档场景的格式要求……全部塞进一个提示词，会带来两个问题：

• 浪费 token：大部分内容与当前任务无关。
• 注意力被稀释：上下文中无关信息过多会稀释模型对关键内容的注意力（这一问题即 压缩 一节讨论的“上下文腐化”）。

这就是从静态提示工程到动态提示词的自然演进：不是把所有知识一次性塞给 agent，而是让它按需加载。Agent Skills 系统正是这一理念的工程化实现。

Skills：领域能力的可组合单元

Agent Skills 的核心思想是将 agent 的能力模块化为独立的、可按需加载的知识包。每个 Skill 本质上是一套包含专业领域指导的提示词集合，就像为新员工准备的某个专项任务的操作手册。与把所有指令塞入单一系统提示词的做法不同，Skills 采用渐进式披露（Progressive Disclosure）的设计哲学——先给 agent 看一份目录摘要，需要时再加载完整内容，就像你不会把公司所有部门的操作手册都堆到新员工桌上，而是先给一份总目录，需要哪本再去取。

• 第一层（元数据）：每个 Skill 必须包含一个 SKILL.md，开头是 YAML frontmatter，含 name 和 description 两个字段。框架在启动时扫描所有已安装的 Skill，将它们的 name 与 description（仅占数百个 token）注入上下文，使 agent 在不消耗大量上下文的前提下知晓自己拥有哪些专业能力。
• 第二层（核心流程）：当 agent 判断某任务需要特定 Skill 时，通过专用工具加载完整的 SKILL.md，内容作为 tool result 出现在对话历史中。
• 第三层（细则）：通过文件引用深入到更详细的子文档，agent 按需选择性阅读。

元数据中的 description 是路由决策的关键——它应当足够短，但写法要像路由条件而非功能介绍。最直接的写法是 “Use when / Don’t use when” 加上几条反例。实践中，缺少反例的描述会让路由准确率明显下降：宽泛的描述（如 “help with backend”）会在不相关任务上频繁误触发。“何时该用我”比“我能做什么”重要得多。

Skills 的实现方式与权衡

理解了 Skills 是什么之后，接下来是一个更具体的工程问题：Skill 内容放在上下文的什么位置？这直接关系到 KV Cache 效率和指令遵循效果。理论上有两种朴素方案，但都有明显代价；生产实现采用的是回避了两者痛点的第三种方案。

• 方式一：注入系统提示词。 模型对 system 位置的指令遵循最强，执行效果最好；但每次加载新 Skill 都改变 system 消息，导致 KV Cache 前缀失效。频繁切换 Skill 时缓存反复失效。
• 方式二：作为普通文件读取，内容出现在上下文中间。 完全不影响 KV Cache（system prompt 不变），但对模型在长上下文中间位置的指令遵循能力要求更高——不同模型对这种模式的支持差异很大。
• 方式三（生产实现）：元数据作为动态上下文提供，完整内容通过专用工具按需加载。 把 Skill 的“路由”和“执行”分离：模型先获得可用 Skill 的元数据（name + description，数百 token）用于判断相关性；只有 Skill 被选中后，才进一步加载完整 SKILL.md。这种设计兼顾了上下文开销、Prompt Cache 复用与指令遵循。

需要厘清一个常见误解：“对 KV Cache 友好”并非“零成本”——首次 emit 那几百到几千 token 终归要付一次写入代价。它的准确含义是一次性写入、永久受益：要让模型知道某个 Skill 的存在，至少得让它进缓存一次，之后整个会话都不再重复。对比之下，把同样的信息塞进 system prompt，每次更新都会让其下游的整条 trajectory 失效——那才是真正的不友好。

工程实践

Zapvol 采用的正是方式三，落在 view_skill 工具上（遵循 agentskills.io 规范）：会话内先注入已安装 Skill 的 name + description 元数据（渐进式披露的第一层），agent 判断需要时调用 view_skill 分两阶段加载——先发现、再按需拉取对应 SKILL.md 的完整内容，作为 tool result 追加到上下文末尾。因为只在末尾追加、绝不改写前缀，它对 KV Cache 是“一次性写入、永久受益”。

相关阅读

• 提示工程——静态系统提示词写什么；Skills 是它的“按需”反面。
• KV Cache 设计——渐进式披露为何对缓存友好。
• Agent 状态栏——“会话中动态补充系统上下文”的另一个例子，Skill 元数据列表可看作其中一种。

来源

• Equipping Agents for the Real World with Agent Skills — Anthropic, 2025