agent-customization

エージェントのカスタマイズ

判断フロー

プリミティブ	使用する場面
ワークスペースの指示	常時適用し、プロジェクト全体に適用する場合
ファイルの指示	applyTo パターンで明示的に適用する場合、または description によって必要に応じて適用する場合
MCP	外部システム、API、またはデータと連携する場合
フック	エージェントのライフサイクルのタイミングで決定的なシェルコマンドを実行する場合（ツールのブロック、自動フォーマット、コンテキストの挿入）
カスタムエージェント	コンテキストを分離するサブエージェント、またはツールを制限した複数段階のワークフロー
プロンプト	パラメーター化された入力を使用する、単一の明確なタスク
スキル	アセット（スクリプト／テンプレート）をまとめた、必要に応じて実行するワークフロー

クイックリファレンス

テンプレート、ドメイン別の例、高度なフロントマターオプション、アセットの整理、アンチパターン、作成チェックリストについては、リファレンスドキュメントを参照してください。リファレンスだけでは不十分な場合は、各プリミティブの公式ドキュメントへのリンクを確認してください。

種類	ファイル	場所	リファレンス
ワークスペースの指示	copilot-instructions.md、AGENTS.md	.github/ またはルート	リンク
ファイルの指示	*.instructions.md	.github/instructions/	リンク
プロンプト	*.prompt.md	.github/prompts/	リンク
フック	*.json	.github/hooks/	リンク
カスタムエージェント	*.agent.md	.github/agents/	リンク
スキル	SKILL.md	.github/skills/<name>/、.agents/skills/<name>/、.claude/skills/<name>/	リンク

ユーザーレベル：{{VSCODE_USER_PROMPTS_FOLDER}}/ (.prompt.md、.instructions.md、*.agent.md。スキルを除く) カスタマイズは、ユーザーの設定同期とともにローミングします。

作成プロセス

コードベース内のパターンを調査または検証する必要がある場合は、読み取り専用のサブエージェントを使用してください。質問ツールを利用できる場合は、ユーザーに質問して要件を明確にしてください。

カスタマイズファイルを作成する際は、次の手順に従ってください。

1. 適用範囲を決める

カスタマイズの配置先をユーザーに確認します。

• ワークスペース：プロジェクト固有で、チームと共有するカスタマイズの場合 → .github/ フォルダー
• ユーザープロファイル：個人用で、複数のワークスペースに適用するカスタマイズの場合 → {{VSCODE_USER_PROMPTS_FOLDER}}/

2. 適切なプリミティブを選ぶ

ユーザーのニーズに基づいて、上記の判断フローから適切なファイルの種類を選択します。

3. ファイルを作成する

適切なパスにファイルを直接作成します。

• 各リファレンスファイルの場所の表を使用します
• 必要に応じて必須のフロントマターを含めます
• テンプレートに従って本文を追加します

4. 検証する

作成後、次の点を確認します。

• ファイルが正しい場所にあること
• フロントマターの構文（--- マーカーで囲まれた YAML）が正しいこと
• description が含まれており、内容が明確であること

例外的なケース

指示とスキルのどちらを使うべきですか？ これは「ほとんどの」作業に適用されますか、それとも「特定の」タスクに適用されますか？ほとんどの作業 → 指示。特定のタスク → スキル。

スキルとプロンプトのどちらを使うべきですか？ どちらもチャットでスラッシュコマンド（/ を入力）として表示されます。アセットを含む複数ステップのワークフロー → スキル。入力を伴う単一の明確なタスク → プロンプト。

スキルとカスタムエージェントのどちらを使うべきですか？ すべてのステップで同じ機能を使う場合 → スキル。コンテキストを分離する必要がある場合（サブエージェントが単一の出力を返す）、または段階ごとに異なるツール制限が必要な場合 → カスタムエージェント。

フックと指示のどちらを使うべきですか？ 指示はエージェントの動作を「導きます」（非決定的）。フックは PreToolUse や PostToolUse などのライフサイクルイベントでシェルコマンドを実行し、動作を「強制します」。操作をブロックしたり、承認を求めたり、決定的にフォーマッターを実行したりできます。フックのリファレンスを参照してください。

よくある落とし穴

説明文が発見の手がかりになります。 エージェントは description フィールドをもとに、スキル、指示、エージェントを読み込むかどうかを判断します。トリガーフレーズが説明文に含まれていないと、エージェントはそれを見つけられません。具体的なキーワードを含め、「Use when...」のパターンを使ってください。

YAML フロントマターのサイレントな失敗。 値に含まれるエスケープされていないコロン、スペースの代わりに使われたタブ、フォルダー名と一致しない name は、いずれもエラーメッセージなしでサイレントに失敗する原因になります。コロンを含む説明文は、必ず引用符で囲んでください。例：description: "Use when: doing X"。

applyTo: "**" はコンテキストを消費します。 これは「すべてのファイルリクエストで常に含める」という意味です。関連性がない場合でも、やり取りのたびに指示がコンテキストウィンドウに読み込まれます。指示が本当にすべてのファイルに適用される場合を除き、具体的な glob（**/*.py、src/api/**）を使ってください。