Google Agent Skillsの中身公開 6つの自動ゲートとAIレビュー
GoogleがAgent SkillsのCI全容を公開。PRを止める6つの自動ゲート、YAMLのバージョン罠、L1/L2/L3構成、AIレビューが弾く「決定的処理の罠」を実測値つきで解説。
結論：スキルは「文書」ではなく「製品」として出荷されている
2026年10月29日、GoogleのRemigiusz Samborski氏がAgent Skillsリポジトリの舞台裏を公開した。今回はGitHubに出るまでに通る6つの自動ゲートと、スキルをレビューするAIエージェントの中身だ。
実測値はこうだ。2026年11月4日時点でgithub.com/google/skillsはスター21,830。ルートのindex.jsonが列挙するスキルは184件で、記事本文の「170以上」より進んでいる。
なぜ「製品」扱いなのか
Googleの主張はシンプルだ。スキルは人間向けのドキュメントではなく、エージェントの推論ループ・ツール選択・実行経路を操る命令だ。フレーズの置き場所を1つ間違えるだけで、エージェントは不正なコマンドフラグを呼び、無限ループに入り、トークンを浪費する。だから指示文の1行を直すのは仕様変更と同じ扱いになる。
ここから3つの要件が導かれる。厳格なセマンティックバージョニング（挙動が変わる変更には必ずバージョンを上げる）、決定的な自動検証（人間やAIがレビューする前にリンターが機械的に弾く）、評価証拠の必須化だ。
6つの自動ゲート
PRが立つとパイプラインが即走る。GitHubへエクスポートされる前に、次を通過する。
- 構造準拠：ディレクトリ配置、許可ファイル、分類
- スキルリンター：フロントマター、フォルダ命名、Markdown書式
- セマンティックバージョニング：挙動変更に対するバンプの有無
- 評価スイート：評価セットの妥当性と最新レポートの存在
- リンク検証：リンク切れがないこと
- AIレビューエージェント：品質と設計標準の適合
- 最後に人間の承認（領域の専門家）
構造準拠とリンターのルールは細かい。フォルダ名とメタデータ名の一致、文字数上限、フロントマターの必須項目、置けるファイルの許可リスト、Markdown整形規約、そしてindex.jsonが最新であること。
リンクは2段構えだ。PR時に相対リンクを検証し、毎週月曜にはGitHub Actionsがlycheeで外部リンクを全走査する。170件超が変化の速いドキュメントを指す以上、承認後の移動は防げないからだ。
6か月の履歴から出た教訓は2つ。ドリフトは数日で起きるので、索引は手で直さず生成スクリプトとCIで強制する。もう1つ、当初はCIのパターンが広すぎ、1行の誤字修正がチケット無しでブロックされる一方、深い階層の新規スキルは検査をすり抜けた。追加か修正か、パスの深さで規則を書き分けるべきだった。
バージョンは「文字列」でなければ弾かれる
検証は2段階ある。1つめはクォートされた文字列であること。YAMLはクォートなしの2.0を数値と解釈し、文字列を期待するツール側でパースエラーになる。2つめは遷移の妥当性で、新規は1.0.0から始め、指示・スクリプト・参照を変えたら上げる。上げ忘れはPRブロックだ。
ランタイムで読まれない番号を厳格に管理する理由は配布のためだ。スキルは自動更新されないので遅延はない。代わりに明示的なバージョンがあれば、開発者は手元と上流カタログを比較し、npx skills updateを走らせるタイミングを決められる。このCLIはnpmで実在し、最新版はv1.7.6だ。
評価スイートの検証
継続評価は「スキルあり／なし」で成績を比較するが、評価セットが壊れていれば結果はノイズだ。バリデータは次を強制する。
- ファイル参照の解決：
@file:test_prompt.txtの参照先が存在し、空でないこと - expectationの原子性：1つの期待は1つの基準だけを検査する
- 重複検出：プロンプト重複や矛盾する期待を検出
- 評価レポートの必須リンクと鮮度チェック（最新コミットに対して実行されたものか）
最後の鮮度が実務で一番効く。コミットを重ねると古い評価結果が添えられたままになる。
AIレビューエージェントが弾く3つのアンチパターン
リンターでは「指示が分かりにくい」「参照が冗長」「これはbashにすべき」までは判定できない。そこでレビューパイプラインにAIレビューエージェントを組み込んだ。スキルをレビューするためのスキルを使っているのがGoogleの言い方だ。
決定的処理の罠。 最初の問いは「このタスクはそもそも指示文に属するのか」。よくある失敗が、CLIコマンドの厳密な手順をMarkdownに直接書くことだ。LLMは確率的エンジンであり、1か所のずれがエラーになる操作を文章で指示すれば幻覚を招く。固定のCLI手順、JSONパーサ、デプロイ手順はscripts/配下のスクリプトへ移し、Markdownはアーキテクチャ選択、エラーログ診断、コード合成といった判断を要する作業に残す。
L1/L2/L3の階層と参照連鎖の禁止。 2,000行のスキルを読み込めばコンテキストを食い、推論品質が落ちる。L1はフロントマターのnameとdescription（発見とルーティング用）、L2はSKILL.md本体で500行未満、L3はAPIリファレンスやスキーマをreferences/へ。L3はフラット構造（サブディレクトリ禁止）かつ単一ホップでなければならない。SKILL.md→参照→別ファイルという連鎖は、ツール呼び出しが増えるうえ評価でエージェントが2段目を辿る前に止まるケースが頻発したためブロックされる。
非対話スクリプトの設計。 ヘルパーはエージェントがサンドボックスで直接実行する前提だ。対話プロンプトで止まるスクリプトは不合格。入力をフラグか環境変数で受け、--helpを用意し、破壊的操作には--dry-runを付ける。JSONは標準出力、エラーは標準エラーへ分離する。
まとめ：持ち帰るならこの順番で
効果の大きい順に、index.jsonの手書きをやめる、バージョンをクォート付き文字列で強制する、SKILL.mdの行数上限を決める、CLI手順をスクリプトへ移す、期待を1基準ずつに割る、リンクチェックを定期実行する（lycheeは無料）。
エージェント時代の品質管理は、プロンプトの書き方ではなく開発インフラの問題になった。バージョニング、評価の原子性、リンクの鮮度、コスト制御。どれも地味だが、184件を複数チームで回すには避けられない。社内でスキルを配れば数週間で「どれが最新か分からない」という声が出る。必要なのは優れたプロンプトではなく、索引を生成するスクリプトとバージョンを強制するCIだ。