生成AIエージェントに「何を任せ、何を任せないか」を決めずに Skills（スキル）を追加していくと、権限の広がり・機密情報の混入・意図しない自動実行が起きやすい。
この記事は、Cursor や Claude Code などで使われる Agent Skills をチームや本番ワークフローに載せる前に確認すべき境界チェックを、初めて Skills を設計するエンジニア向けに整理する。
Agent Skillsとは何か
Agent Skills は、エージェント（AIコーディングアシスタント）に再利用可能な手順・制約・専門知識を与えるための仕組みだ。
Markdown 形式の SKILL.md に「いつ使うか」「何をしてはいけないか」「どのコマンドを使うか」などを書いておき、エージェントがタスクに応じて読み込む。
代表的な用途は次のとおり。
| 用途 | Skills に書く内容の例 |
|---|---|
| 記事執筆 | フロントマター形式、フッター規約、禁止語 |
| インフラ操作 | 触ってよい環境、破壊的操作の禁止 |
| レビュー | チェック観点、報告フォーマット |
| 自動化 | 承認ゲート、冪等性、失敗時の通知先 |
Skills は「プロンプトを毎回書かなくてよくなる」利点がある一方、エージェントの行動半径を広げる点ではツール連携と同じリスクを持つ。
なぜ「載せる前の境界チェック」が必要か
Skills 自体はテキストファイルだが、エージェントがそれを読むと実際のファイル操作・コマンド実行・外部送信につながる。
境界を決めずに Skills を増やすと、次のような問題が起きやすい。
| リスク | 具体例 |
|---|---|
| 権限の過剰委譲 |
git push や本番デプロイまで任せてしまう |
| 機密情報の混入 | Skills や生成物に API キー・内部ホスト名が残る |
| スコープの肥大化 | 1つの Skill がリポジトリ全体を触る |
| 承認なしの不可逆操作 | 公開・送信・課金操作が自動で走る |
| 二重実行 | スケジュールタスクと手動実行が同時に走る |
つまり Skills は「ドキュメント」ではなく、エージェントの運用ポリシーとして扱う必要がある。
境界チェックの4レイヤー
本番やチーム共有の前に、次の4層で境界を確認する。
[1. 触ってよい範囲] → ディレクトリ・ブランチ・環境
[2. 実行してよい操作] → 読取 / 書込 / 送信 / 課金
[3. 人間承認が要る操作] → 公開・push・本番・社外連絡
[4. 失敗時の挙動] → 通知・ロールバック・停止
レイヤー1：触ってよい範囲（スコープ）
- 対象リポジトリ・ディレクトリを Skill に明記する
- 「このファイルだけ」「このブランチだけ」と最小スコープに絞る
- 顧客固有・NDA 対象のパスは Skills の参照元から除外する（読ませない）
レイヤー2：実行してよい操作
Skills には「やってよいこと」と「やってはいけないこと」を対で書く。
| 分類 | 例（やってよい） | 例（禁止） |
|---|---|---|
| Git |
status, diff, 作業ブランチへの commit |
push --force, main への直接 push |
| ネットワーク | 公式ドキュメントの取得 | 未承認の Webhook 送信 |
| シェル | lint・テスト・ローカルビルド | 本番 DB への書き込み |
| 外部サービス | 下書き保存 | 公開・課金・メール送信 |
レイヤー3：人間承認ゲート
不可逆または影響が大きい操作は、Skill 内で明示的に止める。
- 公開（Qiita / note / npm publish 等）
- リモートへの push
- 本番デプロイ・インフラ変更
- 社外向けメッセージ送信
- 有料 API の大量呼び出し
承認ゲートのパターン例：
下書き作成 → 自動チェック（lint / 機密スキャン）→ 人間が✅ → 公開runnerが実行
Skill 側では「このタスクでは公開しない」「承認待ちで終了する」と書いておく。
レイヤー4：失敗時・冪等性
- 冪等ガード：同じ日・同じ basename で二重生成しない条件を Skill か runner に書く
- 失敗通知：黙って終了せず、理由付きで通知する
-
ロールバック：公開失敗時に
private: trueへ戻す等、安全側に倒す
載せる前のチェックリスト
Skills を共有リポジトリや自動実行に載せる前に、次を確認する。
-
Skill の
descriptionに「いつ発火するか」が書いてある - 触ってよいパス・触ってはいけないパスが明記されている
- 破壊的操作（force push、本番変更、一括 publish）が禁止されている
- 公開・送信・課金は「明示的な go / 承認後のみ」と書いてある
- 秘密情報を Skill や生成物に書かないルールがある
- 機密スキャンや lint などのハードゲートがパイプラインに入っている
- 二重実行を防ぐ冪等条件がある（日付・queue・マーカーファイル等）
- 失敗時に通知する手順がある（理由を添えて）
- Skill が参照する外部 URL・コマンドが実在し、最小権限である
- テスト実行（dry-run）で意図しないファイルを触らないことを確認した
Skills 設計のミニテンプレート
新規 Skill を書くとき、最低限次の見出しを入れると境界が伝わりやすい。
## 触る範囲
- 対象: ~/example-repo/public/ のみ
- 禁止: ops/ のシークレット、.env
## やってよい操作
- 下書き Markdown の作成
- npm run lint:frontmatter
## やってはいけない操作
- npx publish --all
- git push（ユーザー明示指示がない限り）
## 完了の定義
- 下書き保存 + lint CLEAN + 承認キュー投入
## 失敗時
- 公開せず、理由付きで通知して終了
「何をする Skill か」だけでなく「どこで止まる Skill か」を書くのが境界設計の要点だ。
失敗パターン
パターン1：便利さ優先で Skill に push まで書いてしまう
→ 対策：書き込みはローカル下書きまで。push / 公開は別 runner + 承認に分離する。
パターン2：機密スキャンを「公開直前」だけにする
→ 対策：下書き作成後・承認前・公開直前の複数箇所で同じゲートを通す。
パターン3：1 Skill に記事執筆・画像生成・公開・通知を全部詰める
→ 対策：writer / scan / approval / publish を分け、各 Skill のスコープを小さく保つ。
パターン4：バックログや学習ノートを Skill の参照元に含める
→ 対策：テーマ源はサニタイズ済みリストだけに限定し、NDA 対象パスは Skill から参照禁止にする。
パターン5：失敗時に何も通知しない
→ 対策：自動タスクは必ず成功/失敗を外部通知し、理由を1行で残す。
まとめ
- Agent Skills はエージェントへの運用ポリシーであり、ドキュメント追加と同じ感覚で載せない。
- 境界は「スコープ」「操作権限」「人間承認」「失敗時挙動」の4レイヤーで切る。
- 不可逆操作は Skill 内で止め、承認 runner など別経路に分離する。
- 載せる前にチェックリストで機密・冪等・通知を確認する。
次のステップとして、既存の Skill を1つ選び「触る範囲」と「やってはいけない操作」だけを追記し、dry-run で意図しないファイルが変わらないか確認するとよい。
参考リンク
この記事を書いた人✏️@YushiYamamoto
ITPRODX.com代表 / AIアーキテクト
Next.js / TypeScript / n8nを活用した自律型アーキテクチャ設計を専門としています。
日々の自動化の検証結果や、ビジネス側の視点（ROI等）に関するより深い考察は、以下の公式サイトおよびnoteで発信しています。