Agent Skillsは狙いどおり呼ばれるか｜59本の説明文を検証した結果

Agent Skillsは、説明文（description）を読んだAIが「使うかどうか」を判断する仕組みです。「59本そろえたのに、狙った場面で呼ばれているか分からない」という声が社内で出ました。本記事は、公式仕様に基づいてWEBMARKSの59本を監査した結果と、そこから設計する検証手順を共有します。実行済みの正答率がある体裁では書いていません。

01結論（3行）｜Agent Skillsの発火精度を検証する前に分かること

1. Agent Skillsの発火精度は、説明文がAIに読まれて初めて成立します。読まれなければ、条件が一致していても発火しません。
2. WEBMARKSの59本のうち、一覧に説明文が表示されていたのは35本でした。残り24本は名前だけで、判断材料がありませんでした（2026-07-28時点）。
3. 「59本×885問」という設計自体は成立します。ただし実行はまだ済んでおらず、正答率は走らせてから初めて言える数字です。

02Agent Skillsの発火精度はdescriptionだけで決まる｜公式ドキュメントの仕組み

Claude Codeは起動時に、インストール済みスキルの名前とdescriptionだけを先読みします。SKILL.md本体は、そのスキルが必要になった瞬間に初めて読み込まれます（出典: Claude Code公式ドキュメント）。つまり発火の判定材料は、本文ではなくdescriptionの一文に絞られます。

Agent SkillsはClaude Codeの拡張機能の1つです。業務でどこまで任せられるかは『業務で使うClaude Code｜コード以外に任せる仕事の地図』で扱っています。

公式のベストプラクティスは、descriptionを「三人称で、何をするか・いつ使うかの両方を書く」ことと定めています（出典: Agent Skills公式）。一人称や二人称で書くと、判断がぶれる原因になるとも明記されています。descriptionは1スキルにつき1個で、100本を超える環境を想定してもこの一文だけでAIが選ぶ設計です（出典: 同上）。

descriptionには公式の上限があります。Claude Codeの一覧表示ではさらに別の予算が働き、超過すると呼び出し頻度の低いスキルから説明文が落とされます（出典: Claude Code公式ドキュメント）。

03WEBMARKS 59本の説明文を監査した結果｜衝突が発火精度を脅かす9本

監査の対象は、WEBMARKSがClaude Code環境で運用する自社スキルです。プラグイン同梱の汎用スキル（superpowersやanthropic-skills等）は対象から除き、業務用に作り込んだものだけを数えました。2026-07-28時点でこの条件に当てはまるスキルは59本でした。

59本のうち、一覧にdescriptionが表示されていたのは35本、名前だけだったのは24本でした。名前だけの24本が予算超過によるものかどうかは、この記事の時点では確認できていません。ただしClaude Code公式ドキュメントが説明する「呼び出し頻度が低いスキルから説明文を落とす」という挙動とは矛盾しません（出典: 同上）。

除外文を持つ9本のうち5本は、devils-advocate・vault-audit・seo-article・x-post・html-diagram-explainerです。残り4本は、data-chart-maker・editable-pptx-deck・funnel-diagnosis・harukaze-instagram-feed-postです。いずれも、似た業務ドメインに複数のスキルが並ぶ場所でした。

たとえばvault-auditは、safety-audit・hierarchy-audit・automation-health・devils-advocateとの違いを説明文自身に書いています。同じ「監査」でも見る対象が違うため、書かなければ4本のどれが発火してもおかしくありません。diagram-makerとhtml-diagram-explainerも似た関係ですが、除外文があるのはhtml-diagram-explainer側だけでした。

04発火精度を検証する設計｜「59本×885問」の内訳とskill-creatorの手法

Agent Skills公式は、スキルの効きめを測る評価（eval）の作り方を公開しています。手順は、実際の失敗を先に集める→評価シナリオを作る→スキル無しの基準値を測る→最小限の指示を書く→反復する、の5段です（出典: Agent Skills公式ベストプラクティス）。

この評価は本来、出力の質（できあがった成果物が良いか）を測る仕組みです。トリガー精度（狙った依頼で発火するか）を測る機能は、別に用意されています。skill-creatorプラグインの「description tuning」が、発火すべき文とすべきでない文を生成し、命中率を測って改善案を出します（出典: Claude Code公式ドキュメント）。

WEBMARKS自身、この59本の中にskill-creatorを含めています。ただし2026-07-28時点で、59本全部にこの機能を回した記録はありません。台帳の未実測欄に載っているのは、この作業がまだ実行されていないという意味です（出典: 自社実例の実測台帳、2026-07-28確認）。

（出典: Claude Code公式ドキュメント）

「59本×885問」は、1本あたり平均15問という設計から逆算した数です。内訳は、正確一致トリガー・言い換えトリガー・隣接スキル境界・無関係な非トリガーの4種類です。

59本×15問はおよそ885問になります。数として成立するのはここまでで、実行して初めて正答率が言えます。この記事は設計図であって、完了報告ではありません。

05テスト質問の作り方｜発火精度を落とす2組で試す4パターン

設計を具体化します。ペアは、監査で見つかった衝突候補からそのまま選びます。ここではvault-auditとsafety-auditの組で、4パターンの質問例を示します。

Cの「監査して」だけを渡す一言は、もっとも情報が薄い依頼です。ここでどちらが発火するかは、descriptionの除外文がどちらを優先させているかで決まります。フレッシュなセッションで実行し、前のやり取りを残さないことが公式手順の条件です（出典: Agent Skills公式）。

diagram-maker・html-diagram-explainer・seo-article・proposal-draftの組でも、同じ形で質問を作れます。59本を総当たりにはせず、業務ドメインが近い組から優先して埋めるのが現実的です。

06誤発火を防ぐ運用ルール｜トリガー精度を落とさない書き方

書き方の基本は3つです。三人称で書く、何をするか・いつ使うかの両方を先に書く、曖昧な言い回しを避けることです（出典: Agent Skills公式ベストプラクティス）。「資料を処理します」のような一般的すぎる説明は、公式が避けるべき例として挙げています。

似た業務のスキルが並ぶ場所では、除外文が効きます。「◯◯がしたいときは代わりに××を使う」と書くだけで、判断の分かれ目がAI側にも見えるようになります。WEBMARKSの59本では、この書き方をしているのがまだ9本にとどまっています。

名前だけで説明文が消えている24本は、書き方の問題ではありません。呼び出し頻度が上がって一覧に残るか、予算の設定自体を見直すかのどちらかです。原因が違えば、直す場所も違います。

07つまずきやすい点｜発火精度の数字だけを見て安心しない

• 高い命中率が出ても、フレッシュなセッションで測っていなければ参考になりません。開発中の文脈が残ったままだと、本番では再現しない数字になります（出典: Agent Skills公式）。
• 発火しないスキルが全部「description不足」とは限りません。disable-model-invocation: true を設定した手動専用スキルも、同じように見えます（出典: Claude Code公式ドキュメント）。
• 質問を作った人が採点も兼ねると、期待値に寄った判定になりがちです。命中の判定は、質問を作った人と別の目で見るほうが安全です。
• 名前だけで説明文が消えている24本は、質問を作る前に原因の切り分けが要ります。「壊れていない」と決めつける前に実物を確かめる姿勢は、『AI運用の障害切り分け｜更新時刻を犯人にしない4段の手順』で扱った教訓と同じです。

08同じ勘違いをしないためのチェックリスト

• descriptionを三人称・具体語で書き、何をするか・いつ使うかの両方を入れたか
• 似た業務のスキルには「代わりに◯◯を使う」の除外文を入れたか
• 一覧で名前だけになっているスキルがないか確認したか
• テスト質問は正確一致・言い換え・隣接境界・非トリガーの4種類で作ったか
• 採点は質問を作った人と別の目で行っているか
• フレッシュなセッションで実行し、前のやり取りの文脈を残していないか
• 数字を報告する前に、実行ログ（evals.json・grading.jsonなど）を残したか

09FAQ