agent-writing

name	agent-writing
description	.agent.mdファイルを作成・編集する。frontmatter（tools, handoffs, model）の設計、エージェントの責務定義を支援。agent.md作成、.agent.md編集、.github/agents、カスタムエージェント、handoffs、tools、エージェント定義などの言及時に使用。
user-invokable	false

agent-writing

VS Code Copilot 用の .agent.md ファイルを作成・編集するためのガイド。特定の役割を持つカスタムエージェントを定義。

記述原則: 短く強く

Agent 定義は「役割」と「参照先」が中心。詳細はスキル側に。

• ユーザー内容をそのまま転記せず、意図を最小記述に圧縮
• 人間の読みやすさ < エージェントの機能性
• Agent 本体は薄く、詳細は excludeAgent で参照するスキルに
• 一般常識・推測可能な情報は省略

作成・編集後は必ず圧縮レビュー実施（Reviewer モード・圧縮レビュー実施中は除く）:

1. ファイル作成・編集完了
2. Reviewer サブエージェントに「短く強く」観点でレビュー依頼
3. 指摘に基づき圧縮実施
4. ユーザーに提示

ファイルパスのリンク化: スキル参照（「xxxスキルに基づいて行動する」等）は必ず [skill-name](path) でリンク化。詳細は copilot-instructions-maintenance

よくある致命的なミス

• ❌ tools を多く指定しすぎる

  • 意図しないアクションを実行するリスク
  • 必要最小限のツールのみ指定する

• ❌ 本文に詳細を書きすぎる

  • エージェント定義は薄く保つべき
  • 詳細なルールや知識は skill に分離

• ❌ name/description が曖昧

  • エージェント選択時に迷う
  • 役割を明確に1文で表現

• ✅ 正しいやり方

  • 1エージェント = 1つの役割
  • tools は必要最小限
  • 詳細は skill への参照で

frontmatter の書き方

---
name: Agent Name              # 任意: 表示名（省略時はファイル名）
description: エージェントの目的  # 推奨: 1文で役割を説明
argument-hint: 入力のヒント     # 任意: チャット入力欄のヒント
tools: ['search', 'fetch']    # 任意: 利用可能なツール
model: Claude Sonnet 4        # 任意: 使用するモデル
handoffs:                     # 任意: 次のエージェントへの遷移
  - label: Start Implementation
    agent: implementation
    prompt: Implement the plan.
    send: false
---

frontmatter フィールド一覧

フィールド	必須/任意	説明
name	任意	表示名（省略時はファイル名）
description	推奨	エージェントの目的（1文）
argument-hint	任意	チャット入力欄のヒント
tools	任意	利用可能なツール/ツールセット
model	任意	使用するモデル
infer	任意	サブエージェントとして使用可能か（デフォルト: true）
handoffs	任意	次のエージェントへの遷移定義

handoffs（ワークフロー遷移）

handoffs:
  - label: Start Implementation  # ボタンラベル
    agent: implementation        # 遷移先エージェント名
    prompt: Implement the plan.  # 遷移時のプロンプト
    send: false                  # 自動送信するか（デフォルト: false）

雛形作成

テンプレートからファイルを生成:

.agents/skills/99_agent-writing/scripts/init_agent.sh {agent-name}

生成先: .github/agents/{agent-name}.agent.md

ファイル名の付け方

プレフィックスなし（例: reviewer.agent.md）

詳細: プレフィックス命名規則

設計原則

1. エージェントは薄く保つ

   • 本文はスキルへの参照と出力契約が中心
   • 詳細なルールは skill に分離

2. 責務を明確に

   • 1エージェント = 1つの役割
   • 例: Reviewer, Planner, Debugger

3. ツールを絞る

   • 必要最小限の tools のみ指定
   • 読み取り専用エージェントなら編集ツールは除外

絶対守るルール

• ❌ Bad: エージェント本文にルールや知識を詰め込む

  • コンテキストが肥大化する
  • skill に分離すべき

• ❌ Bad: tools に全ツールを指定

  • 意図しないアクションのリスク

• ✅ Good: スキルへの参照を記述

  • 「詳細は {skill-name} スキルを参照」

• ✅ Good: 役割に必要な最小限の tools のみ

  • Plan エージェント: 読み取り専用ツールのみ

例

Plan エージェント（読み取り専用）

---
name: Plan
description: 実装計画を作成するエージェント
tools: ['search', 'fetch', 'githubRepo', 'usages']
handoffs:
  - label: Implement Plan
    agent: agent
    prompt: Implement the plan outlined above.
    send: false
---

Reviewer エージェント

---
name: Reviewer
description: コードレビューに特化したエージェント
tools: ['search', 'githubRepo']
---

参考資料

• VS Code Custom Agents 公式ドキュメント
• copilot-instructions-maintenance スキル

---

エージェントは薄く保ち、詳細は skill に分離。tools は必要最小限に絞る。