AIエージェントのスキルとプラグインを、正しく読み込まれて発動するように作る

## 公式ドキュメントを読み、参考になるスキルを流用する 何かを書き始める前に、対象とするプラグインとスキルのシステムについて、最新の公式ドキュメントを読むこと。プラグインの形式、スキルの形式、そして公開されている作成ベストプラクティスの3つである。ベンダーのドキュメントはどんな第三者の解説記事よりも速く変わるので、公式を真実の source of truth として扱い、コミュニティのガイドはその上に乗る補足解説として扱う。 次に、自分に必要な複雑さのレベルの参考スキルを1つ選び、構成をゼロから設計するのではなくそれを流用する。 - 基本: 最小限のフロントマターと短い指針のブロックだけ。それ以外はなし。 - 中級: 言語パッケージ、references ディレクトリ、言語別のドキュメント。 - 上級: スクリプト、ワークフローファイル、テンプレート、抽出用ヘルパー、複数のエントリーポイント。 他チームの本番プラグインを2〜3個読むほうが、構成を自分で発明するより大抵は速い。プラグインとスキルの質問に答えられる、ドキュメントを参照できるヘルパーエージェントが環境にあるなら、記憶で答えずにそちらへ質問を回すこと。 ## 複数のランタイムで読まれても、メタデータの正本は1つにする 複数のエージェントランタイムが自分のプラグインを読み込める場合は、メタデータ形式をひとつだけ正本として選び、ランタイムごとのサイドカーのコピーを追加しないこと。重複したメタデータはずれていき、そのずれは CI ではなくユーザーによって発見される。 実務上は次のとおり。 - マーケットプレイスのマニフェストとプラグインごとのマニフェストは、それぞれ唯一の正本の場所に置く。 - 2つ目のランタイムのために、ランタイム固有のマニフェスト用ディレクトリやプラグインメタデータ用ディレクトリを並行して作らない。 - どちらのランタイムもすでに理解しているデフォルトのパスを使い、すべてのコンポーネントをプラグインのルートに置く。すなわち skills ディレクトリ、hooks ファイル、MCP 設定ファイル、アプリ設定ファイルである。 - プラグインが MCP の設定を必要とする場合は、プラグインマニフェストの中にオブジェクトを埋め込むのではなく、プラグインルートにある専用の MCP 設定ファイルに書く。 提出前に、サポートするランタイムそれぞれで読み込みチェックを実行すること。片方のランタイムで失敗したときは、もう片方のランタイムが互換性を通じて読み込めるように正本のほうを直す。同じメタデータの2つ目のコピーを追加して直すのは絶対にやってはいけない。 ## コンポーネントのディレクトリは、メタデータ用ではなくプラグインのルートに置く プラグインのディレクトリには、プラグインマニフェスト（name・version・description・author）だけを入れたプラグインメタデータ用ディレクトリを置き、さらに任意でスラッシュコマンド・自律エージェント・スキル・イベントフックのディレクトリ、そしてそのプラグインを説明する README を置く。 各スキルは skills ディレクトリの下にそれぞれ専用のディレクトリを持ち、フロントマターを載せたエントリーポイントのドキュメントと、任意で references・workflows・scripts のサブディレクトリを持つ。 いちばん人がつまずくルールはこれ。コンポーネントのディレクトリ — skills、commands、agents、hooks — は、プラグインメタデータ用ディレクトリの中ではなく、プラグインのルートに置かなければならない。そこに入れてよいのはプラグインマニフェストだけである。ローダーもレビュアーも両方これに依存しており、コンポーネントのディレクトリを置き間違えると、たいていは「何も公開しないまま黙って動くプラグイン」として現れる。 ## ケバブケースの分かりやすい名前を付け、フロントマターを書く スキルのエントリーポイントのフロントマターには、最低限 name と description が必要である。任意の allowed-tools のリストを書くと、そのスキルが本当に必要とするツールだけに制限できる。スキルの適用範囲が狭いときは必ず設定する価値がある。 - name はケバブケースにし、長さの上限（一般には64文字）に収める。 - description は三人称で書き、そのスキルが何をするのかと、いつ使うのかの両方を述べる。 - name は動名詞形を優先する。"analyzing-contracts" や "processing-pdfs" のような動詞始まりの名前は、"contract-analyzer" や "pdf-processor" のような「〜する人」型の名詞名より読みやすい。 - helper、utils、tools、misc のような曖昧な名前は避ける。すべてにマッチしてしまい、何の意味も持たない。 - ベンダー名や製品名を含む予約語は避ける。ランタイムがそれらを特別扱いすることがある。 ## descriptionに、何をするかといつ使うかを書く あなたのスキルは注目を求めて他の100個ものスキルと競合しており、description はエージェントがそのスキルを読み込むか判断するときに読む唯一のテキストであることが多い。曖昧な description は、スキルが使われないまま放置される結果か、もっと悪いことに間違った場面で発動する結果を招く。 - 三人称の文体で書く。"Analyzes X" であって "I help with X" ではない。 - 対象だけでなく、発動する状況も書く。"Use when auditing smart contracts" は "Smart contract tool" よりはるかに強いルーティングの手がかりを持つ。 - 能力を具体的に書く。"Detects reentrancy vulnerabilities" は "Helps with security" に勝る。 description は、それが実際にそうであるところのルーティングルールとして書くこと。そして書いたあとに読み返し、競合するスキルが同じリクエストを取っていってしまわないかを自問する。 ## 絶対パスを書かず、スクリプトの依存関係をスクリプトの中で宣言する 絶対パスを決してハードコードしないこと。ランタイムが提供するベースディレクトリの変数を使い、Windows 上でもスラッシュ（/）を使う。そうすれば同じスキルがどのマシンでも動く。 スキルが依存関係のあるスクリプトを同梱する場合は次のとおり。 1. その言語の標準的なインラインメタデータのブロックを使い、スクリプトのヘッダーに依存関係をインラインで宣言する。言語の最低バージョンも含める。こうすればランナーが別途インストール手順を挟まずにすべてを解決できる。 2. そのインラインメタデータを尊重するランナー経由でスクリプトを起動する。そうすれば依存関係の解決は、ドキュメントに書かれた前提条件ではなく自動処理になる。 3. リンターやフォーマッターといった開発ツール用のプロジェクトファイルを scripts ディレクトリに置いておく。 4. 言語のパッケージマネージャーがインストールできないシステムレベルの依存関係 — たとえば PDF や OCR のツール — は、プラットフォーム別のインストールコマンドとともにワークフローファイルに記載する。 ## すべてのコマンドの前に動くフックを、速く保つ すべてのコマンドの前に走るフックはホットパス上にあるので、そのコストは1回1回の呼び出しすべてで支払われる。ここでは性能は「あれば嬉しいもの」ではなく正しさの問題である。 - フル機能のインタープリタより、シェルと軽量な JSON フィルタの組み合わせを優先する。インタープリタとパーサーの起動は、ユーザーが毎コマンドで体感するレイテンシを加える。 - 早期に高速に抜ける。明らかに一致しないコマンドについては、即座に成功として終了する。そうすれば呼び出しの圧倒的多数は実質的にコストゼロになる。 - 構文木のフルパースより正規表現を選ぶ。性能上の利得が大きく、エージェントが単にコマンドを言い換えれば済む場合は、まれな誤検出を受け入れる。 - 誤検出の型をあらかじめ想定しておく。インタープリタの場所を突き止めるだけの診断コマンド、その名前を検索語として含む検索コマンド、その名前を含むファイル名 — これらが横取り（インターセプト）を発動させてはならない。 - こうしたトレードオフを変更内容の説明に書いておく。そうすればレビュアーは、その選択が雑なのではなく意図的なものだと分かる。 ## 仕様を丸ごと貼らず、調べ方と判断の理由を書く スキルは、モデルがまだ持っていない指針を提供すべきである。仕様全文をスキルに貼り付けるのはコンテキストを浪費するだけで、モデルが自分で調べられること以上のものを何も加えない。 - 仕様全文や API リファレンスを貼り付けない。代わりに、いつどうやって調べるかを教える。 - 「何を」だけでなく「なぜ」を説明する。トレードオフ、判断基準、そして初心者なら間違えるであろう判断どころを含める。 - アンチパターンは、単なる禁止事項の羅列ではなく、それがなぜ間違いなのかという理由とセットで書く。 このパターンの良い例がある。複雑なバイナリのデバッグ形式を扱うスキルは、その形式の仕様を埋め込まない。どの検査ツールを手に取るべきか、どうやってそれらに問い合わせるか、どの問いにはどのツールが適切かを教えるのである。 ## 厳しさをタスクの危なさに合わせ、使わない場面も書く スキルをどれだけ厳格にすべきかは、そのタスクがどれだけ壊れやすいかで決まる。 - 壊れやすいタスクには厳格に。セキュリティ監査、暗号の実装、コンプライアンスのチェックには、厳格で強制される手順が必要である。 - 幅のあるタスクには柔軟に。コードの探索、ドキュメント作成、リファクタリングは、選択肢を提示し判断の余地を残すべきである。 すべてのスキルのエントリーポイントは、2つのセクションを持たなければならない。そのスキルが当てはまる具体的なシナリオを列挙する「When to Use」のセクションと、別のアプローチのほうが良いケースを名指しする「When NOT to Use」のセクションである。人が飛ばしがちなのは後者の否定側のセクションだが、スキルが間違った場所で発動するのを止めているのはまさにそれである。 監査とセキュリティのスキルには3つ目のセクション「Rationalizations to Reject」が必要で、そこには見落としにつながるよくある近道や言い訳を列挙する。時間に追われているときに表に出てくるのは、まさにそういう正当化だからである。 ## 入口のファイルを短くし、詳しい話へのリンクは1段だけにする スキルのエントリーポイントはおよそ500行以内に収め、残りは references ディレクトリと workflows ディレクトリに分割する。クイックスタートを先頭に置き、詳細はリンクの向こうに置く。そうすれば、よくある経路だけで済む読者は残りを読み込まずにすむ。 リンクは1階層の深さに保つ。エントリーポイントがファイルにリンクし、それらのファイルからさらに別のファイルへ連鎖させない。ディレクトリの深さそのものは問題ない。トピック別のサブフォルダを持つ references ディレクトリはまったく妥当である。問題なのは入れ子のフォルダではなく、連鎖する間接参照のほうである。 典型的な形はこうなる。中核となる手順を収めた Quick Start セクション、詳しいパターンを載せた1つのリファレンスドキュメントを指す Advanced Usage セクション、そしてメソッドの完全なドキュメントを載せた別のリファレンスを指す API リファレンスのセクション。 ## 自動チェックとレビュアーのチェックを通し、バージョンを上げてから出す 自動化が検証してくれることと、人間のレビュアーが判断しなければならないことを分け、レビューを開く前にその両方を満たしておく。 自動チェック: name と description のある妥当なフロントマターがあること。name がケバブケースで長さの上限内であること。参照されているファイルがすべて実在すること。ホームディレクトリの絶対パスをハードコードしていないこと。サポートする各ランタイムで読み込みチェックが通ること。 レビュアーのチェック: description が正しく発動し、三人称で書かれていること。「When to Use」と「When NOT to Use」の両方のセクションがあること。例が具体的で、入力とその結果の出力を示していること。ドキュメントが「何を」だけでなく「なぜ」を説明していること。 ドキュメント: プラグインに README があること。ルートの README の表に追加されていること。プラグイン自身のメタデータ用ディレクトリではなく、リポジトリレベルのマーケットプレイスマニフェストに登録されていること。そして code-owners ファイルに、メンテナーを示す所有者のエントリがあること。 既存プラグインのバージョン更新: プラグインマニフェストとリポジトリレベルのマーケットプレイスのエントリの両方でバージョンを上げ、2つの数字を同一に保つ。多くのクライアントはバージョン番号が上がったときにだけ更新を取得するので、バージョンの引き上げを忘れると誰にも修正が届かない。