智能体技能配置文件的编写实践与优化

一、背景：智能体能力扩展的第三种路径

在扩展大语言模型能力的工程实践中，业界通常有三条路径：

1. 函数调用（Function Calling）：模型输出结构化调用参数，由外部运行时执行真实函数；
2. 代码执行（Code Execution）：模型生成可执行代码，在沙箱中运行并回传结果；
3. 提示词注入（Prompt Injection as Capability）：模型不执行任何代码，而是加载一组专用指令，改变后续请求的处理方式。

智能体技能（Agent Skills）属于第三条路径。它是一套基于提示词的高级元工具架构（Meta-tool Architecture）：技能以文件夹形式组织，内含指令（Instructions）、脚本（Scripts）与资源（Resources），由智能体按需加载。技能本身不是可执行代码，不启动后台服务，也不进行函数调用；它也不硬编码在系统提示词中，而是作为 API 请求结构中的独立模块存在。

理解这一点至关重要：技能的本质是“上下文改造器”。当某项技能被调用时，它会同时修改两类上下文——对话上下文（注入领域指令提示词）与执行上下文（调整工具权限，必要时切换模型）。技能不直接执行操作，而是展开为详细提示词，让模型进入“解决某一类特定问题”的准备状态。

二、运行机制：技能是如何被选中的

在代码层面，不存在算法化的技能选择逻辑，也没有独立的意图识别模型。所有决策都发生在模型的推理过程中，依据仅仅是系统提示词里呈现的文本描述。这意味着：技能配置文件的写作质量，直接决定了调用准确率。

一次典型请求中，模型会接收三类内容：

• 用户消息（User Message）；
• 可用工具列表（如读文件、写文件、执行命令等基础工具）；
• 技能工具（Skill Tool）——其说明中包含一份格式化清单，汇总所有可用技能的名称、描述及其他字段。

模型读取这份清单，借助原生语言理解能力将用户意图与技能描述做匹配。因此，技能清单相当于一份“能力目录”，而每条技能描述就是这份目录中的条目文案。目录文案写得含糊，模型就会选错、漏选或过度调用。

三、配置文件的结构设计

一个可维护的技能目录通常采用如下组织方式：

skills/
├── skill-name-a/
│   ├── SKILL.md          # 主指令文件（必需）
│   ├── references/       # 按需加载的参考文档
│   └── assets/           # 模板、示例数据等静态资源
└── skill-name-b/
    └── SKILL.md

主指令文件承担“入口”职责，应保持精简，把体积大、低频使用的细节下沉到参考文档中按需加载。这是控制上下文预算的关键：技能清单本身会常驻上下文，而参考文档只在需要时被读取。

主指令文件的推荐骨架：

---
name: skill-name
description: 一句话说明能力 + 明确的触发场景 + 不适用场景
---
# 目标
（这个技能要解决什么问题，产出什么结果）
# 输入约定
（需要用户提供哪些信息；缺失时如何追问）
# 执行步骤
1. ……
2. ……
# 输出格式
（结构化模板，字段与顺序明确）
# 边界与禁止项
（不得做什么；超出范围时如何回退）
# 示例
（一个正例，一个反例）

四、编写要点：让描述“可被匹配”

4.1 描述字段是最重要的字段

描述（description）是模型做匹配时的唯一依据。好的描述应同时回答三个问题：做什么、什么时候用、什么时候不用。

反面示例：

description: 处理文档。

正面示例：

description: 将结构化数据转换为规范化报表。
当用户要求"生成周报/月报/汇总表"或提供原始数据并要求整理时使用。
不适用于自由格式的创意写作，也不适用于需要联网检索的任务。

加入“不适用场景”能显著降低误触发率——模型在边界清晰时更保守，在边界模糊时更倾向于“试一试”。

4.2 用声明式语言，而非过程式命令

技能是提示词而非程序，因此指令应描述约束与目标，而不是模拟控制流。与其写“如果变量 X 为真则跳转到步骤 3”，不如写“当输入中包含时间范围时，输出必须覆盖该范围；否则默认最近 7 天”。前者制造了一个模型无法真正执行的假象，后者给出的是可验证的判断标准。

4.3 明确输入契约与追问策略

技能被触发时，用户往往只提供了部分信息。配置文件应显式规定：哪些字段必需、缺失时是先追问还是先按默认值推进、默认值是什么。缺少这一节，模型容易在信息不足时自行编造参数，产生不可控输出。

4.4 输出格式要可校验

给出字段名、顺序、类型与空值表示法，并附一个小样例。可校验的格式让模型有明确的“完成标准”，也便于调用方做自动化解析。

4.5 示例要成对出现

一个正例展示期望行为，一个反例展示应被拒绝或回退的情形。反例尤其重要，它把“边界”从抽象描述变成了具体情境。

五、上下文预算与渐进式加载

技能系统的常见失效模式不是“能力不够”，而是“上下文被撑爆”。实践原则：

• 清单层精简：常驻的技能描述控制在数十字到百余字，只保留匹配所需的信息；
• 指令层分层：主文件只写主干流程，细节放参考文档；
• 资源层惰性加载：模板、长表格、大段样例只在明确需要时读取；
• 避免重复：多个技能共用的通用规范抽成公共片段，避免在每个技能里重复粘贴。

这种“清单 → 主指令 → 参考文档 → 资源”的四级结构，本质上是把上下文当成缓存来管理：越常用的内容越靠近顶层，越冷门的内容越靠后。

六、常见失效模式与排查清单

现象	可能原因	调整方向
该调用的场景没调用	描述缺少触发词，或触发场景写得太抽象	补充用户真实会说的表述
不该调用的场景被调用	描述过宽，未写不适用场景	增加否定边界与回退策略
调用后输出格式不稳定	输出契约缺失或样例不足	补字段表 + 正反例
长任务中途丢失约束	指令过长，关键约束被稀释	拆分技能，约束前置并加粗
多技能相互抢占	描述语义重叠	收敛职责，明确优先级与组合方式

调试时的通用方法：把技能清单打印出来，逐条问自己“仅凭这句话，一个不了解背景的工程师能否判断何时该用它”。如果答案是否定的，模型多半也判断不了。

七、组合与治理

当技能数量增长到十几个以上，治理问题开始显现：

• 职责单一：一个技能只解决一类问题，避免“万能技能”；
• 显式组合：需要多步协作时，在指令中写明“先完成 A，再基于 A 的产出执行 B”，而不是依赖模型自行编排；
• 权限最小化：技能若声明调整工具权限，应遵循最小必要原则，只开放完成该任务所必需的写操作或命令执行能力；
• 版本与变更记录：描述文案的改动会直接影响调用行为，应像对待接口契约一样对待它，变更时记录原因。

八、结语

智能体技能的价值不在于“让模型多会一件事”，而在于把领域知识以可加载、可复用、可治理的方式组织起来。它的运行完全依赖提示词匹配，因此配置文件既是能力定义，也是接口文档，更是调度策略。把描述写准、把边界写清、把输出写死、把上下文管好——这四件事做到位，技能的调用准确率与输出稳定性会有量级上的改善。