Imported from grittygermz/hello-world (.github/skills/agent-file-specs/references/AGENTS.md). Install upstream with npx skills add grittygermz/hello-world --skill references. Copyright stays with the author.

Custom Agent Files (.agent.md)

Source: VS Code Custom Agents Documentation

Custom agents enable you to configure the AI to adopt different personas tailored to specific development roles and tasks. Each agent defines its own behavior, available tools, language model preferences, and can orchestrate multi-step workflows through handoffs.

Custom agents were previously known as "custom chat modes." If you have existing .chatmode.md files, rename them to .agent.md.

File Location

Additional locations can be configured with the chat.agentFilesLocations setting.

Provider note: <provider> is your provider's base folder (.github/, .claude/, .codex/, .config/opencode/). VS Code detects any .md file in .github/agents/ as a custom agent.

File Structure

User-Facing Agent

A standard interactive agent with a focused expertise area.

---
name: agent-name
description: Brief description shown as placeholder in chat input
user-invokable: true
argument-hint: Optional hint for user input
tools: ['tool1', 'tool2']
model: Claude Sonnet 4
disable-model-invocation: false
---

[Agent instructions body — Markdown content]

Orchestrator / Workflow Manager Agent

An orchestrator is a user-facing agent that manages a multi-step workflow by invoking sub-agents. It must include the agent tool to enable subagent invocation, and defines agents to control which sub-agents it can call. Handoffs present the user with transition buttons at the end of a response. Orchestrators do not edit code directly.

---
name: workflow-name
description: Brief description shown as placeholder in chat input
user-invokable: true
tools: ['tool1', 'tool2', 'agent']  # 'agent' tool required to invoke sub-agents
agents: ['*']  # '*' for all, '[]' for none, or a list of sub-agent names
model: Claude Sonnet 4
handoffs:
  - label: Button Text
    agent: target-agent
    prompt: Prompt to send
    send: false
    model: GPT-5 (copilot)
---

[Orchestrator instructions body — defines workflow order and sub-agent coordination]

Sub-Agent

Sub-agents must set user-invokable: false and must not include handoffs — handoffs are only rendered for user-facing agents. Sub-agents cannot communicate with the user directly; they return output (including any questions) to the orchestrator.

---
name: agent-name
description: Brief description of what this sub-agent does
user-invokable: false
tools: ['tool1', 'tool2']
model: Claude Sonnet 4
---

[Agent instructions body — scoped to this phase only; no handoffs, no user interaction]

Frontmatter Attributes

Naming Conventions

• Sub-agents must set user-invokable: false so they don't appear in the agent picker.
• Sub-agents must not include handoffs — handoff buttons are only rendered for user-facing agents, not sub-agents.
• Any .md file in the <provider>/agents/ folder is detected as a custom agent.

Handoff Configuration

Sub-agents must not define handoffs. Handoff buttons are only rendered for user-facing agents (user-invokable: true). Including handoffs in a sub-agent has no effect and should be omitted.

Handoffs create guided sequential workflows between agents. After a chat response completes, handoff buttons appear to let users transition to the next agent with relevant context.

Use Cases

• Planning → Implementation: Generate a plan, then hand off to start coding.
• Implementation → Review: Complete code, then switch to a review agent.
• Write Failing Tests → Implement: Generate tests first, then hand off to make them pass.

Syntax

handoffs:
  - label: "Display text for button"
    agent: "target-agent-name"
    prompt: "Prompt text to send to target agent"
    send: false
    model: "GPT-5 (copilot)"

Handoff Attributes

Body Content

The body contains Markdown-formatted instructions that define the agent's behavior. These instructions are prepended to the user's chat prompt whenever the agent is selected.

Capabilities

• Markdown formatting: Full Markdown including headers, lists, code blocks.
• File references: Link to other files with standard Markdown links (e.g., [standards](../instructions/react.instructions.md)).
• Tool references: Reference tools with #tool:<tool-name> syntax (e.g., #tool:githubRepo).
• Instruction reuse: Link to .instructions.md files to avoid duplicating guidelines.

Tool List Priority

When both a custom agent and a prompt file specify tools, the priority order is:

1. Tools specified in the prompt file (if any)
2. Tools from the referenced custom agent in the prompt file (if any)
3. Default tools for the selected agent (if any)

If a specified tool is not available, it is silently ignored.

Example: Planning Agent (user-facing)

---
name: planner
description: Generate an implementation plan for new features
tools: ['search', 'fetch', 'githubRepo', 'usages']
model: Claude Sonnet 4
handoffs:
  - label: Implement Plan
    agent: agent
    prompt: Implement the plan outlined above.
    send: false
---

# Planning Instructions

You are in planning mode. Generate implementation plans without making code
edits.

## Plan Structure

- **Overview:** Brief description of the feature
- **Requirements:** List of functional and non-functional requirements
- **Implementation Steps:** Detailed, actionable steps
- **Testing:** Required test cases and coverage

Example: Sub-Agent

---
name: due-diligence
user-invokable: false
description: Deep analysis of requirements and integration points
tools: ['search', 'fetch', 'usages']
---

# Due Diligence Analysis

You perform deep analysis on requirements before planning begins.
Identify integration points, dependencies, risks, and clarifications needed.

Sharing and Organization

• Workspace agents are stored in <provider>/agents/ and shared via version control.
• User profile agents are stored in the current VS Code profile and available across all workspaces.
• Organization agents are defined at the GitHub organization level and automatically detected when github.copilot.chat.organizationCustomAgents.enabled is set to true.
• Agents can be reused in background agents and cloud agents.

Diagnostics

If an agent isn't working as expected:

1. Select Configure Custom Agents from the agents dropdown.
2. Use the chat customization diagnostics view: right-click in the Chat view → Diagnostics.
3. Check for syntax errors, invalid configurations, or loading issues.