优化 skill 描述

1. 技能触发的工作原理#

代理使用 渐进式披露 来管理上下文。启动时，它们只加载每个可用技能的 name 和 description——足以判断技能何时可能相关。当用户任务与 description 匹配时，代理会将完整的 SKILL.md 读入上下文并遵循其指令。

这意味着 description 承担了触发的全部责任。如果 description 没有传达技能的适用场景，代理就不知道去调用它。

一个重要细节：代理通常只在任务需要它们自身无法处理的知识或能力时，才会考虑技能。像 “读取这个 PDF” 这样简单、一步到位的请求，即使描述完美匹配，也可能不会触发 PDF 技能，因为代理可以用基础工具处理。涉及专业知识——不熟悉的 API、领域特定工作流或非通用格式——的任务，才是精心编写的描述能发挥作用的场景。

2. 编写有效的描述#

在测试之前，了解好的描述是什么样的会很有帮助。以下是一些原则：

• 使用祈使语气。将描述表述为对代理的指令：“当……时使用此技能”，而不是 “此技能执行……”。代理需要决定是否行动，所以告诉它何时行动。
• 关注用户意图，而非实现细节。描述用户试图达成什么，而不是技能的内部机制。代理是根据用户提出的需求进行匹配的。
• 宁可“强势”一些。明确列出技能适用的上下文，包括用户没有直接提及领域的情况：“即使用户没有明确提到‘CSV’或‘分析’”。
• 保持简洁。几句话到一小段通常就足够了——长度要足以涵盖技能的适用范围，又足够短，不至于在多个技能中膨胀代理的上下文。 agentskills.io 规范 强制规定了 1024 个字符的硬限制。

3. 设计触发评估查询#

为了测试触发，你需要一组评估查询——这些查询是真实的用户提示，并标注了它们是否应触发你的技能。

1
[
2
  { "query": "我有个电子表格在 ~/data/q4_results.xlsx，C 列是收入，D 列是支出——你能添加一个利润率列，并把低于 10% 的标出来吗？", "should_trigger": true },
3
  { "query": "把这个 json 文件转成 yaml 最快的方法是什么", "should_trigger": false }
4
]

目标大约 20 个查询：8-10 个应触发和 8-10 个不应触发。

4. 测试描述是否触发#

基本方法：在安装了技能的代理中运行每个查询，观察代理是否调用该技能。确保技能已注册且可被代理发现——具体方式因客户端而异（例如，技能目录、配置文件或 CLI 标志）。

大多数代理客户端提供某种形式的可观测性——执行日志、工具调用历史或详细输出——让你能查看运行期间咨询了哪些技能。请查阅客户端文档了解详情。如果代理加载了你的 SKILL.md，则表示技能已触发；如果代理未咨询它就直接进行，则表示未触发。

一个查询“通过”的条件是：

• should_trigger 为 true 且技能被调用，或
• should_trigger 为 false 且技能未被调用。

1
#!/bin/bash
2
QUERIES_FILE="${1:?Usage: $0 <queries.json>}"
3
SKILL_NAME="my-skill"
4
RUNS=3
5

6
# 此示例使用 Claude Code 的 JSON 输出来检查 Skill 工具调用。
7
# 请将此函数替换为你代理客户端的检测逻辑。
8
# 如果技能被调用，应返回 0（成功），否则返回 1。
9
check_triggered() {
10
  local query="$1"
11
  claude -p "$query" --output-format json 2>/dev/null \
12
    | jq -e --arg skill "$SKILL_NAME" \
13
      'any(.messages[].content[]; .type == "tool_use" and .name == "Skill" and .input.skill == $skill)' \
14
      > /dev/null 2>&1
15
}
16

17
count=$(jq length "$QUERIES_FILE")
18
for i in $(seq 0 $((count - 1))); do
19
  query=$(jq -r ".[$i].query" "$QUERIES_FILE")
20
  should_trigger=$(jq -r ".[$i].should_trigger" "$QUERIES_FILE")
21
  triggers=0
22

23
  for run in $(seq 1 $RUNS); do
24
    check_triggered "$query" && triggers=$((triggers + 1))
25
  done
26

27
  jq -n \
28
    --arg query "$query" \
29
    --argjson should_trigger "$should_trigger" \
30
    --argjson triggers "$triggers" \
31
    --argjson runs "$RUNS" \
32
    '{query: $query, should_trigger: $should_trigger, triggers: $triggers, runs: $runs, trigger_rate: ($triggers / $runs)}'
33
done | jq -s '.'

5. 使用训练/验证拆分避免过拟合#

如果你针对所有查询优化描述，就有过拟合的风险——编写出的描述仅适用于这些特定措辞，而在新查询上失败。

解决方案是拆分查询集：

• 训练集（约 60%）：用于识别失败并指导改进的查询。
• 验证集（约 40%）：留出的查询，仅用于检查改进是否具有泛化性。

确保两个集合都包含应触发和不应触发查询的适当比例——不要不小心把所有正例都放在一个集合中。随机打乱，并在各迭代中保持拆分固定，以便进行同类比较。

如果你使用类似上述的脚本，可以将查询拆分为两个文件——train_queries.json 和 validation_queries.json——并分别针对每个文件运行脚本。

6. 优化循环#

1. 评估当前描述在 训练集和验证集 上的表现。训练结果指导你的修改；验证结果告诉你这些修改是否具有泛化性。
2. 识别失败在 训练集 中：哪些应触发查询没有触发？哪些不应触发查询触发了？
   • 仅使用训练集的失败来指导修改——无论你自己修改描述还是提示 LLM，都要将验证集结果排除在流程之外。
3. 修改描述。专注于泛化：
   • 如果应触发查询失败，说明描述可能过于狭窄。扩大范围或添加关于技能适用场景的上下文。
   • 如果不应触发查询误触发，说明描述可能过于宽泛。增加关于技能 不 做什么的特定说明，或明确此技能与相邻能力之间的边界。
   • 避免添加失败查询中的具体关键词——那是过拟合。相反，找到这些查询所代表的一般类别或概念，并针对该类别进行调整。
   • 如果经过几次迭代仍无进展，尝试从结构上重新构思描述，而不是增量调整。不同的表述方式或句子结构可能突破微调无法解决的问题。
   • 检查描述是否保持在 1024 个字符的限制内——描述在优化过程中往往会变长。
4. 重复步骤 1-3，直到所有 训练集 查询都通过，或你不再看到有意义的改进。
5. 选择最佳迭代根据其验证通过率——验证集 中通过查询的比例。请注意，最佳描述可能不是你生成的最后一个；早期的迭代可能比后期过拟合到训练集的迭代具有更高的验证通过率。

五次迭代通常足够。如果性能没有提升，问题可能出在查询本身（太容易、太难或标签不佳），而非描述。

7. 应用结果#

选定最佳描述后：

1. 更新 SKILL.md 前置元数据中的 description 字段。
2. 确认描述不超过 1024 字符限制。
3. 验证描述能按预期触发。手动尝试几个提示作为快速健全性检查。如需更严格的测试，编写 5-10 个新查询（混合应触发和不应触发），并通过评估脚本运行——由于这些查询从未参与优化过程，它们能真实地检验描述是否具有泛化性。

修改前后：

1
# 修改前
2
description: Process CSV files.
3

4
# 修改后
5
description: >
6
  分析 CSV 和表格数据文件——计算汇总统计量、
7
  添加派生列、生成图表，并清理杂乱数据。当用户有 CSV、TSV 或 Excel 文件，并希望探索、转换或可视化数据时使用此技能，即使用户没有明确提到“CSV”或“分析”。

改进后的描述在技能具体做什么（汇总统计、派生列、图表、清理）方面更明确，在适用场景（CSV、TSV、Excel；即使没有明确关键词）方面更宽泛。

8. 后续步骤#

一旦技能能可靠触发，你就需要评估它是否能产生良好的输出。请参阅 skill 评估 ，了解如何设置测试用例、对结果进行评分和迭代。