GitHub Copilot Agent Builder

Generate custom GitHub Copilot agents following VS Code's .agent.md format with proper YAML frontmatter and markdown instructions.

When to Activate

Trigger this skill when user says:

• "create copilot agent"
• "generate github copilot agent"
• "new copilot agent for [purpose]"
• "make a copilot agent"
• "build copilot agent"
• "copilot custom agent"

Agent Creation Process

Step 1: Gather Requirements

Ask user for agent configuration:

1. Agent Purpose & Name:

   • What should the agent do? (e.g., "plan features", "review security", "write tests")
   • Suggested name: Extract from purpose (e.g., "planner", "security-reviewer", "test-writer")

2. Tools Selection (multi-select):

   • fetch - Retrieve web content and documentation
   • search - Search codebase and files
   • githubRepo - Access GitHub repository data
   • usages - Find code references and usage patterns
   • files - File operations
   • Custom tools if available

3. Handoff Workflows (optional):

   • Should this agent hand off to another? (e.g., planner → coder)
   • Handoff agent name
   • Handoff prompt text
   • Auto-send handoff? (yes/no)

4. Additional Configuration (optional):

   • Specific model to use?
   • Argument hint for users?

Step 2: Validate Directory Structure

# Ensure .github/agents directory exists
mkdir -p .github/agents

Step 3: Generate Agent File

Create .github/agents/{agent-name}.agent.md with:

YAML Frontmatter Structure:

---
description: [Brief overview shown in chat input]
name: [Agent identifier, lowercase with hyphens]
tools: [Array of tool names]
handoffs:  # Optional
  - label: [Button text]
    agent: [Target agent name]
    prompt: [Handoff message]
    send: [true/false - auto-submit?]
model: [Optional - specific model name]
argument-hint: [Optional - user guidance text]
---

Markdown Body:

• Clear role definition
• Specific instructions
• Tool usage guidance (reference as #tool:toolname)
• Output format expectations
• Constraints and guidelines

Step 4: Validate Format

Ensure generated file has:

• ✓ Valid YAML frontmatter with --- delimiters
• ✓ All required fields (description, name)
• ✓ Tools array properly formatted
• ✓ Handoffs array if specified (with label, agent, prompt, send)
• ✓ Markdown instructions that are clear and actionable

Step 5: Confirm Creation

Show user:

✅ GitHub Copilot Agent Created

📁 Location: `.github/agents/{name}.agent.md`
🎯 Agent: {name}
📝 Description: {description}
🛠️  Tools: {tools list}

To use:
1. Reload VS Code window (Cmd/Ctrl + Shift + P → "Reload Window")
2. Open GitHub Copilot Chat
3. Type `@{name}` to invoke your custom agent

{If handoffs configured: "This agent can hand off to: {handoff targets}"}

Output Format

After creation, provide:

1. File path confirmation
2. Configuration summary (name, description, tools, handoffs)
3. Usage instructions (how to reload and use)
4. Next steps (testing suggestions)

Reference Documentation

• Templates and structures → templates.md
• Real-world examples → examples.md

Important Guidelines

1. Naming Convention: Use lowercase with hyphens (e.g., feature-planner, security-reviewer)
2. Description: Brief (1-2 sentences), shown in chat input UI
3. Tools: Only include tools the agent actually needs
4. Handoffs: Enable multi-step workflows (planning → implementation → testing)
5. Instructions: Be specific about what the agent should and shouldn't do
6. Tool References: Use #tool:toolname syntax in markdown body

Common Agent Patterns

Planning Agent:

• Tools: fetch, search, githubRepo, usages
• Handoff: To implementation agent
• Focus: Analysis and planning, no code edits

Implementation Agent:

• Tools: search, files, usages
• Handoff: To testing agent
• Focus: Write and modify code

Review Agent:

• Tools: search, githubRepo, usages
• Handoff: Back to implementation for fixes
• Focus: Quality, security, performance checks

Testing Agent:

• Tools: search, files
• Handoff: Back to implementation or to review
• Focus: Test creation and validation

---

Ready to build custom GitHub Copilot agents!