エージェントが手順を飛ばす原因はスキルファイルの書き方にある（スキルあり）

エージェントに作業を任せるためのスキルファイル。丁寧に書いたはずなのに、いざ動かすと指定した手順が飛ばされている。「テストを必ず実行してから完了報告をする」と明記したのに、テストを走らせないまま「完了しました」と返ってくる。心当たりのある人は少なくないはずです。スキルをそもそもあまり使わない、という方は「そうなのかな」と思いながら聴いてください。

モデルの性能を疑いたくなる場面ですが、原因はスキルファイルの書き方そのものに潜んでいるかもしれません。世の中で実際に使われているスキルファイルを大量に集め、中身を1件ずつ読み解いた調査があります。浮かび上がってきたのは、多くの書き手が同じ場所でつまずいている実態と、そのつまずきに共通するパターンの存在でした。書き方に問題があるということですね。

本記事では、この調査をもとに、実在するスキルファイルの定番の型、性能を損ないかねない書き方のパターン、そして自作スキルを点検するときの観点を紹介します。また、これを活かしたスキルファイルを作成しました。ぜひお役立てください。

スキルファイルはドキュメントではなく実行部品

エージェントに知識を渡す標準の仕組みになりつつある

Claude CodeやGitHub Copilotに代表されるコーディングエージェントには、組織やプロジェクト固有の知識を渡す仕組みとして「Agent Skills」が広がっています。仕組みはシンプルで、フォルダの中にSKILL.mdという1枚のMarkdownファイルを置き、必要に応じて補助スクリプトや参照ドキュメントを同梱します。SKILL.mdの冒頭には名前と説明文を書くメタデータ欄（フロントマター）があり、エージェントはここを手がかりに「今のタスクにこのスキルが必要か」を判断します。本文に何をどう書くかは、作者に完全に委ねられています。なお、このウェブサイトにもエージェントスキルライブラリがあるように、スキルはマーケットプレイスが幾つも存在します。

公開マーケットプレイスには13万件を超えるスキルが流通しており、モデルを再学習させずにエージェントの振る舞いを拡張できる手段として、採用が急速に進んでいます。すごい勢いで流行ってきました。

自由に書ける、だから品質が割れる

スキルファイルの中身は、読み込まれるとそのままエージェントのコンテキストウィンドウ（モデルが一度に参照できる作業記憶のような領域）に入ります。書き方の巧拙が、そのまま挙動の質と処理コストに跳ね返る構造です。実際、スキルの効果を測った別の調査では、性能を大きく引き上げる場合がある一方で、プロジェクト固有の文脈と衝突してかえって性能を下げる場合も報告されています。いつも必ずプラスに働くわけではないのがややこしいところです。

ソフトウェア開発の歴史を振り返ると、自由記述の成果物は放っておくと品質問題が積み上がっていく傾向があります。コミットメッセージ（コード変更に添える説明文）を対象にした過去の研究では、不完全なものや空のものが多数を占め、その質の低さが不具合の発生と関連していました。スキルファイルも同じ道をたどるのか。この問いに正面から向き合ったのが、今回紹介する調査です。過去を遡って教訓を得るのは大事ですね。

人気スキル238件を1件ずつ読み解いた

対象は「実際に使われている」スキルだけ

調査を手がけたのは、カリフォルニア大学アーバイン校の研究チームです。2026年7月に公開された分析では、公開マーケットプレイスに登録された13万件超のスキルから、対象が段階的に絞り込まれました。絞り込みの条件は次のとおりです。

• 英語で書かれていること
• 週10回以上ダウンロードされていて、実際の利用実績があること
• 掲載リポジトリの人気度（スター数）が全体の上位1割に入ること
• 同じリポジトリからは1件だけを選び、特定の作者に偏らないようにすること

最終的に残った238件が精読の対象になりました。件数としては一部ですが、「人気があり、現実に使われているスキル」の縮図と言えます。13万件から238件に絞り込んだのはすごいですね。

中身には定番の3点セットがあった

238件を見出し単位で分類していくと、13の大分類と44の小分類からなる構成要素の体系が見えてきました。自由記述のはずのSKILL.mdにも、書き手たちが自然に行き着いた共通の型が存在していました。頻出の上位3つを表にまとめます。

「何をするか」「いつ使うか」「困ったらどこを見るか」。この3点セットが、実在するスキルの背骨になっていました。一方で、生成結果を検証する手順を含むスキルは2割程度、不適切な動作を止めるガードレールを明記したものは1割未満にとどまります。作らせる指示は充実しているのに、確かめさせる指示は手薄。この偏りが、後述する結果の伏線になります。こうしてパターンを見出すことで次の一手が打てます。

書き方の指針は26個、ただしカバー範囲は半分

ベンダー文書からブログまで29の情報源を横断

良い書き方の基準はどこにあるか。プラットフォーム公式のドキュメント、開発者コミュニティの解説、実務者のブログ記事。スキルの書き方に触れた29の情報源を集めて照らし合わせ、重複を整理した結果、26個の推奨事項が抽出されました。情報源のあいだで推奨が食い違う場合は、多数決で採否を決めるという手堅い進め方です。そしてブログ記事まで参考にしているのは非常にイマドキな考え方。

半分の領域には指針がそもそもない

興味深いのはここからです。26個の推奨事項を先ほどの13の大分類に対応づけると、明確な指針が存在したのは7分類だけでした。導入部分の書き方、評価手順の設計、外部ツールとの連携方法。頻出する構成要素でありながら、参照できるガイドラインが見当たらない領域が残っています。言い換えれば、スキル作者の判断の半分近くは、手本のないまま勘で下されています。スキルの書き方には手本があるという考え方自体、スタンダードではないですからね。

推奨に反する書き方に名前をつける

コードスメルの発想をスキルに持ち込む

ソフトウェア工学には「コードスメル」という考え方があります。バグとまでは言えないものの、保守性を下げ、不具合の温床になりやすいコードの兆候を指す言葉です。今回の調査では同じ発想で、推奨事項に反するSKILL.mdの書き方が「スキルスメル」と定義され、26種類に整理されました。スキルファイルにスメルの概念を持ち込むなんて厳しすぎると思いますか？

26種類は10の系統に分かれる

たとえば「dig」という名前のスキルは何のスキルか

具体例を見るとイメージが湧きます。調査で見つかったスキルのひとつに「dig」という名前のものがありました。中身はライブラリのドキュメントやソースコードを調べるためのスキルですが、名前だけでは用途が想像できません。別の例では、説明文に「ベンチマークを実行してPDF解析の性能を分析する」とだけ書かれていました。何をするかは分かっても、いつ呼び出すべきか、どんな入力を想定しているかが読み取れません。わかりやすい例ですね。

エージェントは膨大な選択肢の中から、名前と説明文を手がかりにスキルを選びます。入口で選ばれなければ、本文をどれだけ作り込んでも出番は回ってきません。説明文には「何をするか」「いつ使うか」「どんな言葉で呼ばれるか」の3点を入れる。推奨事項のひとつとして挙げられているこの型は、自作スキルにもすぐ応用できます。少なくとも、具体的な名前をつけるのはすぐ実践できます。

無傷だったのは238件中たった1件

1件あたり平均10.5個のスメル

26種類のスメルを人手で全件チェックするのは現実的でないため、ルールベースの静的チェックとLLMによる意味判定を組み合わせた自動検出の仕組みが構築されました。人手で作った正解データと照合した検出精度は、F1スコアで0.78です。この検出器を238件に適用した結果は次のとおりでした。

• スメルがひとつもなかったスキルは238件中わずか1件
• 1件あたり平均10.5個のスメルを抱えている
• 26種類のうち11種類は、半数以上のスキルに存在する

推奨事項からの逸脱は例外ではなく、むしろ標準の状態だと言えます。いわば、初めから完璧なスキルなんてないのです。

最多は「言い訳の抜け道」の94%

個別に見て最も多かったのは、手順を飛ばす言い訳を防ぐ文言がない、という項目でした。検出率の上位を表にまとめます。

エージェントには、作業の途中で「このステップは今回のケースでは省略してよい」と自分を納得させてしまう性質があります。「すべてのステップを例外なく実行する」「省略する場合は必ず人間に確認する」といった歯止めがなければ、この理屈は素通りします。冒頭に挙げた「テストを飛ばして完了報告」も、モデルの気まぐれというより、スキル側に歯止めがなかった結果と捉えたほうが建設的です。逆に、スキルに書かれてある内容に全て従うとトークン消費量が膨大になってしまいます。

長さの問題はほぼゼロだった

意外な結果もあります。本文が長すぎる、名前が長すぎる、説明文が長すぎる。分量に関するスメルは、238件の中でほとんど検出されませんでした。書き手たちは量のコントロールには成功しています。問題は量ではなく、検証・歯止め・安全装置という中身の設計に集中していました。高度な要求ですが・・・

一度入ったスメルは8か月間ほぼ直らなかった

変更履歴1,199件を週ごとに追跡

スメルは時間とともに直されていくのか、それとも残り続けるのか。2回以上更新された142件のスキルについて、初回の登録から直近までの全変更履歴、あわせて1,199件が分析されました。期間は2025年10月から2026年6月までの35週間です。週ごとに、その時点で存在するスキルのうち何割がそれぞれのスメルを含むかが追跡されました。その結果は、想像の通り、というか見出しの通りです。

減る気配はなく、そのまま固定化していく

どのスメルについても、時間の経過とともに割合が下がる傾向は観測されませんでした。

すべてのスキルが出そろった終盤の期間では、各スメルの割合はほぼ横ばい。新たに直されることも大きく増えることもなく、そのまま固定化しています。個別のスキル単位で追跡しても、一度入ったスメルが後から取り除かれるケースはほとんど見られませんでした。指摘されなければ直す動機はかなり少ないということでしょうか。

言い換えれば、スキルファイルは「最初に書いたときの品質」がその後も続く成果物です。後から誰かが直してくれる期待は持てません。書き始めの段階で型を押さえることに、それだけの価値があります。おそらく書くモチベーションも最初が大きいです。

良いスキルは3つのバランスで決まる

指示の粒度は「目的を示して実行を委ねる」

指示不足と指示過剰は、同じ軸の両端にある失敗です。手順をまったく分解しなければ、エージェントは何から手を付けるべきか迷います。逆にコマンドの実行順を1行ずつ固定すると、状況が少し変わっただけで対応できなくなります。関連する先行研究でも、ワークフローの分解や判断基準の提示は性能を高める一方、過剰に細かい指定は指示への追従性をかえって下げると報告されています。ちょうどよい粒度は、達成したい状態と判断の基準を示し、具体的な実行方法の選択はエージェントに委ねる書き方です。人間には難しいかもしれませんので、この考え方ごとAIエージェントに渡すのはありです。

検証と歯止めは後付けの飾りではない

計画を立てさせる、生成結果を確かめさせる、チェックリストで進捗を追わせる、省略時には人間に確認させる。こうした仕組みの有無が信頼性を左右することは、複数の先行研究で繰り返し示されています。そして今回の調査で検出率が高かったスメル群は、まさにこの領域に集中していました。自作スキルを見直すなら、真っ先に確認したいのはここです。生成の手順だけでなく、確かめる手順と手を抜かせない文言をセットで書いておく。それだけで検出率上位のスメルの大半を回避できます。これは実践してみないと何とも言えなさそうですね。

情報は多くても少なくてもコストになる

細かい実装情報を本文に詰め込むと、コンテキストウィンドウを圧迫し、推論の負担を増やします。かといって情報が足りなければ、エージェントは推測で穴を埋めるしかありません。推奨されているのは、本文には判断に必要な高レベルの情報だけを置き、細部は参照ファイルや補助スクリプトに逃がす構成です。あわせて典型的な使用例をひとつ添えておくと、エージェントが文脈をつかむ助けになります。基本的には、階層的な作り方はよしとされています。

まとめ

SKILL.mdは説明書のような見た目をしていますが、実態はエージェントの挙動を直接左右する実行部品です。実在する人気スキルを対象にした今回の調査からは、ほぼすべてのスキルが推奨から外れた書き方を含み、その問題が更新を重ねても直らないまま残り続ける実態が見えてきました。こうした分析は地味ですが大事ですね。

なお、対象が英語圏の人気スキルに限られること、個々のスメルが性能をどの程度損なうかの因果関係はまだ検証されていないことは、割り引いて受け取る必要があります。とはいえ、コードスメルの研究が数十年かけて検出ツールやリファクタリング技術に結実してきた歴史を踏まえると、スキルの品質管理も同じ道をたどると見るのが自然です。リンターに相当する支援ツールが整うまでのあいだ、本記事で挙げたスメルの一覧は、そのまま自作スキルのセルフチェックリストとして役立ちます。書いた直後の品質がずっと続くと分かった以上、最初のひと手間をかける理由は十分にあります。

スキル

本記事の関連研究