原則1．「Description」をスキル起動のトリガーとして設計する

　最初のポイントは、skill.mdに記述する「Description」（説明文）だ。

　大量のSkillsをインストールしたAIエージェントが、起動時に全てのskill.mdを読み込めば、コンテキストウィンドウを大量に消費してしまう。そのため、起動時には基本的に各スキルの「Name」（名前）とDescriptionだけを読み込み、ユーザーの指示に応じて利用するスキルを選択する。Descriptionが、「このスキルを使うかどうか」をAIエージェントに判断させるトリガーとして機能する。

　Descriptionには、例えば「コンプライアンスレポートを作成する」といったように、そのSkillsが何をするのかだけを書くのでは不十分だ。「社内データから月次コンプライアンスレポートを作成する。ユーザーからコンプライアンスレポートや月次提出資料の作成を依頼された場合に使用する」といった具合に、「何をするスキルなのか」に加えて「どのような依頼や状況で使うのか」まで記載する。

　キーン氏によると、AIモデルは、本来使うべきスキルを選ばない「under-trigger」という現象を起こすことがある。そのためDescriptionは、控えめに書くよりも、Skillsを使う条件をやや強めに明示する方がよいという。

原則2．LLMに丸投げせず「現場のノウハウ」を入れる

　次に重要なのが、skill.mdの中身だという。

　キーン氏は、「○○業務を実施するスキルを書いて」と大規模言語モデル（LLM）に依頼すれば、それらしいskill.mdは簡単に生成できると説明する。しかし、その結果は「入力値を検証する」「適切にエラー処理する」といった一般論に偏りやすい。こうした知識は、そもそもAIモデルが既に知っている可能性が高い。

　エージェントスキルに入れる価値があるのは、「自社ではこの業務をこう進める」といったAIモデルが自力では知り得ない情報だとキーン氏は強調する。

　その材料として使えるのが、実際に人間が業務を進める際の手順だ。担当者が業務を手作業で実行し、その途中で実施した修正や判断を記録する。既に社内に存在する過去のレポート、ランブック、レビューコメント、コードレビューのフィードバックなどからノウハウを抽出する方法もある。

　中でも重要なのが「Gotchas」、つまり現場特有の注意点や落とし穴だ。

　例えばAIエージェントを運用する中で、人間が「この場合だけは別の処理が必要」「この項目はこのシステムの値を使ってはいけない」と修正したとする。その修正内容をskill.mdに残さなければ、AIエージェントは次回も同じ間違いをする可能性がある。

　しかし、AIエージェントの処理を人間が手作業で修正した内容をGotchasとして蓄積すれば、運用を続けながら業務スキルそのものを改善できる。

原則3．skill.mdを肥大化させず「段階的に情報を渡す」

　現場固有の情報を詳細に書けば書くほど、skill.mdは長くなる。しかし、情報を詰め込み過ぎると別の問題が起きるとキーン氏は指摘する。

　AIエージェントがSkillsを選択すると、skill.md本文がコンテキストに読み込まれる。そこに大量の説明を書けば、ユーザーとの会話や他の情報とコンテキストウィンドウを奪い合うことになる。

　そこで重要なのが、「AIモデルが既に知っている内容は書かない」という考え方だ。

　例えばPDFとは何か、データベース移行とは何かといった一般知識までskill.mdで説明する必要はない。書くべきなのは、自社固有の業務ルールや手順など、AIモデルがあらかじめ知っているとは考えにくい情報だという。

　キーン氏は、skill.md本文を目安として500行未満、約5000トークンを目安に抑えることを推奨している。

　それでも詳細な情報が必要になる場合は、「references」サブフォルダを利用するのが有用だ。

　例えば詳細な仕様書や過去のレポート、業務ルール集などをreferences配下に置き、skill.mdには「必要になった場合にこの資料を参照する」と記述する。AIエージェントは必要になった時だけ資料を読み込める。

　こうした考え方を「Progressive Disclosure」（段階的開示）と呼ぶ。最初から全情報をコンテキストに投入するのではなく、必要な情報だけを必要な時に渡すことで、トークン消費を抑えながら詳細な業務知識を利用できる。

原則4．「絶対に間違えてはいけない処理」はAIエージェントに考えさせない

　AIエージェントに業務手順を詳細に教えても、実行結果が毎回完全に同じになるとは限らない。基盤となるAIモデルは指示を読み、その都度推論しながら処理するからだ。

　多少やり方が違っても問題ない作業であれば、それでも問題はないかもしれない。しかし、計算やデータの変換、決められた形式への整形など、「毎回必ず同じロジックで正確に処理しなければならない作業」では問題になる。

　そこでキーン氏が紹介するのが「決定論的スクリプト」だ。具体的には、Skills用のフォルダに「scripts」ディレクトリを作成し、確実に実行したい処理をコードとしてあらかじめ配置する。skill.mdには、その処理が必要になった場合に該当するスクリプトを実行するよう記載する。

　キーン氏は例として、コンプライアンスレポートの集計を挙げる。同氏がAIエージェントに計算を実行させたところ、合計値は一致しなかった。そこで、AIエージェントに計算させず、計算処理を決定論的なスクリプトに置き換え、そのコードを実行させる構成に変更した。これによって、AIモデルによる確率的な判断を計算処理から排除できる。

　この例のポイントは「壊れやすい処理ほどAIに自由に判断させない」ことだ。

　文章の作成や情報の整理など複数の正解が考えられるタスクは、自然言語による手順で指示する。一方、計算や厳密なフォーマット変換など答えが一意に決まる処理はコードにする。「AIエージェントに詳しく指示する」のではなく、「AIエージェントが推論する必要そのものをなくす」という設計が重要になる。

原則5．外部のスキルは「プログラム」として監査する

　Skillsを運用する上で、情報システム部門やセキュリティ担当者が特に注意したいのが、外部から入手したSkillsだ。

　Skillsは単なるテキストファイルではない。scriptsフォルダなどに実行可能なコードを含めることができる。そのコードから端末のローカルファイルシステムにアクセスしたり、環境に保存されているAPIキーなどを参照したりすることも可能だ。

　キーン氏によると、公開されているSkills約4000件を調査した結果、そのうち約35％に何らかのセキュリティ上の問題があったという。さらに、13％のSkillsにはプロンプトインジェクションやマルウェアなど重大な問題の存在が確認されたという。

　このため、インターネット上で公開されているスキルをそのまま社内環境で実行するのは避けるべきだとキーン氏は強調する。

　外部に公開されているSkillsを利用する際は、一般的なソフトウェアライブラリや外部パッケージと同じように扱うこと。実行前にskill.mdやスクリプトの内容を確認する必要がある。どのファイルにアクセスするのか、外部のどのサービスと通信するのか、認証情報を読み取る処理がないかといった点を確認することが重要だ。

「プロンプトを書く」から「業務の実行環境を設計する」へ

　Skillsという名称からは、AIエージェントに長い指示文を与える仕組みを想像しがちだ。しかし実際には、単なるプロンプトとは性格が異なる。

　Descriptionによって「いつ使うか」を判断させ、skill.mdで自社固有の手順やGotchasを伝える。大量の資料はreferencesに分離し、正確性が必要な処理はscriptsに任せる。こうして見ると、SkillsはAIエージェントに知識を与えるだけではなく、「どこまで判断させ、どこから既存の仕組みに任せるのか」を設計する仕組みだと言える。

　AIエージェントに業務を任せる際、全てをLLMの推論能力に委ねる必要はない。むしろ、AIモデルに任せる柔軟な判断と、コードに任せる決定論的な処理を切り分け、自社の業務ノウハウをその間に組み込むことが、安定したAIエージェント運用につながる。

本稿は、IBM Technologyが2026年8月10日に公開した5 Best Practices for Building AI Agent Skillsを基に作成しました。