Agent Skillsを複数の開発者や自動実行環境で共有するとき、レビュー対象をSKILL.mdだけに絞ると、実際に動くスクリプトや参照ファイル、実行環境の権限を見落とす。Skillの配布物と、Skillを実行するエージェントの権限を別々に管理する必要がある。
技術的な問い：Skillを信頼するとは何を信頼することか
Agent Skillsの公開仕様では、SkillはSKILL.mdを必須とし、scripts/、references/、assets/などを含むディレクトリとして定義されている。つまりレビュー対象は指示文だけではない。仕様ではallowed-toolsも定義されているが、これは実験的な項目で、クライアントごとに対応が異なる。
ここから導ける設計上の結論は、Skillの記述を実行権限そのものとして扱わないことだ。Skillは手順を提案し、ホスト側の実行環境がファイル・コマンド・ネットワークの可否を強制する。指示文に「送信しない」と書くだけで、送信権限が消えるわけではない。
設計選択肢：指示文だけで制御するか、実行環境でも制御するか
| 方式 | 利点 | 主な弱点 |
|---|---|---|
| Skillの指示だけで制限 | 導入が簡単で移植しやすい | 指示の誤読や競合時に、ツール側の権限を止められない |
| ホストの権限設定だけで制限 | 実行可能な操作を機械的に絞れる | 業務上の判断基準や承認条件は表現しにくい |
| Skillとホストを分けて併用 | 手順と強制境界をそれぞれ管理できる | 設定の重複・ずれを継続的に点検する必要がある |
本番を想定するなら3つ目を採る。SKILL.mdには目的・入力・出力・停止条件を書き、ホストには対象パス、許可コマンド、ネットワーク可否、外部操作の制限を設定する。仕様のallowed-toolsは補助的な宣言として読み、ホストが強制していることを別途確認する。
採用する設計：配布物を固定し、能力を段階的に与える
導入単位を次のように分ける。
-
配布物：レビュー済みのコミットやリリースに固定し、
SKILL.mdと同梱スクリプトを一緒に検査する。 - 能力：最初は読み取りとローカル検証だけにし、書き込みやネットワーク接続は必要な範囲だけ追加する。
- 操作：公開、送信、課金、本番変更は別の承認経路に分け、自動実行の許可に含めない。
- 記録：実行したSkillの版、対象、呼び出したツール、承認結果、生成物の識別子を残す。
この分離なら、Skillの更新と権限の拡大を同じ変更にせず、差分ごとにレビューできる。特定の実行環境での検証値ではなく、ここでは汎用的な設計案として示している。
実装の要点：導入ゲートを小さく作る
導入前に、配布物と実行環境について以下を確認する。
配布物:
- 取得元とレビュー済みバージョンを固定したか
- SKILL.mdが参照する全ファイルを列挙したか
- スクリプトの依存関係・書き込み先・通信先を確認したか
実行環境:
- 対象ディレクトリを限定したか
- 読み取り専用で通る処理を先に分けたか
- 不要な環境変数や認証情報を渡していないか
- 外部操作が人間承認を経由するか
テストでは通常入力だけでなく、Skillの指示と矛盾する入力、壊れた参照ファイル、権限外の操作を要求する入力も使う。確認するのは回答文の見た目だけではない。許可されないツール呼び出しが拒否されたか、対象外ファイルに変更がないか、停止理由と実行記録が残ったかを見る。
失敗・トレードオフ：allowed-toolsをアクセス制御と誤認する
仕様上、allowed-toolsの対応は実装ごとに異なる。そこでこの値だけを見て「このSkillは読み取り専用」と判断すると、実際のクライアントで制約されていない可能性が残る。使うクライアントの仕様と設定を確認し、強制されない項目はホスト側の権限設定で補う。
もう一つの失敗は、参照先を増やすたびに配布物全体を再確認しないことだ。SKILL.mdから相対パスで読み込む文書、実行可能ファイル、外部依存を含めて一つのレビュー単位として扱う。自動更新は便利だが、固定版との差分レビューとロールバック手順を省く理由にはならない。
本番運用論点：変更と実行の両方を監視する
- 変更管理：誰が、どの版を、何の理由で更新したかを記録する。
- 実行監視：Skill名・版、ツール呼び出し、拒否、承認、失敗を相関できる形で記録する。入力本文や秘密情報は必要以上に保存しない。
- 停止条件：想定外の書き込み、権限拒否の回避試行、参照先の欠落があれば処理を止め、再試行で外部操作を重ねない。
- 復旧：最後に承認された版へ戻せるようにし、復旧後は同じ拒否テストを再実行する。
今後の改善
まず読み取り専用のSkillを一つ選び、参照ファイルの棚卸し、権限外操作の拒否、実行記録の確認までを自動テストにする。その後、書き込みや外部連携を一つずつ追加し、各能力に個別の承認条件とロールバック方法を設ける。評価指標は成功率だけでなく、誤った権限付与の検出率や、拒否後に安全に停止できた割合も含める。
同様の仕組みの設計・構築・運用については相談可能。
この記事を書いた人✏️@YushiYamamoto
ITPRODX.com代表 / AIアーキテクト
Next.js / TypeScript / n8nを活用した自律型アーキテクチャ設計を専門としています。
日々の自動化の検証結果や、ビジネス側の視点（ROI等）に関するより深い考察は、以下の公式サイトおよびnoteで発信しています。