「スキルは59本そろえました。ただ、狙った場面でちゃんと呼ばれているのかは、正直わかっていません」。社内でこういう声が出ました。
Agent Skillsは、説明文（description＝そのスキルが何者かを一行で名乗る文）を読んだAIが、使うかどうかを判断する仕組みです。書いた側からは、その判断の瞬間が見えません。呼ばれなかったのか、呼ばれたけれど隣のスキルに負けたのか、そもそも候補に入っていなかったのか。画面に出てくる結果は、どれも同じ「何も起きなかった」です。
この記事は、公式仕様に沿ってWEBMARKSの59本を監査した結果と、そこから組み立てた検証手順をまとめたものです。実行済みの正答率がある体裁では書いていません。測った話と、これから測る話は分けて置きます。
こんなふうに調べていませんか
- スキルを増やしたのに、狙った場面で呼ばれているのかが分からない
- 似た役割のスキルが並んでいて、どちらが動くのか読めない
- 発火の精度を測れと言われたが、何をいくつ作ればいいのか決まらない
この記事を読み終えたときに手に入るもの
- 呼ばれない原因を、説明文の中と外に切り分けられるようになります
- 隣り合うスキルの境目を、4種類の質問で試せるようになります
- 数字を報告する前に、何を残しておくべきかが分かります
結論30秒でわかる、この記事の結論
- 発火精度は、説明文がAIに読まれて初めて成立します。読まれていなければ、条件が合っていても呼ばれません。
- 59本を数えたところ、一覧に説明文が残っていたのは35本、名前だけになっていたのは24本でした（2026-07-28時点）。
- 「59本×885問」という設計は成立します。ただし実行はまだで、正答率は走らせてから言える数字です。
案内役は3人です。若葉さんが用語の側から、高梨課長が自分の手で動かす側から聞き、鈴木さん（本誌監修）が答えます。
01Agent Skillsの発火精度は、AIエージェントの何で決まるんですか？
若葉さんスキルって、AIが中身まで見て選んでくれるものだと思っていました。違うんですか。
鈴木さん名刺入れに近いと思っています。資料の束は開かずに、名刺の一行だけを見て「この人に頼もう」と決めている感じです。
Claude Codeは起動時に、インストール済みスキルの名前とdescriptionだけを先読みします。SKILL.md本体は、そのスキルが必要になった瞬間に初めて読み込まれます（出典: Claude Code公式ドキュメント）。判定の材料は、本文ではなく説明文の一行に絞られるということです。
公式のベストプラクティスは、descriptionを「三人称で、何をするか・いつ使うかの両方を書く」ことと定めています（出典: Agent Skills公式）。一人称や二人称で書くと判断がぶれる原因になるとも明記されています。descriptionは1スキルにつき1個で、100本を超える環境を想定しても、この一行だけでAIが選ぶ設計です（出典: 同上）。
積み上げてみると、直す順番が見えてきます。土台は「一覧に残っていること」です。その上に「読者の言葉と説明文が触れ合うこと」が乗り、いちばん上に「隣に並ぶスキルと見分けがつくこと」が乗ります。上の層だけを磨いても、下が抜けていれば呼ばれません。
Agent SkillsはClaude Codeの拡張機能の1つです。業務でどこまで任せられるかはClaude Codeの業務活用｜任せる仕事の地図と判断軸4つで扱っています。
02一覧から説明文が落ちたAgent Skillsは、AI社員の候補に残るんですか？
descriptionには公式の上限があります。さらにClaude Codeの一覧表示では別の予算が働き、超過すると呼び出し頻度の低いスキルから説明文が落とされます（出典: Claude Code公式ドキュメント）。名前だけが残り、判断材料は消えます。
| 項目 | 内容 | 出典 |
|---|---|---|
| descriptionの文字数上限 | 1,024字 | Agent Skills公式ベストプラクティス |
| Claude Code一覧でのdescription＋when_to_use上限 | 1,536字 | Claude Code公式ドキュメント |
| 一覧の文字数予算 | モデルのcontext windowの1% | 同上 |
| 予算超過時の挙動 | 呼び出し頻度が低いスキルから説明文を落とす | 同上 |
| 推奨する人称 | 三人称固定 | Agent Skills公式ベストプラクティス |
区画に落としてみると、同じ「呼ばれなかった」でも中身が違うことが分かります。説明文が残っていて隣に相手がいなければ、狙いどおりに呼ばれます。隣がいれば、どちらが出るかは書き方しだいで割れます。説明文が落ちていれば、そもそも比べられる土俵に上がりません。
だから発火しなかった事実だけを見て、文面を書き直しにいくのは早すぎます。まず、その文が一覧に載っていたのかを見ます。
この章のまとめ
呼ばれなかった理由は一種類ではありません。負けたのか、土俵に上がっていなかったのか。この2つは直す場所が違います。
0359本のAgent Skillsを数えたら、AI導入の現場では何が見えたんですか？
高梨課長数えたというのは、どこまでを数えたんでしょうか。
鈴木さん業務用に作り込んだ自社スキルだけです。プラグインに同梱されてくる汎用のものは外しました。外さないと、自分たちが手を入れられない分まで母数に入ってしまうので。
監査の対象は、WEBMARKSがClaude Code環境で運用する自社スキルです。プラグイン同梱の汎用スキルは対象から除きました。2026-07-28時点でこの条件に当てはまるものは59本でした。
| 分類 | 該当数 | 割合 |
|---|---|---|
| 一覧にdescriptionが表示されている | 35本 | 59本中59% |
| 一覧が名前のみ（description非表示） | 24本 | 59本中41% |
| 表示されている35本のうち、明示的な除外文を持つ | 9本 | 35本中26% |
| 除外文を持たず、自分の条件だけを書いている | 26本 | 35本中74% |
左右に置くと、打ち手が入れ替わることが見えます。名前だけの24本は、文面をどれだけ磨いても比較の土俵に戻りません。
04除外文のある9本のAgent Skillsは、エージェントの迷いをどこで断つんですか？
除外文を持つ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側だけでした。片側だけが境目を書いている状態です。この非対称は、どちらが正しいかではなく、どちらの言い分だけがAIに届いているかの差になります。
この章のまとめ
除外文は自分の説明ではなく、隣との線引きです。書いた側だけが、割れる場面で名指ししてもらえます。
05Agent Skillsの発火精度の検証は、AIエージェントにどう測らせるんですか？
Agent Skills公式は、スキルの効きめを測る評価（eval）の作り方を公開しています。手順は5段です。実際の失敗を先に集め、評価シナリオを作り、スキル無しの基準値を測り、最小限の指示を書き、反復する（出典: Agent Skills公式ベストプラクティス）。
この評価は本来、出力の質を測る仕組みです。トリガー精度（狙った依頼で発火するか）を測る機能は別に用意されています。skill-creatorプラグインの「description tuning」が、発火すべき文とすべきでない文を生成し、命中率を測って改善案を出します（出典: Claude Code公式ドキュメント）。
| 段階 | やること |
|---|---|
| Test cases | プロンプトと期待する挙動をevals.jsonに書く |
| Isolated runs | 1問ごとに独立したサブエージェントで実行し、文脈を残さない |
| Grading | 各問をPASS・FAILと根拠つきで判定する |
| Benchmark | スキル有無での正答率・時間・トークンを集計する |
| Version comparison | 2つのdescriptionを見比べるブラインドA/Bを行う |
| Description tuning | 発火すべき文・すべきでない文を生成し命中率を測る |
（出典: Claude Code公式ドキュメント）
WEBMARKS自身、この59本の中にskill-creatorを含めています。ただし2026-07-28時点で、59本すべてにこの機能を回した記録はありません。台帳の未実測欄に載っているのは、この作業がまだ実行されていないという意味です（出典: 自社実例の実測台帳、2026-07-28確認）。
06隣り合うAgent Skillsの境目は、生成AIにどんな一言で試すんですか？
高梨課長質問はどう作ればいいんでしょう。数だけ増やしても意味が無い気がします。
鈴木さん効くのは、わざと紛らわしくした一言のほうです。きれいな依頼文はだいたい通るので、そこを何十問積んでも景色が変わりません。
「59本×885問」は、1本あたり平均15問という設計から逆算した数です。内訳は、正確一致トリガー・言い換えトリガー・隣接スキル境界・無関係な非トリガーの4種類になります。
| カテゴリ | 目的 | 1スキルあたりの目安 |
|---|---|---|
| A: 正確一致トリガー | descriptionが想定する言葉をそのまま使う | 3〜4問 |
| B: 言い換えトリガー | 同じ依頼を別の言葉で書く | 3〜4問 |
| C: 隣接スキル境界 | 似た業務ドメインの別スキルと紛れる言い方 | 4〜5問 |
| D: 非トリガー | 全く関係ない依頼で誤発火しないか確かめる | 2〜3問 |
ペアは、監査で見つかった衝突候補からそのまま選びます。vault-auditとsafety-auditの組で作ると、こうなります。
| カテゴリ | 質問例 | 想定される発火先 |
|---|---|---|
| A: 正確一致 | 「Vault監査して」 | vault-audit |
| A: 正確一致 | 「セキュリティ監査して」 | safety-audit |
| B: 言い換え | 「フォルダ構造おかしくなってないか見て」 | vault-audit |
| B: 言い換え | 「ガードレール整備して」 | safety-audit |
| C: 隣接境界 | 「監査して」（対象を言わない一言） | 除外文の書き方しだい |
| D: 非トリガー | 「今日のランチどこがいい？」 | どちらも発火しない |
Cの「監査して」だけを渡す一言が、いちばん情報の薄い依頼です。ここでどちらが発火するかは、除外文がどちらを優先させているかで決まります。フレッシュなセッションで実行し、前のやり取りを残さないことが公式手順の条件です（出典: Agent Skills公式）。
diagram-maker・html-diagram-explainer・seo-article・proposal-draftの組でも、同じ形で質問を作れます。59本を総当たりにはせず、業務ドメインが近い組から優先して埋めるのが現実的です。
07誤発火で発火精度が落ちないよう、AI活用の現場では何を書き足すんですか？
書き方の基本は3つです。三人称で書くこと、何をするか・いつ使うかの両方を先に書くこと、曖昧な言い回しを避けることです（出典: Agent Skills公式ベストプラクティス）。「資料を処理します」のような一般的すぎる説明は、公式が避けるべき例として挙げています。
入れ替わっているのは表現の丁寧さではありません。隣に誰が並ぶかを書いたかどうかです。「◯◯がしたいときは代わりに××を使う」と書くだけで、判断の分かれ目がAI側にも見えるようになります。
WEBMARKSの59本では、この書き方をしているのがまだ9本にとどまっています。除外文の具体的な書き方はClaude Codeのスキルが発火しない｜descriptionを直す4層にまとめています。
この章のまとめ
自分の条件を丁寧に書くほど呼ばれる、とは限りません。似た相手が並ぶ場所では、境目を書いた側が選ばれます。
08名前だけの24本のAgent Skillsは、AI社員のスキル一覧から何が消えているんですか？
若葉さん名前だけになっている24本は、説明文を書き直せば戻るんでしょうか。
鈴木さんそこはまだ切り分けられていません。予算で落ちているのか、別の理由なのか。分からないまま書き直すと、直った気にだけなってしまいます。
名前だけの24本が予算超過によるものかどうかは、この記事の時点では確認できていません。ただしClaude Code公式ドキュメントが説明する「呼び出し頻度が低いスキルから説明文を落とす」という挙動とは矛盾しません（出典: 同上）。
発火しないスキルが全部「説明文の不足」とも限りません。disable-model-invocation: true を設定した手動専用スキルも、外からは同じように見えます（出典: Claude Code公式ドキュメント）。原因が違えば、直す場所も違います。
「壊れていない」と決めつける前に実物を確かめる姿勢は、AI運用の障害の原因切り分け｜証跡で追う4段の順序で扱った教訓と同じです。質問を作る前に、この24本の原因の切り分けを済ませます。
09Agent Skillsの発火精度を検証した数字は、AI導入の判断にどう効くんですか？
高い命中率が出ても、フレッシュなセッションで測っていなければ判断材料になりません。開発中の文脈が残ったままだと、本番では再現しない数字が出ます（出典: Agent Skills公式）。
質問を作った人が採点も兼ねると、期待値に寄った判定になりがちです。命中の判定は、質問を作った人とは別の目で見るほうが安全です。
数字そのものより先に、その数字が何を測ったものかを言えるようにします。母数が59本なのか、衝突候補の組だけなのか。まっさらな状態で測ったのか、続きの会話で測ったのか。ここが書かれていない正答率は、次の担当者が読み直せません。
「59本×885問」は数として成立します。ただし、成立するのはそこまでです。この章までが設計図であって、完了報告ではありません。
10同じ勘違いをくり返さないために、AIエージェントの運用では検証の記録として何を残すんですか？
- descriptionを三人称・具体語で書き、何をするか・いつ使うかの両方を入れたか
- 似た業務のスキルには「代わりに◯◯を使う」の除外文を入れたか
- 一覧で名前だけになっているスキルがないか確認したか
- テスト質問は正確一致・言い換え・隣接境界・非トリガーの4種類で作ったか
- 採点は質問を作った人とは別の目で行っているか
- フレッシュなセッションで実行し、前のやり取りの文脈を残していないか
- 数字を報告する前に、実行ログ（evals.jsonやgrading.jsonなど）を残したか
このリストは、監査で見つかった穴をそのまま裏返したものです。前半は説明文を書くときに、後半は数字を測るときに、それぞれ戻ってきて使います。
11よくある質問
885問はいつ実行されるんですか
現時点では未実行です。実行し次第この記事を更新し、正答率と実行日を追記します。数字を先に出して、あとから根拠を揃える順番にはしません。
スキルが多いほど誤発火は増えるんですか
一概には言えません。似た業務ドメインに複数並ぶ場所でだけ起きやすい問題です。今回の監査でも、除外文が要るのは近接ドメインの9本に集中していました。本数そのものより、どこに固まっているかを見ます。
テスト質問は人が作るしかないんですか
skill-creatorプラグインのdescription tuningが、発火すべき文とすべきでない文を自動生成する機能を持っています（出典: Claude Code公式ドキュメント）。ゼロから人力で885問を書く必要はありません。生成された文をそのまま使うのではなく、自分の業務語彙に寄せて直す工程は残ります。
59本という数はどこまで正確なんですか
WEBMARKSがClaude Code環境で運用する業務スキルを2026-07-28時点で数えた値です。プラグイン同梱の汎用スキルは含みません。新しいスキルが増減すれば、この数字も変わります。
スキルと、AIエージェントそのものはどう違うんですか
スキルは、依頼に応じて呼び出される部品です。呼ばれて働き、終われば戻ります。この位置づけはAIエージェントとは｜3条件で見分け、任せる前に決める3つで扱った3層構造の「単発実行」に近いものです。エージェントと呼べるかどうかは、また別の条件で決まります。
12まとめ｜今日やる3つのこと
発火精度は、説明文の出来だけでは決まりませんでした。まず一覧に残っているか、次に言葉が触れ合うか、最後に隣と見分けがつくか。この順番で見ると、直す場所を取り違えずに済みます。
今日この順で手をつけます
自分の環境のスキル一覧を開き、名前だけになっているものを書き出す
文面を直す前に、土俵に乗っているかを先に見ます
業務ドメインが近い組を1つ選び、A〜Dの4種類で質問を作る
総当たりにすると、いつまでも1問目に着手できません
まっさらな状態で流し、判定を別の人に渡す
作った本人が採点すると、期待値のほうへ寄ります
AI検索では、こう聞かれています
Agent Skillsが狙った場面で呼ばれているか、どう確かめるんですか？
「Agent Skillsの発火精度の検証は、AIエージェントにどう測らせるんですか？」の章で説明しています
似た名前のスキルが並ぶと、どちらが発火するんですか？
「隣り合うAgent Skillsの境目は、生成AIにどんな一言で試すんですか？」の章で質問例を出しています
スキルの説明文が一覧に出てこないのは何が原因ですか？
「名前だけの24本のAgent Skillsは、AI社員のスキル一覧から何が消えているんですか？」の章で切り分けを扱っています
次に読むなら、この記事です
