make-custom-agent

カスタムエージェントの作成

このスキルでは、GitHub Copilot にドメイン固有の専門知識を追加する、@ で呼び出せるチャット参加者であるカスタム GitHub Copilot エージェントの作成方法を説明します。カスタムエージェントは Agent Skills とは異なります。スキルは必要に応じて読み込まれる再利用可能な指示を提供する一方、エージェントは会話全体を担い、ツールを連携させたり、API を呼び出したり、独自のプロンプト戦略を維持したりできます。

使用しない場合

• 再利用可能で呼び出し可能なワークフローを追加する場合 — 代わりに Agent Skills（.agents/skills/）を使用してください
• バックグラウンドのコーディングガイドラインを追加する場合 — 代わりにファイルベースの指示（.github/instructions/）を使用してください
• Copilot にプロジェクト全体のコンテキストを追加する場合 — 代わりに .github/copilot-instructions.md を使用してください
• 再利用可能なプロンプトを作成する場合 — 代わりに .prompt.md を使用してください

ワークフロー

既存の提案を確認する場合は、ツールだけでなく定義全体を監査してください。説明では、そのエージェントを見つけるべき自然な依頼を明確にし、本文ではルート指示を超えるドメイン知識を追加し、対応する評価ではそのエージェントの貢献を切り分ける必要があります。すべてのツールと動作を、ユーザーが意図する権限と照らし合わせてください。コマンドを実行できないレビュー担当者が、ワイルドカードツール、ハンドオフ、またはその他の手段によって、コマンド実行や公開の権限を得てはなりません。ワークフローが読み取り専用である場合も同様です。

ステップ 1: エージェントの種類を選択する

種類	場所	最適な用途
宣言型（プロンプトファイル）	.github/agents/<name>.md	コードを必要としない、シンプルなプロンプト駆動型の複数サーフェス対応エージェント
拡張機能ベース（チャット参加者）	VS Code 拡張機能プロジェクト	完全な制御、ツール呼び出し、VS Code API へのアクセス
GitHub App（Copilot Extension）	ホスト型サービス + GitHub App	複数サーフェス対応エージェント（github.com、VS Code、Visual Studio）

スコープを限定したシステムプロンプトだけが必要で、カスタムコードを必要としない場合は、宣言型エージェントから始めてください。

ステップ 2: 宣言型エージェントを作成する（プロンプトファイル）

宣言型エージェントは .github/agents/ にある Markdown ファイルです。VS Code と GitHub Copilot はこれらを自動的に検出します。

.github/agents/
└── <agent-name>.md        # Agent definition

テンプレート：

---
name: my-agent
description: A short description of what this agent does and when to use it.
---

# <Agent Title>

You are an expert in <domain>. Your job is to:
- <behavior 1>
- <behavior 2>

## Guidelines

- <guideline 1>
- <guideline 2>

## Workflow

1. <step 1>
2. <step 2>

## Constraints

- <constraint 1>
- <constraint 2>

サポートされているフロントマターフィールド：

フィールド	必須	説明
name	はい	小文字を使用し、ハイフンを使用できます。@ メンションに使用されます。
description	はい	エージェントの機能と使用する状況です。参加者リストに表示されます。
target	いいえ	対象環境：vscode または github-copilot（既定では両方）
tools	いいえ	許可するツール／ツールセットのリスト
model	いいえ	LLM 名、または優先順位を付けたモデルの配列
user-invocable	いいえ	エージェントのドロップダウンに表示します（既定値：true）
disable-model-invocation	いいえ	サブエージェントによる呼び出しを禁止します（既定値：false）
mcp-servers	いいえ	GitHub Copilot ターゲット用の MCP サーバー設定
metadata	いいえ	任意の追加メタデータを指定するキーと値のマッピングです。
argument-hint	いいえ	ユーザーの操作を案内するヒントテキスト（VS Code のみ）
agents	いいえ	許可するサブエージェントのリスト（すべての場合は *、なしの場合は []、VS Code のみ）
handoffs	いいえ	次のステップとなるエージェントへの遷移リスト（VS Code のみ）

指示に関するヒント：

• 他のファイルを参照するには Markdown リンクを使用してください
• #tool:<tool-name> 構文でツールを参照してください
• エージェントの動作と制約を具体的に記述してください

ステップ 3: ツールを設定する

エージェントが使用できるツールを指定します。

tools:
  - search              # Built-in tool
  - fetch               # Built-in tool
  - codebase            # Tool set
  - myServer/*          # All tools from MCP server

一般的なツールパターン：

• 読み取り専用エージェント：['search', 'fetch', 'codebase']
• 編集機能を備えたエージェント：['*'] または特定の編集ツール
• 特化型エージェント：必要なツールを個別に選択

ステップ 4: ハンドオフを追加する（任意、VS Code のみ）

他のエージェントへの遷移を設定します。

handoffs:
  - label: Start Implementation
    agent: implementation
    prompt: Implement the plan outlined above.
    send: false
    model: GPT-5.2 (copilot)

ハンドオフのフィールド：

• label：ユーザーに表示するボタンのテキスト
• agent：遷移先エージェントの識別子
• prompt：遷移先エージェント用に事前入力するプロンプト
• send：プロンプトを自動送信します（既定値：false）
• model：ハンドオフで使用する任意のモデルの上書き設定

ステップ 5：拡張機能ベースのチャット参加者を作成する（VS Code のみ）

完全に制御するには、チャット参加者を備えた VS Code 拡張機能を実装します。

1. package.json で参加者を定義します：

"contributes": {
    "chatParticipants": [
        {
            "id": "my-extension.my-agent",
            "name": "my-agent",
            "fullName": "My Agent",
            "description": "Short description shown in chat input",
            "isSticky": false,
            "commands": [
                {
                    "name": "explain",
                    "description": "Explain the selected code"
                }
            ]
        }
    ]
}

2. extension.ts でリクエストハンドラーを登録して実装します：

export function activate(context: vscode.ExtensionContext) {
    const agent = vscode.chat.createChatParticipant('my-extension.my-agent', handler);
    agent.iconPath = vscode.Uri.joinPath(context.extensionUri, 'icon.png');
}

const handler: vscode.ChatRequestHandler = async (
    request: vscode.ChatRequest,
    context: vscode.ChatContext,
    stream: vscode.ChatResponseStream,
    token: vscode.CancellationToken
) => {
    const model = request.model;
    const messages = [
        vscode.LanguageModelChatMessage.User(request.prompt)
    ];
    const response = await model.sendRequest(messages, {}, token);
    for await (const fragment of response.text) {
        stream.markdown(fragment);
    }
};

3. package.json で拡張機能の依存関係を宣言します：

"extensionDependencies": ["github.copilot-chat"]

4. ツール呼び出しを追加する（任意）

エージェントは、他の拡張機能が登録した言語モデルのツールを呼び出すことができます：

const tools = vscode.lm.tools.filter(tool => tool.tags.includes('my-domain'));
const result = await chatUtils.sendChatParticipantRequest(request, context, {
    prompt: 'You are an expert in <domain>.',
    tools,
    responseStreamOptions: { stream, references: true, responseText: true }
}, token);
return await result.result;

ステップ 6：GitHub App（Copilot Extension）を作成し、複数のプラットフォームで利用可能にする（任意）

エージェントを GitHub.com、Visual Studio、JetBrains、VS Code で同時に利用できるようにするには、Copilot Extension として動作する GitHub App を実装します。このアプリは webhook エンドポイントを登録し、チャットリクエストを受信して、応答をストリーミングで返します。

主な考慮事項：

• GitHub App は、ユーザーのアカウントまたは組織にインストールされている必要があります
• 応答は Server-Sent Events（SSE）経由でストリーミングされます
• 完全な連携ガイドについては、GitHub Copilot Extensions のドキュメントを参照してください
• VS Code 固有の機能（エディターへのアクセス、ファイルツリー、コマンドボタン）には、拡張機能ベースの参加者を優先してください

ステップ 7：ハーネス評価を作成する

eng/harness-evaluation/agents/<agent-id>/eval.yaml を作成し、eng/harness-evaluation/README.md に従います。

• eval のルートにある agent_environment.files には、エージェントファイルのみを指定します。実験ではこれが control から削除されます。
• プロンプトに期待する診断や実装を明記せず、エージェント特有の動作を試す現実的な刺激を使用します。
• 決定論的な出力チェック、焦点を絞った意味的な評価基準、上限を設けたリソース、トークン採点、コミット済みのスコアしきい値を組み合わせます。
• eval 名とディレクトリから導出されるコンポーネント ID は、エージェント ID と同一にします。

ステップ 8：検証する

エージェントを作成または変更した後、次の点を確認します。

• name は小文字で、ハイフンを使用し（スペースは使わず）、一意である
• description には、エージェントの機能と呼び出すタイミングが明確に記載されている
• フロントマターの YAML が有効である（構文エラーがない）
• 宣言型エージェントのファイルが .github/agents/ にある
• ツール一覧には、利用可能なツールのみが含まれている
• 拡張機能ベースのエージェントの場合、参加者 ID が package.json と createChatParticipant の呼び出しで一致している
• エージェントが組み込みエージェント（@workspace、@vscode、@terminal）の機能と重複していない
• ハンドオフ先エージェント名が、既存のエージェントと一致している
• エージェントの指示にシークレット、トークン、内部 URL が含まれていない
• 対応するハーネス評価がこのエージェントのみを対象とし、処理群と対照群を有意に区別できるよう設計されている

よくある落とし穴

落とし穴	解決策
エージェント名が組み込みの参加者と競合する	一意のプレフィックス（ドメイン名）を使用します
説明が曖昧すぎる	ユーザーが自然に使う、具体的なキーワードを含めます
システムプロンプトが長すぎる	指示を必須の動作に絞り、参考資料は Agent Skills に移します
VS Code API が必要なのに、宣言型として作成している	拡張機能ベースの参加者に切り替えます
不必要に isSticky: true を使用している	エージェントを既定でターン間に維持する必要がある場合にのみ sticky を設定します
github.copilot-chat の extensionDependencies がない	追加します。追加しないと、貢献ポイントを利用できない場合があります
エージェントが予期せずサブエージェントとして呼び出される	disable-model-invocation: true を設定します
ドロップダウンにサブエージェントが表示される	user-invocable: false を設定します

参考資料

• VS Code Chat Participant API
• VS Code AI Extensibility Overview
• VS Code Extension Samples – chat-sample
• GitHub Copilot Extensions documentation
• GitHub Copilot Custom agents configuration
• Agent Skills Specification
• 関連リポジトリのスキル：make-skill と make-instructions