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

System Prompt Design

The markdown body becomes the agent's system prompt. Write in second person, addressing the agent directly.

Structure

Standard template:

You are [role] specializing in [domain].

**Your Core Responsibilities:**
1. [Primary responsibility]
2. [Secondary responsibility]
3. [Additional responsibilities...]

**Analysis Process:**
1. [Step one]
2. [Step two]
3. [Step three]
[...]

**Quality Standards:**
- [Standard 1]
- [Standard 2]

**Output Format:**
Provide results in this format:
- [What to include]
- [How to structure]

**Edge Cases:**
Handle these situations:
- [Edge case 1]: [How to handle]
- [Edge case 2]: [How to handle]

Best Practices

✅ DO:

• Write in second person ("You are...", "You will...")
• Be specific about responsibilities
• Provide step-by-step process
• Define output format
• Include quality standards
• Address edge cases
• Keep under 10,000 characters

❌ DON'T:

• Write in first person ("I am...", "I will...")
• Be vague or generic
• Omit process steps
• Leave output format undefined
• Skip quality guidance
• Ignore error cases

Creating Agents

Method 1: AI-Assisted Generation

Use this prompt pattern (extracted from Copilot CLI):

Create an agent configuration based on this request: "[YOUR DESCRIPTION]"

Requirements:
1. Extract core intent and responsibilities
2. Design expert persona for the domain
3. Create comprehensive system prompt with:
   - Clear behavioral boundaries
   - Specific methodologies
   - Edge case handling
   - Output format
4. Create identifier (lowercase, hyphens, 3-50 chars)
5. Write description with triggering conditions
6. Include 2-3 <example> blocks showing when to use

Return JSON with:
{
  "identifier": "agent-name",
  "whenToUse": "Use this agent when... Examples: <example>...</example>",
  "systemPrompt": "You are..."
}

Then convert to agent file format with frontmatter.

See examples/agent-creation-prompt.md for complete template.

Method 2: Manual Creation

1. Choose agent identifier (3-50 chars, lowercase, hyphens)
2. Write description with examples
3. Select model (usually omit for default)
4. Define tools (if restricting access)
5. Write system prompt with structure above
6. Save as agents/agent-name.agent.md

Validation Rules

Identifier Validation

✅ Valid: code-reviewer, test-gen, api-analyzer-v2
❌ Invalid: ag (too short), -start (starts with hyphen), my_agent (underscore)

Rules:

• 3-50 characters
• Lowercase letters, numbers, hyphens only
• Must start and end with alphanumeric
• No underscores, spaces, or special characters

Description Validation

Length: 10-5,000 characters Must include: Triggering conditions and examples Best: 200-1,000 characters with 2-4 examples

System Prompt Validation

Length: 20-10,000 characters Best: 500-3,000 characters Structure: Clear responsibilities, process, output format

Agent Organization

Plugin Agents Directory

plugin-name/
└── agents/
    ├── analyzer.agent.md
    ├── reviewer.agent.md
    └── generator.agent.md

All .agent.md files in agents/ are auto-discovered.

Namespacing

Agents are namespaced automatically:

• Single plugin: agent-name
• With subdirectories: plugin:subdir:agent-name

Testing Agents

Test Triggering

Create test scenarios to verify agent triggers correctly:

1. Write agent with specific triggering conditions
2. Use similar phrasing in test
3. Check Copilot loads the agent
4. Verify agent provides expected functionality

Test System Prompt

Ensure system prompt is complete:

1. Give agent typical task
2. Check it follows process steps
3. Verify output format is correct
4. Test edge cases mentioned in prompt
5. Confirm quality standards are met

Quick Reference

Minimal Agent

---
description: Use this agent when...
model: claude-sonnet-4.5
---

You are an agent that [does X].

Process:
1. [Step 1]
2. [Step 2]

Output: [What to provide]

Frontmatter Fields Summary

Field	Required	Format	Example
description	Yes	Text	Use when...
model	No	model name	claude-sonnet-4.5
tools	No	Array of tool names	[read, grep]

Best Practices

DO:

• ✅ Include concrete triggering conditions in description
• ✅ Write specific triggering conditions
• ✅ Omit model field unless specific need
• ✅ Choose appropriate tools (least privilege)
• ✅ Write clear, structured system prompts
• ✅ Test agent triggering thoroughly

DON'T:

• ❌ Use generic descriptions
• ❌ Omit triggering conditions
• ❌ Grant unnecessary tool access
• ❌ Write vague system prompts
• ❌ Skip testing

Additional Resources

Reference Files

For detailed guidance, consult:

• references/system-prompt-design.md - Complete system prompt patterns
• references/triggering-examples.md - Example formats and best practices
• references/agent-creation-system-prompt.md - The exact prompt from Copilot CLI

Example Files

Working examples in examples/:

• agent-creation-prompt.md - AI-assisted agent generation template
• complete-agent-examples.md - Full agent examples for different use cases

Utility Scripts

Development tools in scripts/:

• validate-agent.sh - Validate agent file structure
• test-agent-trigger.sh - Test if agent triggers correctly

Implementation Workflow

To create an agent for a plugin:

1. Define agent purpose and triggering conditions
2. Choose creation method (AI-assisted or manual)
3. Create agents/agent-name.agent.md file
4. Write frontmatter with required fields
5. Write system prompt following best practices
6. Include triggering conditions in description
7. Validate with scripts/validate-agent.sh
8. Test triggering with real scenarios
9. Document agent in plugin README

Focus on clear triggering conditions and comprehensive system prompts for autonomous operation.