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": 「完全に無関係なタスク」
}
]
{
"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
# スクリプトが自動的に:評価 → 修正 → 再評価 を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/
# 最適化前
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
# バージョン 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 がテストケースに過度に適合していることを意味し、実際のシナリオでは効果が低下する可能性があります。