前回作成した Azure CAF エージェントチームを、GitHub Copilot カスタムエージェントの「正しいフォーマット」という観点で見直してみます。Copilot エキスパートエージェントを新たに作成し、エージェントが暴走しないためのガードレール設計も解説します。

はじめに

前回の記事では、Azure CAF（Cloud Adoption Framework）の組織論に基づいた 7 つのカスタムエージェントを GitHub Copilot CLI で作成しました。作成後、人事評価エージェントによって各エージェントを評価したのですが、ここで気づいてしまいました。

「そもそも GitHub Copilot カスタムエージェントとして正しいフォーマットで書けているか」を評価してへんかった！

人事評価エージェントの評価観点は「CAF 準拠度」「役割の明確さ」「実用性」「他エージェントとの連携」「セキュリティ考慮」の 5 項目でした。これらはビジネス要件としては適切ですが、エージェントが期待通りに動作するための技術的フォーマットの評価が抜けていました。

また、著者自身が GitHub Copilot の最新機能をキャッチアップできていないため、エージェントが暴走しないためのガードレール設計についても改めて整理したいというモチベーションもありました。

今回のエージェントは https://github.com/NakayamaKento/caf-agents においてます。

この記事のゴール

• GitHub Copilot カスタムエージェントの正しいフォーマットとベストプラクティスを整理する
• Agent Skills（SKILL.md）を活用した CAF エージェント強化を学ぶ
• Custom Instructions・Prompt Files・コンテキスト管理 など実行時 Tips を押さえる
• エージェントの暴走を防ぐガードレール設計のパターンを理解する
• Copilot エキスパートエージェントを作成し、既存の CAF エージェントを技術的観点で評価する
• 人事評価エージェントと連携した改善サイクルを実施する

想定読者

• 前回の記事を読んだ方（または GitHub Copilot CLI でカスタムエージェントを使ったことがある方）
• カスタムエージェントの品質を向上させたい方
• AI エージェントの「暴走防止」設計に関心がある方

背景

人事評価エージェントの評価基準の盲点

前回作成した人事評価エージェント（hr-evaluation.agent.md）は、以下の 5 観点でエージェントを評価していました。

これらはいずれも重要な評価観点ですが、GitHub Copilot のカスタマイズファイル（.agent.md・SKILL.md・copilot-instructions.md・.prompt.md 等）が正しいフォーマットで書かれているかという技術的な観点が完全に欠けていました。たとえば:

• mcp-servers フィールドをオブジェクト形式で書くべきところを配列形式で書いていないか
• description がエージェント推論のトリガーとして機能する書き方になっているか
• 不要な execute ツールを付与していないか（最小権限の原則）
• バウンダリ（禁止事項）が明記されているか
• SKILL.md の name・description が正しいフォーマットで書かれているか
• copilot-instructions.md のルールがエージェントの指示と矛盾していないか

これらの問題は、エージェントが「動かない」「期待しない動作をする」「セキュリティリスクになる」原因になります。

エージェントが暴走するとはどういうことか

具体的には、以下のような状況を指します:

• 意図しないファイル変更: edit ツールを持つエージェントが、レビューを求めたつもりが直接ファイルを書き換えてしまう
• 本番環境への誤操作: execute ツールを持つエージェントが、確認なしにインフラ変更コマンドを実行する
• 機密情報の漏洩: エージェントが .env ファイルや Secret の内容をログに出力してしまう
• 無限ループ: エージェント同士が互いを呼び出し続けてしまう
• スコープ外の操作: 「ファイルをレビューして」と頼んだのに無関係なファイルまで変更してしまう

これらを防ぐための設計がガードレールです。

ざっくり手順

1. GitHub Copilot カスタムエージェントのフォーマットとベストプラクティスを理解する
2. Agent Skills（SKILL.md）を理解し、CAF エージェント向けのスキルを作成する
3. Custom Instructions・Prompt Files・コンテキスト管理の Tips を押さえる
4. エージェント暴走防止のガードレール設計を整理する
5. Copilot エキスパートエージェント（copilot-expert.agent.md）を作成する
6. 既存の CAF エージェントを評価する
7. 人事評価エージェントとの連携で改善サイクルを実行する

カスタムエージェントのフォーマットとベストプラクティス

.agent.md ファイルの正しい構造

GitHub Copilot CLI のカスタムエージェントは .agent.md という拡張子のファイルで定義します。.github/agents/ ディレクトリに配置することが推奨されています。

ファイルは大きく 2 つの部分で構成されています:

[YAML フロントマター]
---
name: エージェント名
description: "説明"
tools:
  - read
  - search
---

[Markdown 本文]
# エージェントのペルソナと指示

YAML フロントマターの全フィールド解説

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

---
# ✅ 必須フィールド
name: my-agent                   # lowercase + hyphens 推奨
description: "エージェントの説明"  # エージェント推論のトリガーになる重要なフィールド

# 🔧 ツール設定（必要なものだけ付与する）
tools:
  - read      # ファイル読み込み
  - search    # ファイル・テキスト検索
  - edit      # ファイル編集（変更が必要な場合のみ）
  - execute   # シェルコマンド実行（最後の手段）
  - agent     # 他のカスタムエージェントを呼び出す
  - web       # Web 検索・URL 取得

# 🌐 MCP サーバー設定（オブジェクト形式！配列形式は誤り）
mcp-servers:
  azure-mcp:                     # サーバーの識別名（任意のキー）
    type: 'local'
    command: 'npx'
    args: ['-y', '@azure/mcp@latest', 'server', 'start']
---

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

# ❌ 誤り（配列形式）
mcp-servers:
  - name: azure-mcp
    type: local
    command: npx

# ✅ 正しい（オブジェクト形式）
mcp-servers:
  azure-mcp:
    type: 'local'
    command: 'npx'

6 つの重要なベストプラクティス

1. description は「いつ使うか」を明示する

description フィールドは単なる説明文ではなく、エージェント推論のトリガーになります。GitHub Copilot がどのエージェントを起動すべきかを判断する際に参照されます。

1
2
3
4
5
6
7

# ❌ 悪い例（曖昧すぎる）
description: "便利なアシスタントです"

# ✅ 良い例（いつ使うかが明確）
description: "Azure インフラのコスト分析と最適化提案を行う専門家。
  Azure Cost Management のレポート分析、予算超過のアラート調査、
  リソース最適化の提案に使用する。キーワード: cost, 予算, コスト最適化"

2. tools は最小権限の原則を適用する

エージェントに必要以上のツールを付与することは、セキュリティリスクと誤操作の原因になります。

3. バウンダリを明示する

「〜してはいけない」という禁止事項を具体的に書くことが、最も効果的な暴走防止策です。

1
2
3
4
5
6

## ⚠️ このエージェントの制約

- **このエージェントはファイルの変更を行いません**
- 本番環境のリソースを直接変更するコマンドを実行しません
- `.env` ファイルや Secrets の内容をログに出力しません
- 提案のみを行い、実行は必ず人間が判断してください

4. 具体例（入出力例）を含める

抽象的な指示より、1 つの具体的な入出力例が動作の安定性を大幅に向上させます。

5. mcp-servers はオブジェクト形式

前述の通り、配列形式は誤りです。必ずオブジェクト形式（キーと値のペア）で記述してください。

6. ファイル名は lowercase + hyphens

my-agent.agent.md の形式を推奨します。大文字やアンダースコアは避けてください。

Agent Skills の活用

Agent Skills とは

Agent Skills（エージェントスキル）は .agent.md とは別の仕組みで、GitHub Copilot に再利用可能な手順・知識・スクリプトを教えるための機能です。

• カスタムエージェント（.agent.md）: 特定の役割・ペルソナを持つ専門家エージェント。/agent <名前> で明示的に呼び出す
• Agent Skills（SKILL.md）: 繰り返し使う手順や専門知識のカプセル化。Copilot が文脈から自動的に判断して読み込む

この 2 つを組み合わせることで、「役割（エージェント）× 手順知識（スキル）」という形で Copilot の能力を最大化できます。

graph LR
    subgraph "Agent Skills (.github/skills/)"
        S1["📘 caf-governance-review<br/>SKILL.md"]
        S2["📘 azure-policy-lint<br/>SKILL.md"]
        S3["📘 iac-security-check<br/>SKILL.md"]
    end

    subgraph "Custom Agents (.github/agents/)"
        A1["🤖 cloud-governance<br/>.agent.md"]
        A2["🤖 cloud-security<br/>.agent.md"]
        A3["🤖 copilot-expert<br/>.agent.md"]
    end

    S1 -->|自動読み込み| A1
    S2 -->|自動読み込み| A1
    S3 -->|自動読み込み| A2
    S1 -->|評価対象| A3

    classDef skill fill:#f9f0ff,stroke:#6f42c1,color:#333;
    classDef agent fill:#e6f3ff,stroke:#0078d4,color:#333;
    class S1,S2,S3 skill;
    class A1,A2,A3 agent;

SKILL.md のファイル構造

スキルは .github/skills/<スキル名>/SKILL.md というパスに配置します。各スキルは専用のサブディレクトリを持ちます。

.github/
├── agents/
│   ├── cloud-governance.agent.md
│   └── copilot-expert.agent.md
└── skills/
    ├── caf-governance-review/
    │   └── SKILL.md
    └── azure-policy-lint/
        ├── SKILL.md
        └── lint-policy.sh   ← スクリプトも同梱できる

SKILL.md ファイルの構造は以下の通りです:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

---
name: caf-governance-review          # lowercase + hyphens（必須）
description: >                       # いつ使うかを明記（必須）
  Azure CAF のガバナンス観点で IaC ファイルをレビューする際に使用する。
  Bicep や Terraform の Azure Policy 定義、RBAC 設定のレビューに特化。
  キーワード: governance review, policy, RBAC, IaC レビュー
---

# CAF ガバナンスレビュースキル

## レビュー手順

以下の手順で Azure IaC ファイルを CAF ガバナンス観点でレビューしてください:

1. **リソースの命名規則を確認**: CAF の命名規則ガイド（`abbr.md`）に準拠しているか
2. **タグの強制ポリシーを確認**: `Environment`、`Owner`、`CostCenter` タグが必須になっているか
3. **RBAC の最小権限を確認**: カスタムロールは使用せず組み込みロールを使っているか
4. **Azure Policy の効果を確認**: `deny` より `audit` → `deployIfNotExists` の段階的導入を推奨

## チェックリスト

- [ ] リソース名が `<種別>-<ワークロード>-<環境>-<連番>` 形式か
- [ ] タグ強制ポリシーの `enforcementMode` が設定されているか
- [ ] 本番環境のリソースに `ResourceLock` が設定されているか

CLI でのスキル管理コマンド

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

# 利用可能なスキルの一覧表示
> /skills list

# スキルを有効・無効に切り替え（↑↓ キーで選択、スペースでトグル）
> /skills

# スキルの詳細情報（場所・説明）を表示
> /skills info

# スキルを明示的に指定して実行
> /caf-governance-review を使って .github/policies/ をレビューしてください

# セッション中に追加したスキルを即時反映
> /skills reload

CAF エージェント向けスキルの設計例

今回の CAF エージェントチームに対して、以下のスキルを作成してみます。

Copilot CLI でスキルを作成する

スキルの作成も Copilot CLI に任せることができます。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

copilot

# スキルの作成を指示
> .github/skills/caf-governance-review/ ディレクトリを作成し、
  SKILL.md ファイルを作成してください。

  このスキルは Azure CAF のガバナンス観点で Bicep/Terraform ファイルを
  レビューするための手順を定義します。
  CAF のガバナンス 5 分野（コスト管理、セキュリティベースライン、
  リソース整合性、ID ベースライン、デプロイ高速化）をカバーしてください。

その他の Copilot カスタマイズ機能

.agent.md と SKILL.md に加えて、GitHub Copilot にはエージェントの動作品質を底上げするカスタマイズ機能がさらに 3 つあります。改善サイクルの網羅性を高めるために、これらも押さえておきましょう。

graph TB
    subgraph "GitHub Copilot カスタマイズの全体像"
        CI["📋 Custom Instructions<br/>copilot-instructions.md<br/>（リポジトリ全体のベースライン）"]
        PI["📂 Path-specific Instructions<br/>.instructions.md<br/>（ファイルパスごとのルール）"]
        PF["📝 Prompt Files<br/>.prompt.md<br/>（再利用可能なプロンプト）"]
        AG["🤖 Custom Agents<br/>.agent.md<br/>（専門家ペルソナ）"]
        SK["📘 Agent Skills<br/>SKILL.md<br/>（手順知識カプセル）"]
    end

    CI -->|全エージェントに適用| AG
    PI -->|パス一致時に適用| AG
    SK -->|文脈で自動読み込み| AG
    PF -->|手動で呼び出し| AG

    classDef base fill:#e8f5e9,stroke:#43a047,color:#333;
    classDef agent fill:#e6f3ff,stroke:#0078d4,color:#333;
    classDef skill fill:#f9f0ff,stroke:#6f42c1,color:#333;
    classDef prompt fill:#fff3e0,stroke:#ef6c00,color:#333;
    class CI,PI base;
    class AG agent;
    class SK skill;
    class PF prompt;

Custom Instructions（カスタムインストラクション）

Custom Instructions は、リポジトリ内のすべての Copilot インタラクション（エージェント含む）に適用されるベースラインルールです。

リポジトリ全体のベースライン: copilot-instructions.md

.github/copilot-instructions.md に配置すると、すべてのエージェントが自動的にこの指示を継承します。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

# Copilot Instructions

このリポジトリは Azure CAF（Cloud Adoption Framework）に基づくエージェントチームです。

## 基本ルール
- すべての提案は Azure Well-Architected Framework の 5 本柱を考慮する
- IaC は Bicep を第一選択、Terraform を第二選択とする
- リソース命名規則は CAF の推奨形式（`<種別>-<ワークロード>-<環境>-<連番>`）に従う
- 日本語で回答する（技術用語は英語のまま使用可）

## セキュリティ
- 認証情報をコードに含めない（Azure Key Vault を使用）
- 本番環境の変更は必ず人間がレビューしてから適用する

パス固有のインストラクション: .instructions.md

.github/instructions/*.instructions.md に配置し、YAML フロントマターの applyTo で対象パスを指定します。

1
2
3
4
5
6
7

---
applyTo: "**/bicep/**"
---
# Bicep ファイルのルール
- モジュール分割を推奨（1 ファイル 200 行以下）
- パラメータには必ず `@description` デコレータを付ける
- `param` のデフォルト値には環境変数を使わない

1
2
3
4
5
6
7

---
applyTo: "**/policies/**"
---
# Azure Policy ファイルのルール
- `effect` は `audit` を優先し、`deny` は最終手段
- `policyRule.if` の条件は明示的に記述
- displayName と description を必ず設定する

Prompt Files（プロンプトファイル）

Prompt Files は、繰り返し使うプロンプトをテンプレート化して .github/prompts/*.prompt.md に保存する機能です。

改善サイクルのプロンプトをファイル化することで、チーム全員が同じ品質基準でエージェントを評価・改善できます。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

---
# .github/prompts/agent-review.prompt.md
---
# Copilot カスタマイズファイル全体レビュープロンプト

以下の手順で .github/ 内の Copilot カスタマイズファイルを評価してください:

1. @.github/agents/copilot-expert.agent.md の評価フレームワーク（35 点満点）を使用
2. 以下のファイルをすべて読み込み:
   - .github/agents/*.agent.md（エージェント定義）
   - .github/skills/*/SKILL.md（Agent Skills）
   - .github/copilot-instructions.md（ベースラインルール）
   - .github/instructions/*.instructions.md（パス固有ルール）
   - .github/prompts/*.prompt.md（プロンプトテンプレート）
3. エージェント定義は以下の観点で評価:
   - フォーマット準拠度
   - description の品質
   - ツールの最小権限
   - バウンダリ定義
   - 具体例の有無
   - Skills との連携
   - Custom Instructions / Prompt Files の活用
4. Skills・Instructions・Prompt Files はフォーマット準拠を個別チェック:
   - SKILL.md: name・description の YAML フロントマターが存在するか
   - .instructions.md: applyTo glob パターンが正しいか
   - copilot-instructions.md: エージェントとのルール矛盾がないか
5. スコアと改善提案をテーブル形式で出力

プロンプトファイルは CLI で以下のように利用します:

1
2
3
4

# プロンプトファイルを指定して実行
copilot

> /prompt agent-review

コンテキスト管理の Tips

エージェント実行時にはコンテキストウィンドウ（トークン上限）の管理が重要です。大量のファイルを評価する改善サイクルでは特に意識が必要です。

1
2
3
4
5
6
7
8

# コンテキスト使用量の確認
> /context

# 長いセッションの途中で圧縮
> /compact

# 特定ファイルを指定して評価
> @.github/agents/cloud-governance.agent.md を読み込んで評価してください

エージェント暴走防止のガードレール設計

このセクションでは暴走防止のガードレール設計をより詳しく解説します。

graph TB
    subgraph "リスクレベルと対策"
        L1["🟢 Low Risk<br/>read + search のみ<br/>分析・評価エージェント"]
        L2["🟡 Medium Risk<br/>edit を含む<br/>コード生成・改善エージェント"]
        L3["🔴 High Risk<br/>execute を含む<br/>インフラ変更エージェント"]
    end

    subgraph "ガードレール層"
        G1["ツール最小権限<br/>不要なツールを除外"]
        G2["明示的な禁止事項<br/>DON'T リストを本文に記載"]
        G3["提案のみモード<br/>実行は人間が判断"]
        G4["スコープ制限<br/>対象ディレクトリを限定"]
        G5["/plan モード推奨<br/>実行前に計画を確認"]
    end

    L1 --> G1
    L2 --> G1
    L2 --> G2
    L2 --> G3
    L3 --> G1
    L3 --> G2
    L3 --> G4
    L3 --> G5

ガードレール設計の 4 つの層

第 1 層: ツールの最小権限

最も基本的なガードレールです。execute ツールは付与しないだけで、シェルコマンドの誤実行を完全に防げます。

1
2
3
4
5

# 分析系エージェントは read + search のみで十分
tools:
  - read
  - search
# execute は絶対に不要

第 2 層: 本文への明示的な禁止事項

YAML フロントマターのツール制御だけでは不十分です。本文にも明確な制約を書きます。

1
2
3
4
5
6
7

## ⚠️ 重要な制約

### やってはいけないこと（NEVER）
- 本番環境（prod/production）の Azure リソースを変更しない
- `.env`、`*.key`、`*.pem` など認証情報ファイルを読み込まない
- git push、terraform apply などの破壊的コマンドを実行しない
- 同一エージェントを再帰的に呼び出さない（無限ループ防止）

第 3 層: 提案のみモードの宣言

エージェントに「自分は提案するだけで、実行は人間が決める」という役割を明確に意識させます。

1
2
3
4
5
6
7

## 🎯 このエージェントの役割

このエージェントは **分析と提案のみ** を行います。
提案した改善を実際に適用するかどうかは、必ず人間がレビューして判断してください。
変更を適用する場合は、以下のいずれかの方法を取ってください:
- 別のエージェント（例: platform-team エージェント）に依頼する
- 人間が直接コードを編集する

第 4 層: /plan モードの活用推奨

GitHub Copilot CLI の /plan モードを使うと、エージェントが実際に行動する前に計画を提示します。エージェントの本文に利用を促す記述を加えることで、予期しない操作を防げます。

1
2
3

## 💡 推奨される使い方

複数ファイルへの変更を伴う場合は、まず `/plan` モードで計画を確認してください:

1

copilot -p "/plan .github/agents/ 内のエージェントをすべて改善してください"

どのエージェントにどのガードレールを適用するか

Copilot エキスパートエージェントの作成

ここまでのベストプラクティスを踏まえて、.github/agents/copilot-expert.agent.md を作成します。このエージェントは .agent.md だけでなく、SKILL.md・copilot-instructions.md・.instructions.md・.prompt.md など GitHub Copilot のすべてのカスタマイズファイルを横断的にレビューできる設計にします。

Copilot CLI でエージェントを作成する

前述のベストプラクティスをすべて盛り込んだエージェントを、Copilot CLI に作成させます。以下のプロンプトを使用してください:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38

copilot

> .github/agents/copilot-expert.agent.md を作成してください。

  このエージェントは GitHub Copilot のカスタマイズファイル全般の
  フォーマットとベストプラクティスの専門家です。
  .agent.md だけでなく、SKILL.md、copilot-instructions.md、
  .instructions.md、.prompt.md のすべてを対象にレビュー・改善提案を行います。

  以下の要件を満たしてください:

  【YAML フロントマター】
  - name: copilot-expert
  - description にはエージェント推論のトリガーとなるキーワードを含める
    （agent review, agent format, copilot agent評価, skill review,
      instructions review, prompt review など）
  - tools は read と search のみ（分析専用エージェントのため）

  【本文の構成】
  - ⚠️ 重要な制約セクション: 読み取りと分析のみ、ファイル変更は行わない旨を明記
  - 🎯 レビュー対象: 以下の Copilot カスタマイズファイルすべて
    - .agent.md（カスタムエージェント定義）
    - SKILL.md（Agent Skills 定義）
    - copilot-instructions.md（リポジトリ全体のベースライン）
    - .instructions.md（パス固有インストラクション）
    - .prompt.md（プロンプトファイル）
  - 🎯 評価観点セクション: 以下の 7 観点（各 5 点、計 35 点）で評価する
    1. フォーマット準拠度（各ファイルタイプの YAML 必須フィールド・構造）
    2. description の品質（専門性、トリガーキーワード、applyTo の妥当性）
    3. ツールの最小権限（不要な execute/edit の有無）
    4. バウンダリ定義（禁止事項の明記）
    5. 具体例の有無（入出力例、チェックリスト）
    6. Agent Skills との連携（.github/skills/ の活用、SKILL.md の品質）
    7. Custom Instructions / Prompt Files の活用（ベースラインとの整合性）
  - 📝 ファイル別チェックリスト: 各ファイルタイプの必須要件を定義
  - 📝 評価出力フォーマット: テーブル形式でスコアと改善提案を出力
  - 💬 具体的な使用例: 入力例と期待する出力例を含める
  - 回答時のガイドライン: 客観的・建設的な評価、改善案の before/after 提示

エージェント設計のポイント解説

このエージェント自体がベストプラクティスの体現になっています。設計上のポイントを解説します。

graph LR
    subgraph "YAML フロントマター"
        T1["tools: read + search のみ<br/>（第 1 層ガードレール）"]
        T2["description にキーワードを含む<br/>（エージェント推論のトリガー）"]
    end

    subgraph "Markdown 本文"
        B1["⚠️ 重要な制約セクション<br/>（第 2 層ガードレール）"]
        B2["評価観点の明確な定義<br/>（役割の明確化）"]
        B3["評価出力フォーマット<br/>（出力の安定化）"]
        B4["具体的な入出力例<br/>（ベストプラクティス準拠）"]
    end

    T1 --> B1
    T2 --> B2
    B1 --> B2
    B2 --> B3
    B3 --> B4

評価の実施

方法 1: 対話モードで全体評価

Copilot CLI の対話モードで Copilot エキスパートエージェントを起動して、すべての Copilot カスタマイズファイルを横断的に評価します。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

copilot

# エージェントを切り替える
> /agent copilot-expert

# Copilot カスタマイズファイル全体を評価するプロンプト
> .github/ ディレクトリ内の Copilot カスタマイズファイルをすべて読み込み、
  GitHub Copilot のベストプラクティスに基づいて評価してください。
  対象: .agent.md, SKILL.md, copilot-instructions.md,
        .instructions.md, .prompt.md
  各ファイルのスコアと改善提案を出力してください。

方法 2: 特定のファイルタイプを詳細評価

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

# エージェント定義の詳細評価
> .github/agents/cloud-governance.agent.md を読み込んで、
  フォーマット観点での詳細な評価をしてください。
  特に mcp-servers の記法が正しいかどうかを重点的に確認してください。

# Skills のフォーマット評価
> .github/skills/ ディレクトリ内の SKILL.md ファイルをすべて読み込んで、
  name・description の必須フィールドが正しいか、
  チェックリストや手順が再利用可能な形式で書かれているかを評価してください。

# Custom Instructions の整合性チェック
> .github/copilot-instructions.md と各 .agent.md の指示内容を比較して、
  矛盾するルールがないか確認してください。

評価結果の例（想定）

前回作成した CAF エージェントチームに対して、Copilot エキスパートエージェントが全 Copilot カスタマイズファイルを横断的に評価した場合の想定結果です。

エージェント定義（.agent.md）の評価

Skills・Instructions・Prompt Files の評価

copilot-expert は .agent.md 以外のファイルも個別にチェックします。

人事評価エージェントとの連携による改善

Copilot エキスパートエージェントによる技術的評価と、前回の人事評価エージェントによるビジネス観点の評価を組み合わせた改善サイクルを実施します。

2 つのエージェントの位置付け

sequenceDiagram
    participant U as 👤 ユーザー
    participant CE as 🔍 copilot-expert
    participant HR as 👔 hr-evaluation
    participant Files as 📁 Copilot カスタマイズファイル群

    U->>CE: Copilot カスタマイズファイル全体をレビューして
    CE->>Files: .agent.md / SKILL.md / copilot-instructions.md /<br/>.instructions.md / .prompt.md を読み込み
    Files-->>CE: ファイル内容
    CE-->>U: 技術的評価レポート（スコア + ファイル別指摘 + 改善提案）

    U->>HR: エージェント定義をビジネス観点で評価して
    HR->>Files: .agent.md ファイルを読み込み
    Files-->>HR: ファイル内容
    HR-->>U: ビジネス評価レポート（スコア + 改善提案）

    U->>U: 2 つの評価結果を統合して改善方針を決定

    Note over U,Files: /delegate で自動改善サイクルへ

/delegate を使った自動改善サイクル

/delegate コマンドを使うことで、評価→改善提案→PR 作成をバックグラウンドで自動実行できます。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40

copilot -p "/delegate
以下のタスクを実行してください（提案のみ行い、ファイルの変更は PR として作成）:

1. @.github/agents/copilot-expert.agent.md の評価フレームワークを使って
   .github/ 内のすべての Copilot カスタマイズファイルを横断的に評価する
   対象: .agent.md, SKILL.md, copilot-instructions.md,
         .instructions.md, .prompt.md

2. エージェント定義（.agent.md）はスコアが 28/35 未満のものに対して、
   @.github/agents/hr-evaluation.agent.md の改善フレームワークも参照しながら
   GitHub Copilot フォーマットの改善提案を作成する

3. Skills（SKILL.md）のフォーマットを検証し、
   name・description の YAML フロントマターが正しいか確認する。
   不備があれば修正案を作成する

4. 各エージェントに対応する Agent Skills（.github/skills/<エージェント名>/SKILL.md）を
   作成または改善する

5. .github/copilot-instructions.md にリポジトリ全体のベースラインルールを定義する
   （存在しない場合は新規作成、存在する場合はエージェントとの整合性を確認）

6. エージェント固有のパス向けインストラクション（.github/instructions/*.instructions.md）が
   必要な領域（Bicep、Terraform、Policy JSON 等）に対して作成する。
   applyTo glob パターンが正しく指定されているか確認する

7. 改善サイクルの評価プロンプトを .github/prompts/agent-review.prompt.md として保存する

8. 改善案を COPILOT_FORMAT_IMPROVEMENT.md として出力する

9. 改善内容を適用した上で PR を作成する

⚠️ 重要な注意事項:
- 既存エージェントの CAF 機能や専門性を損なわないように改善してください
- フォーマット面の改善のみを行い、エージェントの役割・指示内容は維持してください
- Skills の SKILL.md は .github/skills/<スキル名>/ サブディレクトリに配置してください
- SKILL.md には必ず name と description の YAML フロントマターを含めてください
- copilot-instructions.md のベースラインと各エージェントの指示が矛盾しないよう注意してください
- .instructions.md には必ず applyTo glob パターンを指定してください
"

改善前後の比較ポイント

/delegate によって生成された改善後のエージェントでは、以下の点が改善されます。

1. description の改善（トリガーキーワードの追加）

1
2
3
4
5
6
7

# ❌ 改善前
description: "Azure ガバナンスとコンプライアンスの専門チーム"

# ✅ 改善後
description: "Azure ガバナンスとコンプライアンスの専門チーム。
  Azure Policy の設計・適用、リスク管理、コンプライアンス監視に使用する。
  キーワード: policy, governance, compliance, リスク管理, ポリシー"

2. tools の最小権限化

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

# ❌ 改善前（execute が不要）
tools:
  - read
  - search
  - edit
  - execute    # ← ガバナンス評価に execute は不要
  - agent
  - web

# ✅ 改善後（必要なツールのみ）
tools:
  - read
  - search
  - edit       # IaC ファイルの生成のため必要
  - agent      # 他のエージェントと連携するため必要
  - web        # 最新の Azure Policy ドキュメント参照のため必要

3. バウンダリ（DO/DON’T）セクションの追加

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

## ⚠️ このエージェントの制約

### やること（DO）
- Azure Policy の設計と提案
- コンプライアンス状況の分析レポート
- ガバナンス改善の提案書作成

### やってはいけないこと（DON'T）
- 本番環境の Azure リソースへの直接変更（提案のみ）
- `.env` や Secrets ファイルの内容をログに出力
- クラウド戦略チームの権限範囲（予算承認・ビジネス目標策定）への介入
- 同一エージェントの再帰的呼び出し（無限ループ防止）

4. 具体例セクションの追加

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

## 💬 使用例

### 入力例
```
現在の .github/policies/ ディレクトリ内の Azure Policy 定義を読み込んで、
CAF ガバナンスの観点から不足しているポリシーを提案してください。
```

### 期待する出力例
```
## ガバナンス評価レポート

### 現状のポリシーカバレッジ
| カテゴリ | 現状 | 推奨 | ギャップ |
|:---|:---:|:---:|:---|
| タグ管理 | 3 件 | 5 件 | Environment, CostCenter タグが未定義 |
...
```

まとめ

得られた知見

• フォーマットの正確さは動作安定性に直結する: mcp-servers のオブジェクト形式や description のキーワード設計など、細かいフォーマットの差が動作の安定性に大きく影響します。これは .agent.md だけでなく SKILL.md や .instructions.md にも同様に当てはまります。

• レビューは .agent.md だけでは不十分: SKILL.md の YAML フロントマターの欠落や、copilot-instructions.md とエージェントのルール矛盾など、カスタマイズファイル全体を横断的にチェックしないと見落としが生まれます。copilot-expert をすべてのファイルタイプに対応させたことで、この問題を解決しました。

• Agent Skills はエージェントの「手順知識」を分離できる: .agent.md にすべての手順を詰め込むのではなく、再利用可能な手順は SKILL.md に分離することで、エージェントのコンテキストウィンドウを節約しつつ専門知識を提供できます。

• Custom Instructions でベースラインを統一する: copilot-instructions.md を使うと、命名規則やセキュリティルールなどの共通ルールを全エージェントに一括適用でき、各 .agent.md への重複記述を排除できます。

• Prompt Files で改善サイクルを再現可能にする: 評価プロンプトを .prompt.md としてテンプレート化することで、誰が実行しても同じ品質基準で評価・改善できるワークフローが構築できます。

• /compact と /context でコンテキスト管理を意識する: 複数エージェントを横断的に評価する長いセッションでは、トークン上限を意識したコンテキスト管理が安定動作の鍵になります。

• ガードレール設計は「ツール制限 + 明示的禁止事項」の 2 層が効果的: YAML フロントマターでのツール最小化だけでは不十分で、本文への禁止事項の明記を組み合わせることで初めて実効性のあるガードレールになります。

• 評価エージェント自体がベストプラクティスの体現になる: Copilot エキスパートエージェントを「自分自身がベストプラクティスに準拠した設計」で作ることで、評価の説得力が増し、実際の改善例としても機能します。

• 2 つの評価軸（技術的・ビジネス的）を組み合わせるとより効果的: Copilot エキスパートエージェント（技術的フォーマット）と人事評価エージェント（ビジネス要件）の両方で評価することで、エージェントの品質を多角的に担保できます。

• /delegate は改善サイクルの自動化に強力: 評価→改善提案→PR 作成の一連のサイクルを無人実行できるため、定期的なエージェント品質管理にも活用できます。

注意点

• 改善提案はあくまでも提案: Copilot エキスパートエージェントや /delegate が生成した改善案は、必ず人間がレビューしてから適用してください。特に既存エージェントの役割・専門性に関わる変更は慎重に判断してください。
• 公式ドキュメントの更新に追従する: GitHub Copilot CLI のカスタムエージェント仕様は更新される可能性があります。定期的に公式ドキュメントを確認し、エージェントの評価基準も見直してください。
• ガードレールは完璧ではない: 今回紹介したガードレール設計は多くのリスクを低減しますが、完全な保証ではありません。重要な操作の前には常に人間による確認を挟んでください。

今後の展望

今回の改善サイクルを経て、CAF エージェントチームは技術的・ビジネス的の両面で高い品質を達成しました。次のステップとして:

1. Azure Landing Zone の Bicep/Terraform 作成: 改善されたエージェントチームを使って、実際の Landing Zone IaC の生成に挑戦
2. エージェントの定期的な品質チェックの自動化: GitHub Actions と組み合わせて、PR ごとにエージェントのフォーマットチェックを実施
3. エージェント評価基準のバージョン管理: Copilot エキスパートエージェントの評価基準をバージョン管理し、変更履歴を追跡
4. Agent Skills のライブラリ化: CAF 共通の手順スキルを整備し、組織全体で共有できる Skills リポジトリを構築

参考

• カスタム エージェントの作成 - GitHub Docs
• Agent Skills の作成 - GitHub Docs
• Custom Instructions の追加 - GitHub Docs
• カスタム エージェントの設定リファレンス - GitHub Docs
• GitHub Copilot CLI ベストプラクティス - GitHub Docs
• GitHub Copilot CLI コマンドリファレンス - GitHub Docs
• Azure CAF の組織論に基づいたエージェントを作成し隊（前回の記事）
• 組織の連携を管理する - Cloud Adoption Framework | Microsoft Learn