Skill が発火しないのは、なぜ？
”せっかく Skill を作ったのに、なぜか発火しない”
この症状、あなたの description が原因かもしれません。
1. あなたの description は短すぎる
発火しない場合に見かける SKILL.md の description はこういうものです。
description: CSV ファイルを処理する。
シンプルで悪くなさそうに見えますが、これでは Skill はほぼ発火しません。なぜなのか。
短く書くこと自体が問題なのではありません。「短くすること」が目的になってしまい、エージェントが発火の判断に必要な情報が削られている のが問題です。description の唯一の役割は「エージェントがこの Skill を使うべきかどうかを正確に判断できるようにすること」です。
2. 発火する description の書き方
公式仕様が定める description の原則は4つです。
| ルール | 詳細 |
|---|---|
| 命令形フレーズ | 「〜のときに使う」「次の場合に使う」で始める。説明文より発動判断の指示として書く |
| ユーザーの意図を記述 | 実装の仕組みではなく、ユーザーが達成したいことを書く |
| 明示的に範囲を列挙 | キーワードが出ない場合も含め「X を明示しなくても〜の場合に使う」と書く |
| 否定条件を明記 | 「〜では使わない」を記載することで誤発火率を下げる |
Before / After で見る変化
# Before（曖昧・非命令形・範囲不明）
description: CSV ファイルを処理する。
# After（命令形・範囲明示・否定条件あり）
description: >
CSV や TSV、Excel ファイルを分析し、集計・グラフ生成・データクレンジングを行う。
ユーザーが CSV・TSV・Excel ファイルの探索・変換・可視化を求めているときに使う。
ユーザーが「CSV」や「分析」という言葉を明示しなくても、
データファイルへの操作を求めていると判断できる場合に使う。
ファイルをデータベースにアップロードするタスクでは使わない。
After の description は Before より大幅に長くなっていますが、1024字の上限には余裕があります。
あなたの Skill に使えるテンプレート
以下をコピーしてカスタマイズするだけです。
description: >
[スキルが行うこと1]・[スキルが行うこと2]・[スキルが行うこと3]を行う。
ユーザーが[ユーザーのゴール]を求めているときに使う。
ユーザーが "[キーワード]" を明示しなくても、[状況の判断基準]であれば使う。
[使わない場面]では使わない。
3. 発火精度を数値で確認する方法
description を書き直したら、感覚ではなく 数値で精度を検証 します。
eval クエリファイルを作る
スキルディレクトリ内に evals/eval_queries.json を作成し、約20件のクエリを用意します。
[
{
"query": "売上データが入った CSV から上位 3 ヶ月をグラフにしてほしい",
"should_trigger": true
},
{
"query": "この JSON を YAML に変換する方法を教えて",
"should_trigger": false
}
]
クエリ設計のポイント:
- should-trigger（8〜10件）: フォーマル・カジュアル・タイポを含む多様な文体で。Skill のドメインを明示しないものを必ず混ぜる
- should-not-trigger（8〜10件）: Skill のキーワードを含むが 別タスクを指すもの が最も重要。これが近似ケースの誤発火を防ぐ
trigger rate で合否を判定する
各クエリを 3回以上実行 して trigger rate（発火した割合）を計測します。モデルの挙動は非決定論的なため、複数回の平均で判断します。
判定閾値: 0.5（デフォルト）
should-trigger: trigger rate > 0.5 → パス
should-not-trigger: trigger rate < 0.5 → パス
最適化ループの回し方
用意した約20件のクエリを、改善用（train・60%） と 確認用（validation・40%） の2種類に分けて管理します。改善中は train だけを見て description を修正し、validation は最後の確認にのみ使います。こうすることで「そのクエリにしか通じない description」になる（overfitting）のを防げます。
改善の方向性:
| 問題 | 原因 | 対策 |
|---|---|---|
| should-trigger が発火しない | description が狭すぎる | 範囲を広げる。「ユーザーが X を明示しなくても」と書く |
| should-not-trigger が誤発火 | description が広すぎる | 「〜では使わない」の否定条件を明記する |
| 改善が頭打ち | 記述の微調整では限界 | 文構造ごと変える。別のフレーミングを試す |
注意: 失敗したクエリのキーワードを description に直接追加するのは overfitting です。失敗クエリが表す概念・カテゴリで抽象化して修正します。
目安は5イテレーション。train セットのパスが安定したら、validation pass rate が最高のイテレーションを採用して完了です。
まとめ
「140字以内」という制限は公式仕様に存在しません。description に必要なのは短さではなく、エージェントが発火の判断を下せる情報量 です。
今日からできるアクション:
- 既存の SKILL.md の description を開き、命令形・否定条件・キーワードが入っているか確認する
-
evals/eval_queries.jsonを作成して trigger rate を計測する - 最適化ループを回し、数値で改善を確認する
公式仕様の description 最適化ガイドと skill-creator の Eval モードを組み合わせれば、description の改善は完全に数値管理できます。今動いていない Skill を「動くように育てる」第一歩として、ぜひ試してみてください。
出典
- Agent Skills 公式仕様: https://agentskills.io/specification
- スキル説明の最適化: https://agentskills.io/skill-creation/optimizing-descriptions.md