优化 Skill Description：触发准确率提升指南

Overview

Skill 的 description 字段是 Agent 决定是否激活 Skill 的唯一依据。上端 spec 不足 → 该触发时不触发（漏判）；过宽 → 不该触发时触发（误判）。本文梳理系统性测试和优化 description 的方法论。

为什么重要

description 写不好，最优秀的 Skill 也不会被触发——它是 Skill 通往 Agent 的唯一钥匙。但 description 优化没有量化指标就是凭直觉调字眼。本文给出可量化的「触发率 + 误触率」双指标测试法，把 prompt 工程从经验艺术变成可度量的工程实践。

为什么重要

description 写不好，最优秀的 Skill 也不会被触发——它是 Skill 通往 Agent 的唯一钥匙。但 description 优化没有量化指标就是凭直觉调字眼。本文给出可量化的「触发率 + 误触率」双指标测试法，把 prompt 工程从经验艺术变成可度量的工程实践。

Skill 触发原理

Agent 通过**渐进式披露（progressive disclosure）**管理上下文：

1. 启动时：仅加载所有 Skill 的 name + description（约 100 token/skill）
2. 匹配时：当用户任务匹配某个 description，Agent 加载完整 SKILL.md
3. 注意：简单任务（如”读这个 PDF”）可能不触发 PDF Skill，因为 Agent 基础工具就能处理。涉及专业知识的任务才是 description 产生差异的地方。

编写有效 Description 的原则

原则	说明	示例
祈使句措辞	告诉 Agent 何时行动	”Use this skill when…”
聚焦用户意图	描述用户想达成什么，非内部机制	—
宁可偏 pushy	显式列出适用上下文	”even if they don’t explicitly mention ‘CSV‘“
保持简洁	几句话到短段落	硬上限 1024 字符

设计触发 Eval 查询

查询结构

[
  { "query": "I've got a spreadsheet in ~/data/q4_results.xlsx...", "should_trigger": true },
  { "query": "whats the quickest way to convert this json to yaml", "should_trigger": false }
]

目标：约 20 条，8-10 条 should-trigger + 8-10 条 should-not-trigger。

Should-Trigger 查询维度

• 措辞变化：正式/随意/拼写错误/缩写
• 显式程度：直接命名领域 vs 描述需求不命名
• 详细程度：简洁 vs 上下文丰富（文件路径、列名）
• 复杂程度：单步 vs 多步嵌入

Should-Not-Trigger 查询：近误是关键

最有价值的负例是近误（near-misses）——共享关键词但实际需要不同的东西。

弱负例（没用）	强负例（有用）
“Write a fibonacci function"	"update the formulas in my Excel budget spreadsheet"
"What’s the weather today?"	"write a python script that reads a csv and uploads each row to postgres”

测试方法

对每条查询运行多次（建议 3 次），计算触发率（trigger rate）。针对非确定性行为：

• should-trigger 通过：触发率 > 0.5
• should-not-trigger 通过：触发率 < 0.5

建议写成脚本自动化运行（示例脚本见 raw 文件）。

训练/验证集划分

防止过拟合：

• 训练集（~60%）：用于识别失败、指导改进
• 验证集（~40%）：仅用于检查改进是否泛化，不参与优化决策

随机打乱，保持划分恒定。

优化循环

评估（训练+验证集）
  → 识别训练集失败
  → 修订 description（基于泛化原则，不添加失败查询的具体关键词）
  → 重复
  → 选最佳迭代（依据验证通过率，不一定是最后一个）

关键策略：

• 漏判 → description 太窄，拓宽范围
• 误判 → description 太宽，加”不做什么”的说明
• 如多次迭代仍无突破 → 尝试结构上不同的 description 方案，非渐进微调
• 检查 description 是否仍在 1024 字符内

通常 5 轮迭代足够。

优化前后对比

# 优化前
description: Process CSV files.

# 优化后
description: >
  Analyze CSV and tabular data files — compute summary statistics,
  add derived columns, generate charts, and clean messy data. Use this
  skill when the user has a CSV, TSV, or Excel file and wants to
  explore, transform, or visualize the data, even if they don't
  explicitly mention "CSV" or "analysis."

改进点：更具体说明做什么 + 更广泛说明何时适用 + 覆盖无需关键词的情况。

See Also

• Skill 开发综合指南 — Skill 完整开发框架
• Skill 评估与迭代 — Eval 驱动的品质改进
• Agent Skills 开放规范 — agentskills.io 格式规范