生成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で発信しています。