优化 Skill 描述
改进 Skill 描述,让它在收到相关 Prompt 时可靠触发。
Skill 只有得到激活才能发挥作用。Agent 主要根据 SKILL.md 前置元数据中的 description 字段,判断是否为当前任务加载某个 Skill。描述不够具体,该触发时可能不会触发;描述范围过宽,则可能在不适用的任务中触发。
本指南介绍如何系统地测试、改进 Skill 描述,提高触发准确率。
Skill 如何触发
Agent 通过渐进式披露管理上下文。启动时,只加载每个可用 Skill 的 name 和 description,据此判断它可能适用于哪些任务。用户任务与某段描述匹配后,Agent 会将完整的 SKILL.md 读入上下文,并遵循其中的指令。
这意味着,触发判断完全依赖描述。如果描述没有说明 Skill 在什么情况下有用,Agent 就不知道何时应该调用它。
还有一点需要注意:Agent 通常只在任务需要超出自身能力的知识或功能时,才会查阅 Skill。像“读取这份 PDF”这样简单的单步请求,即使与描述完全匹配,也可能不会触发 PDF Skill,因为 Agent 用基础工具就能完成。对于涉及陌生 API、特定领域工作流、不常见格式等专业知识的任务,精心编写的描述才更能发挥作用。
编写有效的描述
开始测试前,先了解好的描述应具备哪些特点:
- 使用指令式表达。 将描述写成对 Agent 的指令:“在……时使用这个 Skill”,而不是“这个 Skill 可以……”。Agent 正在判断是否采取行动,描述应明确告诉它何时行动。
- 关注用户意图,而非实现方式。 描述用户想实现什么,不必解释 Skill 的内部机制。Agent 匹配的是用户提出的请求。
- 明确、积极地说明适用场景。 列出 Skill 适用的情境,包括用户没有直接说出领域名称的情况,例如“即使用户没有明确提到‘CSV’或‘分析’”。
- 保持简洁。 通常几句话到一个短段落就足够:既能涵盖 Skill 的适用范围,也不会在同时加载大量 Skill 时占用过多上下文。规范规定,描述最多为 1,024 个字符。
设计触发评测查询
测试触发行为需要一组评测查询:模拟真实用户的 Prompt,并标注每条查询是否应触发这个 Skill。
eval_queries.json
[
{ "query": "我在 ~/data/q4_results.xlsx 里有个电子表格,C 列是营收,D 列是支出。能加一列利润率,并把低于 10% 的值突出显示吗?", "should_trigger": true },
{ "query": "这个 json 文件转 yaml 最快怎么弄", "should_trigger": false }
]准备约 20 条查询:8–10 条应触发,8–10 条不应触发。
应触发的查询
这类查询用于检验描述是否准确涵盖了 Skill 的适用范围。可以从几个维度设计变化:
- 表达方式:既有正式表达,也有随意表达,还可以包含错别字或缩写。
- 明确程度:有些直接说出 Skill 对应的领域(“分析这份 CSV”),有些只描述需求,不点明领域(“老板想根据这个数据文件做张图”)。
- 细节数量:简短请求与包含大量背景的请求搭配使用,例如一句“分析我的销售 CSV,做张图”,以及包含文件路径、列名和事情背景的较长消息。
- 复杂程度:改变步骤数量和需要作判断的环节。既包含单步任务,也包含多步工作流,以检验当 Skill 对应的任务嵌在较长流程中时,Agent 能否识别其相关性。
最有价值的应触发查询,是那些 Skill 能提供帮助、但仅看查询本身又不容易发现二者联系的情况。描述的措辞在这些场景下才会产生差别。如果查询已经明确要求完成 Skill 的核心任务,任何合理的描述通常都能触发。
不应触发的查询
最有价值的反例是看似相关、实际不适用的查询:它们与 Skill 共享关键词或概念,却需要完成不同的任务。这类查询检验的是描述是否精确,而不只是覆盖面是否足够广。
对于分析 CSV 的 Skill,以下反例价值较低:
“写一个斐波那契函数”——显然无关,无法检验什么。“今天天气怎么样?”——没有重合的关键词,太容易区分。
更有价值的反例:
“我需要更新 Excel 预算表中的公式”——涉及“电子表格”和“数据”概念,但需要编辑 Excel,而不是分析 CSV。“能写个 python 脚本,读取 csv,再把每行上传到我们的 postgres 数据库吗”——虽然涉及 CSV,任务却是数据库 ETL(抽取、转换、加载),而非数据分析。
让查询贴近实际
真实用户的 Prompt 往往包含通用测试查询所缺少的背景。可以加入:
- 文件路径(
~/Downloads/report_final_v2.xlsx) - 个人背景(
“我的经理让我……”) - 具体细节(列名、公司名、数据值)
- 随意表达、缩写,以及偶尔出现的错别字
测试描述能否触发 Skill
基本方法是:安装 Skill 后,将每条查询交给 Agent,观察它是否调用了该 Skill。先确认 Skill 已注册,且 Agent 能发现它。具体方式取决于客户端,例如放入 Skills 目录、写入配置文件,或通过命令行参数指定。
大多数 Agent 客户端都会提供某种观察执行过程的方式,例如执行日志、工具调用历史或详细输出,以便查看一次运行中查阅了哪些 Skill。具体做法参见客户端文档。如果 Agent 加载了这个 Skill 的 SKILL.md,就算触发;如果没有查阅便继续执行任务,就算未触发。
符合以下任一条件,查询就算“通过”:
should_trigger为true,且调用了 Skill;或should_trigger为false,且没有调用 Skill。
多次运行
模型行为具有不确定性,同一条查询可能在一次运行中触发 Skill,在下一次却不触发。将每条查询运行多次(可以从 3 次开始),计算触发率:调用 Skill 的运行次数占总运行次数的比例。
对于应触发的查询,触发率高于阈值才算通过(默认设为 0.5 比较合理)。对于不应触发的查询,触发率低于该阈值才算通过。
20 条查询各运行 3 次,共需调用 60 次,适合用脚本完成。下面是基本结构,请根据 Agent 客户端提供的能力,替换 claude 调用及 check_triggered 中的检测逻辑:
#!/bin/bash
QUERIES_FILE="${1:?Usage: $0 <queries.json>}"
SKILL_NAME="my-skill"
RUNS=3
# 本示例使用 Claude Code 的 JSON 输出检查是否调用了 Skill 工具。
# 请将此函数替换为适用于你的 Agent 客户端的检测逻辑。
# 调用过 Skill 时应返回 0(成功),否则返回 1。
check_triggered() {
local query="$1"
claude -p "$query" --output-format json 2>/dev/null \
| jq -e --arg skill "$SKILL_NAME" \
'any(.messages[].content[]; .type == "tool_use" and .name == "Skill" and .input.skill == $skill)' \
> /dev/null 2>&1
}
count=$(jq length "$QUERIES_FILE")
for i in $(seq 0 $((count - 1))); do
query=$(jq -r ".[$i].query" "$QUERIES_FILE")
should_trigger=$(jq -r ".[$i].should_trigger" "$QUERIES_FILE")
triggers=0
for run in $(seq 1 $RUNS); do
check_triggered "$query" && triggers=$((triggers + 1))
done
jq -n \
--arg query "$query" \
--argjson should_trigger "$should_trigger" \
--argjson triggers "$triggers" \
--argjson runs "$RUNS" \
'{query: $query, should_trigger: $should_trigger, triggers: $triggers, runs: $runs, trigger_rate: ($triggers / $runs)}'
done | jq -s '.'提示
如果 Agent 客户端支持,可以在结果明确后提前结束运行:Agent 已查阅 Skill,或已开始在不使用 Skill 的情况下工作。这样能显著减少完整评测所需的时间和费用。
划分训练集与验证集,避免过拟合
如果针对所有查询优化描述,就有过拟合的风险:描述只适用于这些特定表述,遇到新的表述便失效。
解决方法是将查询集拆分为:
- 训练集(约 60%):用于发现失败案例、指导改进的查询。
- 验证集(约 40%):单独留出,只用于检验改进能否适用于其他查询。
两组都应按比例包含应触发和不应触发的查询,避免把所有正例都分到同一组。随机打乱后划分,并在各轮迭代中保持划分不变,以便在相同条件下比较。
如果使用上文那样的脚本,可以将查询分别存入 train_queries.json 和 validation_queries.json,再分别运行脚本。
优化循环
- 在训练集与验证集上评测当前描述。训练集结果用于指导修改,验证集结果用于判断修改是否具备泛化能力。
- 找出失败案例:在训练集中,哪些应触发的查询没有触发?哪些不应触发的查询却触发了?
- 只根据训练集中的失败案例指导修改。无论亲自修改描述,还是让大语言模型(LLM)修改,都不要将验证集结果纳入修改过程。
- 修改描述。 重点是提高泛化能力:
- 如果应触发的查询未通过,描述可能过于狭窄。可以扩大适用范围,或补充 Skill 在什么情境下有用。
- 如果不应触发的查询发生误触发,描述可能过于宽泛。进一步说明 Skill不处理什么,或厘清它与相邻能力的边界。
- 不要从失败查询中直接提取特定关键词加入描述,这会导致过拟合。应找出这些查询代表的一般类别或概念,再据此调整。
- 如果几轮迭代后仍无进展,尝试从结构上重写描述,而不只是小幅修补。换一种组织方式或句式,可能解决反复润色也无法解决的问题。
- 确认描述始终不超过 1,024 个字符,优化过程中描述往往会越来越长。
- 重复步骤 1–3,直到训练集中的所有查询都通过,或不再有明显改善。
- 根据验证通过率选出最佳版本,也就是验证集中通过查询的比例。最佳描述不一定是最后一版;后期版本可能对训练集过拟合,验证通过率反而不及较早的版本。
通常 5 轮迭代就足够。如果效果没有改善,问题可能在查询本身,例如太简单、太难或标注不准确,而不在描述。
提示
skill-creatorSkill 可以自动完成整个循环:划分评测集、并行评估触发率、使用 Claude 提出描述改进方案,并生成可在运行过程中查看的实时 HTML 报告。
应用优化结果
选出最佳描述后:
- 更新
SKILL.md前置元数据中的description字段。 - 确认描述未超过 1,024 个字符的限制。
- 确认描述能按预期触发。可以手动尝试几条 Prompt,快速检查是否存在明显问题。若要更严格地测试,再编写 5–10 条全新查询,混合应触发与不应触发的情况,然后运行评测脚本。这些查询没有参与优化过程,能更客观地检验描述的泛化能力。
优化前后对比:
# 优化前
description: 处理 CSV 文件。
# 优化后
description: >
分析 CSV 和表格数据文件——计算汇总统计值、添加衍生列、
生成图表,并清理杂乱数据。用户持有 CSV、TSV 或 Excel
文件,且希望探索、转换数据或将数据可视化时,使用这个 Skill,
即使用户没有明确提到“CSV”或“分析”。优化后的描述更具体地说明了 Skill 做什么(汇总统计、衍生列、图表、清理),也更全面地说明了适用情境(CSV、TSV、Excel,以及没有明确关键词的情况)。
后续步骤
Skill 能稳定触发后,还需要评估它能否产出高质量结果。参见评估 Skill 输出质量,了解如何设计测试用例、评判结果并持续迭代。