优化 skill 描述

​

skill 触发机制是如何工作的

​

编写有效的描述

• 使用祈使式表达。 把描述写成对 agent 的指令，例如“在……情况下使用这个 skill”，而不是“这个 skill 会做……”。agent 正在决定是否采取行动，所以你应该直接告诉它什么时候行动。
• 关注用户意图，而不是实现细节。 描述用户想达成什么，而不是 skill 内部如何实现。agent 匹配的是用户提出的需求。
• 宁可写得主动一点。 明确列出 skill 适用的上下文，包括用户没有直接点出领域名称的情况，例如“即使用户没有显式提到 ‘CSV’ 或 ‘analysis’ 也应使用。”
• 保持简洁。 一般来说，几句话到一个短段落最合适：既足够覆盖 skill 的边界，又不会因为描述过长，让 agent 在加载大量 skills 时上下文膨胀。规范对它也有 1024 个字符的硬限制。

​

设计触发 eval 查询

[
  { "query": "I've got a spreadsheet in ~/data/q4_results.xlsx with revenue in col C and expenses in col D — can you add a profit margin column and highlight anything under 10%?", "should_trigger": true },
  { "query": "whats the quickest way to convert this json file to yaml", "should_trigger": false }
]

​

应触发的查询

• 表达方式：有些正式，有些口语化，有些带错别字或缩写。
• 显式程度：有些直接点出 skill 所属领域（例如“分析这个 CSV”），有些只描述需求而不点名（例如“我老板想要这份数据文件生成一张图表”）。
• 细节丰富度：混合简短提示词和上下文丰富的提示词，例如短句“分析我的销售 CSV 并做一张图”，以及包含文件路径、列名和背景说明的长消息。
• 复杂度：变化步骤数量和决策点。既要有单步骤任务，也要有多步骤工作流，用来测试当 skill 所解决的问题被埋在更长任务链中时，agent 是否仍能识别它相关。

​

不应触发的查询

• "Write a fibonacci function" — obviously irrelevant, tests nothing.
• "What's the weather today?" — no keyword overlap, too easy.

• "I need to update the formulas in my Excel budget spreadsheet" — shares “spreadsheet” and “data” concepts, but needs Excel editing, not CSV analysis.
• "can you write a python script that reads a csv and uploads each row to our postgres database" — involves CSV, but the task is database ETL, not analysis.

​

提高真实性的小建议

• File paths (~/Downloads/report_final_v2.xlsx)
• Personal context ("my manager asked me to...")
• Specific details (column names, company names, data values)
• Casual language, abbreviations, and occasional typos

​

测试描述是否会触发

• should_trigger is true and the skill was invoked, or
• should_trigger is false and the skill was not invoked.

​

多次运行

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

# This example uses Claude Code's JSON output to check for Skill tool calls.
# Replace this function with detection logic for your agent client.
# Should return 0 (success) if the skill was invoked, 1 otherwise.
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 '.'

​

用 train / validation 切分避免过拟合

• Train set（约 60%）：用来发现问题并指导你改进的查询。
• Validation set（约 40%）：提前留出来，只用来检查改进是否真的具备泛化能力的查询。

​

优化闭环

1. 评估当前描述在 train 和 validation 两个集合 上的表现。train 结果用于指导改动，validation 结果用来判断这些改动是否具备泛化性。
2. 在 train set 中识别失败样本：哪些“应触发”的查询没有触发？哪些“不应触发”的查询却触发了？
   • 只有 train set 中的失败样本可以用来指导改动。无论是你自己改描述，还是让 LLM 帮你优化，都不要把 validation set 的结果带入这个过程。
3. 修订描述。 重点是做泛化而不是死记：
   • 如果“应触发”的查询没有触发，说明描述可能太窄。你需要适度扩大范围，或者补充说明这个 skill 在什么情况下有帮助。
   • 如果“不应触发”的查询被误触发，说明描述可能太宽。你需要补充这个 skill 不做什么，或者更清楚地划定它和相邻能力之间的边界。
   • 不要把失败查询里的特定关键词直接塞进描述里，那就是过拟合。应该去提炼这些查询背后的通用类别或概念，并针对那个层面做修订。
   • 如果几轮下来都卡住了，不要只做微调，可以尝试从结构上重写描述。换一种 framing 或句式，有时比局部修补更有效。
   • 同时检查描述是否仍然低于 1024 字符限制。因为在优化过程中，描述很容易越写越长。
4. 重复步骤 1 到 3，直到 train set 全部通过，或者你已经看不到有意义的提升。
5. 根据 validation pass rate，也就是 validation set 中通过查询的比例，选出最佳版本。注意，最好的描述未必是最后一版；有时中间某一版的 validation 表现反而优于后续那些过拟合到 train set 的版本。

​

应用优化结果

1. 更新 SKILL.md frontmatter 中的 description 字段。
2. 确认描述仍低于1024 字符限制。
3. 验证这个描述是否按预期触发。你可以先手动试几条 prompt 做快速 sanity check。若要更严格地测试，可以另外再写 5 到 10 条全新的查询（混合“应触发”和“不应触发”），然后跑一次 eval 脚本。因为这些查询从未参与过优化过程，所以它们能更真实地检验描述是否具备泛化能力。

# Before
description: Process CSV files.

# After
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."

​

下一步