/agentic-workflow-guide

Agent & Prompt Template

Standard structure and specification for .agent.md and .prompt.md files.

Note: Both file types use similar YAML front matter. The mode: field is deprecated for both.

File Format Rules

⚠️ フェンスラッパーに関する重要な注意

.prompt.md と .instructions.md ファイルは 素の YAML フロントマター (---) で始めること。 コードフェンス（````prompt 等）で囲む必要はない。フェンスで囲むと VS Code がフロントマターを認識できず、プロンプトピッカーに description が表示されなくなる。

# ✅ .prompt.md — 正しい
---
description: セッション内容をXポスト用に変換
---
# プロンプト本文...

# ❌ .prompt.md — 間違い（description が表示されない）
````prompt
---
description: セッション内容をXポスト用に変換
---
# プロンプト本文...

✅ .agent.md — 正しい（フェンス不要、素の --- だけ）

---
name: my-agent
description: Does something useful
---
# エージェント本文...

## YAML Front Matter

### For `.agent.md` files

```yaml
---
name: <agent-name> # Required: Identifier for @mention
description: <description> # Required: One-line role description
model: <model-name> # Optional: LLM model to use
tools: [...] # Optional: Tool whitelist
agents: [...] # Optional: Restrict which subagents may be invoked
handoffs: [...] # Optional: Agent transitions (must be objects with label/agent/prompt/send)
user-invocable: true # Optional: Show in agents dropdown (default: true)
disable-model-invocation: false # Optional: Prevent subagent invocation (default: false)
---

Model note: In VS Code, subagents inherit the parent's model unless .agent.md sets model: or the caller specifies one (highest priority). A requested model cannot exceed the parent's cost tier. Use only exact names verified locally. VS Code Docs

When fallback matters, model: can be an ordered array and the first available model is used. Use only model display names verified in the current environment.

model: ["<verified-model-name-1>", "<verified-model-name-2>"]

handoffs は文字列配列ではなく、label・agent・prompt・send を持つオブジェクト配列で定義する。

agents は親 agent が呼び出せる subagent 名の制限。省略すると全許可、[] なら subagent 呼び出し禁止。

⚠️ 非標準フィールド禁止（バリデーションエラーの原因）

author, repository, license, copyright 等のメタデータを YAML frontmatter に書くと バリデーションエラー になる。 これらは YAML の外、--- 終端の直後に HTMLコメント として記述すること。

# ✅ 正しい — メタデータはHTMLコメント
---
name: my-agent
description: Does something useful
---

<!-- author: aktsmm
     repository: https://github.com/aktsmm/ghc_template
     license: CC BY-NC-SA 4.0
     copyright: Copyright (c) 2025 aktsmm -->

# エージェント本文...

# ❌ 間違い — YAMLに非標準フィールドを追加
---
author: aktsmm        ← バリデーションエラー
repository: https://...
name: my-agent
---

For .prompt.md files

---
description: <description> # Required: Brief description of the prompt
# agent: <agent-name> # Optional: Bind to a specific agent
---

Do not add tools: to .prompt.md by default. Prompt-level tools: is an allowlist that overrides the selected or referenced agent's tools for that prompt run. Use it only when losing unrelated built-in, extension, web, or MCP tools is intentional.

⚠️ Deprecated Fields

infer: Migration Guide:

infer: true (default) はプルダウン表示とサブエージェント呼び出しの両方を制御していたが、新しいフィールドでは独立制御が可能。

# ❌ Wrong (deprecated)
---
infer: false
---
# ✅ Correct: プルダウンに非表示（サブエージェントとしては呼び出し可能）
---
user-invocable: false
---
# ✅ Correct: サブエージェント呼び出しを禁止（プルダウンには表示）
---
disable-model-invocation: true
---
# ✅ Correct: 両方禁止
---
user-invocable: false
disable-model-invocation: true
---

⚠️ typo注意: user-invokable は誤記で無効。ピッカー非表示には必ず user-invocable: false を使うこと。

⚠️ サブディレクトリの罠（2026年2月時点）: .github/agents/ は直下のファイルだけをスキャン。 サブフォルダに入れると runSubagent でも呼び出せなくなる。フラットに置くこと。 非表示にしたい場合はサブフォルダではなく user-invocable: false を使うこと。

Manifest Validation Checklist

複数の .agent.md をまとめて編集したら、最低限次を確認すること。

• user-invokable などの誤記が front matter に混入していない
• user-invocable: false の agent が意図どおり subagent 専用になっている
• front matter 編集後も本文先頭の ## Role など必須セクションが崩れていない

mode: Migration Guide:

# ❌ Wrong (deprecated)
---
mode: agent
---
# ✅ Correct: Specify agent name
---
description: Daily report generator
agent: report-generator
---
# ✅ Correct: Boolean value
---
description: Daily report generator
agent: true
---
# ✅ Correct: Omit (default behavior)
---
description: Daily report generator
---

agent: Field Options:

Complete .prompt.md Example

---
description: デイリーレポート自動生成（業務ログから1日分のレポートを作成）
agent: report-generator
---

Tools Pattern Reference:

Common Tool Categories:

✅ Correct

name: my-agent description: Does something useful

### Tools Field Behavior

| Specification | Behavior                                   |
| ------------- | ------------------------------------------ |
| **Omitted**   | All tools available (recommended for most) |
| `tools: []`   | No tools available                         |
| Tool names    | Only listed tools available (whitelist)    |

> **Note**: MCP server tools become available at runtime automatically. Unknown tool names cause errors.

### Recommended `tools:` style for `.agent.md`

For custom agents, prefer the stable aliases below unless you specifically need a narrower tool path.

```yaml
tools: [read, search]
tools: [read, search, edit]
tools: [agent, read, search]
```

Use these aliases first:

| Purpose | Preferred alias |
| ------- | --------------- |
| Read    | `read`          |
| Search  | `search`        |
| Edit    | `edit`          |
| Shell   | `execute`       |
| Web     | `web`           |
| Subagent| `agent`         |
| Todo    | `todo`          |

Avoid raw runtime tool IDs in `.agent.md` frontmatter. Names such as `read_file`, `grep_search`, and `semantic_search` are chat/runtime tool identifiers, not portable custom-agent tool names, and they trigger validation errors.

Body から特定ツールを明示したい場合は `#tool:<name>` 参照を使う。

```markdown
Use #tool:agent for each independent file review.
Use #tool:web when external documentation is required.
```

> **⚠️ Orchestrator の tools 制限に注意**: 親エージェントの `tools:` はサブエージェントの **ツール上限（ceiling）** として機能する。Orchestrator の `tools:` から `edit` を外すと、サブエージェント（Writer 等）も `edit` を使えなくなる。Orchestrator は `tools:` を省略する（= 全ツール利用可）のが推奨。SRP の強制は `tools:` ではなくプロンプト内の MANDATORY 指示で行うこと。詳細は [agent-guide.md の Pitfall 7](agent-guide.md#pitfall-7-restricting-orchestrators-tools-breaks-sub-agents) を参照。

### ⚠️ tools フィールドの注意事項

**ツール名は `category/toolName` 形式で指定すること。** カテゴリが間違っていると VS Code がエラーを出す。

| ツール | ✅ 正しい指定 | ❌ 間違い | 備考 |
|--------|------------|---------|------|
| シェル実行 | `execute/runInTerminal` | `run/runInTerminal` | カテゴリは `execute` |
| ファイル読み | `read/readFile` | `readFile` | カテゴリ必須 |
| ファイル編集 | `edit/editFiles` | `editFiles` | カテゴリ必須 |
| テキスト検索 | `search/textSearch` | `textSearch` | カテゴリ必須 |
| ファイル検索 | `search/fileSearch` | `fileSearch` | カテゴリ必須 |
| Web フェッチ | `web/fetch` | `fetch` | カテゴリ必須 |
| サブエージェント | `agent` | `runSubagent` | カテゴリなし |
| タスク管理 | `todo` | `todos` | カテゴリなし |

**`tools:` に登録できないもの（チャット変数としてのみ利用可）:**
- `problems` / `changes` / `usages` / `codebase` / `githubRepo` → `#problems` 等でチャット内参照は可能だが、`tools:` ホワイトリストには登録不可

## Agent Body Structure

## Built-in Aligned Minimal Template

If you do not need the full structured template, start from this smaller built-in aligned shape and expand only when required.

```markdown
---
description: "Use when... trigger phrases for subagent discovery"
tools: [read, search]
user-invocable: false
---
You are a specialist at {specific task}. Your job is to {clear purpose}.

## Constraints
- DO NOT {thing this agent should never do}
- DO NOT {another restriction}
- ONLY {the core responsibility}

## Approach
1. {Step one}
2. {Step two}
3. {Step three}

## Output Format
{Exactly what this agent should return}
```

Use the minimal template when:

- the agent is single-purpose
- tool boundaries matter more than rich documentation
- the return format is more important than a long workflow narrative

Use the full template below when you need explicit I/O contracts, progress reporting, or error handling tables.

Each agent should include these sections:

| Section                | Required    | Description                                           |
| ---------------------- | ----------- | ----------------------------------------------------- |
| **Role**               | ✅          | Single sentence defining responsibility               |
| **Goals**              | ✅          | List of objectives to achieve                         |
| **Done Criteria**      | ✅          | Verifiable completion conditions (**one place only**) |
| **Permissions**        | ✅          | What's allowed and forbidden                          |
| **I/O Contract**       | ✅          | Input/output definitions                              |
| **Non-Goals**          | Recommended | What this agent explicitly does NOT do                |
| **Workflow**           | Recommended | Step-by-step procedure                                |
| **Progress Reporting** | Recommended | How to report progress (e.g., `manage_todo_list`)     |
| **Error Handling**     | Recommended | Error patterns and responses                          |
| **Idempotency**        | Recommended | How to guarantee safe retries                         |

### ⚠️ Critical: Done Criteria Placement

**Define Done Criteria in exactly ONE place.** Multiple definitions cause confusion.

## Full Template

````markdown
---
name: example-agent
description: Brief description of what this agent does
tools: [read, edit, search]
---

# Example Agent

## Role

[Single sentence defining this agent's responsibility]

## Goals

- Goal 1: [Specific, measurable objective]
- Goal 2: [Another objective]
- Goal 3: [...]

## Done Criteria

Task is complete when ALL of the following are true:

- [ ] Criterion 1 (verifiable condition)
- [ ] Criterion 2 (verifiable condition)
- [ ] Criterion 3 (verifiable condition)

## Permissions

### Allowed

- Action 1
- Action 2

### Forbidden

- ❌ Action that should never be done
- ❌ Another prohibited action

## Non-Goals

Explicitly define what this agent does NOT do:

- ❌ Do not write code directly (delegate to implementation agent)
- ❌ Do not review own output (delegate to review agent)
- ❌ Do not assume user intent (ask for clarification)

> **Why Non-Goals?** Prevents orchestrators from doing work they should delegate.

## I/O Contract

### Input

| Field       | Type   | Required | Description          |
| ----------- | ------ | -------- | -------------------- |
| input_field | string | Yes      | Description of input |

### Output

| Field        | Type   | Description           |
| ------------ | ------ | --------------------- |
| output_field | string | Description of output |

## Workflow

1. **Step 1**: [Action description]
   - Details or sub-steps
2. **Step 2**: [Action description]
3. **Step 3**: [Action description]

## Error Handling

| Error Pattern        | Response                           |
| -------------------- | ---------------------------------- |
| File not found       | Report error, suggest alternatives |
| Invalid input format | Validate early, return clear error |
| External API failure | Retry with backoff, then escalate  |

## Progress Reporting

For long-running tasks, maintain visibility:

- Use `manage_todo_list` tool to track task status
- Update status at each sub-task completion
- Provide intermediate reports for tasks > 5 minutes

```markdown
**Progress:**

- [x] Task 1: Analyze requirements
- [x] Task 2: Generate IR
- [ ] Task 3: Validate output

## Idempotency

- Check current state before making changes
- Use unique identifiers to prevent duplicates
- Design operations to be safely retried

Examples by Role

→ See design-principles.md for detailed design principles.

Orchestrator Agent

VS Code Copilot:

---
name: orchestrator
description: Coordinates workflow and delegates to specialist agents
# Omit tools for orchestrators unless a hard allowlist is intentional.
# Parent tool allowlists become ceilings for worker agents.
---

Claude Code:

---
name: orchestrator
description: Coordinates workflow and delegates to specialist agents
tools: ["Task", "Read", "Search", "TodoWrite"]
---

Key characteristics:

• Uses subagent tool for delegation (#tool:agent / Task)
• Maintains high-level view
• Does NOT perform detailed work itself

Available Tools

Built-in tools for custom agents. Tool names differ by platform:

VS Code Copilot Tools (Official)

Claude Code Tools (Anthropic)

Cross-Platform Mapping

Tool Definition Examples

VS Code Copilot:

---
name: orchestrator
description: Coordinates workflow and delegates to specialist agents
# Omit tools for orchestrators unless a hard allowlist is intentional.
# Parent tool allowlists become ceilings for worker agents.
---

Claude Code:

---
name: orchestrator
description: Coordinates workflow and delegates to specialist agents
tools: ["Task", "Read", "Search", "TodoWrite"]
---

Tool Reference Syntax

• VS Code Copilot: Use #tool:<tool-name> in prompts (e.g., #tool:agent)
• Claude Code: Reference tools directly by name

MCP Server Tools

Use <server-name>/* format to include all tools from an MCP server.

Troubleshooting: If tools are not recognized:

• VS Code: Check VS Code Chat Tools Reference
• Claude Code: Check Custom Agents Configuration - GitHub Docs

Handoffs (Agent Transitions)

Handoffs enable guided sequential workflows between agents with suggested next steps.

When to Use

• Plan → Implementation: Generate plan, then hand off to implementation agent
• Implementation → Review: Complete coding, then switch to code review agent
• Write Failing Tests → Pass Tests: Generate failing tests first, then implement code

Configuration

---
name: Planner
description: Generate an implementation plan
tools: [search, web, read]
handoffs:
  - label: Start Implementation
    agent: implementation
    prompt: Implement the plan outlined above.
    send: false
---

Benefits

• Human control: User reviews each phase before proceeding
• Context preservation: Relevant context passed via prompt
• Workflow orchestration: Multi-step tasks with clear boundaries

References

• Custom Agents in VS Code
• Custom Agents Configuration - GitHub Docs