Agent Development

Agent Development for Copilot CLI Plugins

Create autonomous agents (.agent.md) that handle complex, multi-step tasks independently. Define structure, triggering conditions, and system prompts.

• Agents are FOR autonomous work, skills are FOR user-initiated actions
• Markdown file format with YAML frontmatter
• Triggering via description field
• System prompt defines agent behavior
• Model customization

Agent File Structure

Complete Format

---
description: Use this agent when [triggering conditions].
model: claude-sonnet-4.5
tools: [read, edit, grep]
---

You are [agent role description]...

**Your Core Responsibilities:**
1. [Responsibility 1]
2. [Responsibility 2]

**Analysis Process:**
[Step-by-step workflow]

**Output Format:**
[What to return]

Frontmatter Fields

description (required)

Defines when Copilot should trigger this agent. This is the most critical field.

Must include:

1. Triggering conditions ("Use this agent when...")
2. Context describing when agent is appropriate

Format:

Use this agent when [conditions].

Best practices:

• Be specific about triggering conditions
• Cover different phrasings of same intent
• Be specific about when NOT to use the agent

model (optional)

Which model the agent should use.

Options:

• claude-sonnet-4.5 - Claude Sonnet (balanced, default)
• claude-opus-4.5 - Claude Opus (most capable, expensive)
• claude-haiku-4.5 - Claude Haiku (fast, cheap)

Recommendation: Omit unless agent needs specific model capabilities. Defaults to session model.

tools (optional)

Restrict agent to specific tools.

Format: Array of tool names (lowercase, unquoted)

tools: [read, edit, grep, powershell]

Default: If omitted, agent has access to all tools

Best practice: Limit tools to minimum needed (principle of least privilege)

Common tool sets:

• Read-only analysis: [read, grep, glob]
• Code generation: [read, edit, grep]
• Testing: [read, powershell, grep]
• Full access: Omit field