Skills 説明最適化テクニック

description フィールドは Skill トリガーの唯一の判断基準です。

よく書かれた description は、Skill を正しいタイミングでトリガーし、無関係なシナリオで Claude に干渉するのを防ぎます。


Description の役割と制限

Claude は特定の Skill を使用するかどうかを決定するとき、description フィールドのみを読み、SKILL.md の本文を事前に読みません。

つまり、description は2つのことを同時に担う必要があります:Skill が何ができるかを説明することと、いつ使うべきかを示すことです。

description の理想的な長さは50〜150文字です。短すぎるとトリガーが不正確になり、長すぎるとコンテキスト制限を超える可能性があり、Claude が素早くスキャンして比較することが難しくなります。


Description の4要素構造

要素役割例
コア機能を一言でSkill が何であるかを最も直接的に説明する「Excel および CSV 形式の表データを処理する」
具体的な機能の列挙代表的な操作を3〜5つ列挙する「データクレンジング、統計分析、グラフ生成を含む」
トリガーシナリオの説明Claude にいつ使うべきかを伝える「ユーザーがデータ分析、レポート、統計に言及したときにトリガー」
促進的な文言(オプション)「低トリガー率」の問題を解決する「ユーザーが形式を明確に言及していなくても、表データに関わる場合は使用すべき」
---
name: data-analyzer
description: >
  处理 Excel(.xlsx)和 CSV 格式的表格数据,包括数据读取、
  清洗去重、统计分析(均值/中位数/分布)、生成可视化报告。
  当用户需要分析数据文件、生成统计报告、处理表格、
  查找数据规律时应优先使用此 Skill,即使用户只是上传了
  一个数据文件并询问"帮我看看这个"。
---

よくある Description の書き方の問題

問題例(誤り)修正の方向性
機能だけを書き、トリガーシナリオを書かない「データを分析するツール」「ユーザーが……のときにトリガー」を追加する
説明が広すぎる「ファイルを処理する汎用ツール」具体的なファイルタイプと操作を列挙する
Skill の内部実装用語を使用する「pandas を呼び出して分析する」ユーザー視点のビジネス記述に変更する
他の Skill との境界が不明確2つの Skill が両方とも「ドキュメントを処理する」と書いているそれぞれのファイルタイプまたは操作タイプを明確に区別する

自動化ツールで Description を最適化する

skill-creator は description 自動最適化スクリプトを提供し、反復テストを通じてトリガー率が最も高い書き方を見つけ出します。

ステップ1:テストケースを準備する

例

[
  {
    "id": "should_trigger_01",
    "prompt": 「サンプル_sales.csv を分析して、月次売上トレンドを特定してください」,
    "expected": true,
    "note": 「典型的なデータ分析リクエスト」
  },
  {
    "id": "should_trigger_02",
    "prompt": 「この Excel ファイルのどの列に空値がありますか?集計してください」,
    "expected": true,
    "note": 「データ品質チェックに関するもの」
  },
  {
    "id": "should_not_trigger_01",
    "prompt": 「Excel と CSV の違いは何ですか?」,
    "expected": false,
    "note": 「知識Q&A、Skill は不要」
  },
  {
    "id": "should_not_trigger_02",
    "prompt": 「メールを書いてください」,
    "expected": false,
    "note": 「完全に無関係なタスク」
  }
]

ステップ2:最適化ループを実行する

例

# description の自動最適化を実行
# スクリプトが自動的に:評価 → 修正 → 再評価 を5回ループ
python -m scripts.run_loop \
  --eval-set evals/trigger-eval.json \
  --skill-path data-analyzer/ \
  --model claude-sonnet-4-20250514 \
  --max-iterations 5 \
  --verbose
迭代 1:训练集得分 0.62,测试集得分 0.60
迭代 2:训练集得分 0.75,测试集得分 0.72
迭代 3:训练集得分 0.87,测试集得分 0.85
迭代 4:训练集得分 0.90,测试集得分 0.88
迭代 5:训练集得分 0.91,测试集得分 0.89

最优 description(测试集得分 0.89)已保存。

ステップ3:最適な結果を適用する

例

# スクリプトが best_description フィールドを出力し、SKILL.md の description に置き換える
# 最適化前
grep "description:" data-analyzer/SKILL.md

# 手動またはスクリプトで best_description の内容に置き換える
# 置き換え後に Skill を再パッケージ
python -m scripts.package_skill data-analyzer/

A/B 比較テスト

どちらの書き方が良いか不明な場合、2つのバージョンの description をブラインドテストで比較できます。

例

# バージョン A:現在の description
# バージョン B:候補の新しい description

# それぞれで評価を実行
python -m scripts.run_eval \
  --eval-set evals/trigger-eval.json \
  --skill-path data-analyzer-v1/ \
  --output evals/results_v1.json

python -m scripts.run_eval \
  --eval-set evals/trigger-eval.json \
  --skill-path data-analyzer-v2/ \
  --output evals/results_v2.json

# 比較レポートを生成
python eval-viewer/generate_review.py \
  --results evals/results_v1.json evals/results_v2.json \
  --compare \
  --output evals/comparison.html

評価はトレーニングセットのスコアではなく、テストセットのスコアを基準にすべきです。トレーニングセットのスコアが高くテストセットが低い場合、description がテストケースに過度に適合していることを意味し、実際のシナリオでは効果が低下する可能性があります。

その他の拡張