Instruction file imported from chrisreddington/flight-school (.github/instructions/custom-agents.instructions.md). Copyright stays with the author.

Creating GitHub Copilot Custom Agents

Guidelines for creating agent files in .github/agents/ that define behavioral expertise, workflows, and specializations.

Key Concepts

Agents are behavioural specialists. They define HOW to work, not WHAT conventions to follow:

┌─────────────────────────────────────────────────────────────────┐
│  Instructions (*.instructions.md)                               │
│    ← Auto-injected based on applyTo patterns                    │
│    ← Contains: Coding standards, patterns, file conventions     │
│    ← DO NOT DUPLICATE THIS IN AGENTS                            │
├─────────────────────────────────────────────────────────────────┤
│  Agent (*.agent.md) ← YOU ARE HERE                              │
│    ← Selected from agents dropdown or via prompt file `agent:`  │
│    ← Contains: Workflow, expertise, personality, handoffs       │
│    ← Injected as <modeInstructions> in the prompt               │
├─────────────────────────────────────────────────────────────────┤
│  Prompt (*.prompt.md)                                           │
│    ← Triggered via /command                                     │
│    ← Contains: Task description, variables, agent selection     │
└─────────────────────────────────────────────────────────────────┘

What Belongs in Agents (vs Other Files)

Core Agent Patterns

Rules and Guidelines

Mandated Agent File Structure (Required Ordering)

Agent files MUST follow this section order:

Manager-Specific Sections (Lessons Learned)

Manager agents orchestrating multi-step workflows benefit from these additional sections:

Why these matter:

• Configuration: Makes agent behavior predictable and tunable
• Domain framework: Provides consistent criteria across sessions
• Evaluation criteria: Prevents infinite loops, clarifies "done"
• Invocation templates: Ensures specialists return usable, structured data

Frontmatter Properties

XML Tag Structure

Tool Configuration

Tool Design Best Practices:

• Keep tool count small — aim for fewer than 20 functions
• Make tools obvious and intuitive — principle of least surprise
• Use enums and object structure — make invalid states unrepresentable

Agent Specialization

Prefer specialized agents that excel at one task over general-purpose agents.

Specialist Invocation Rules

Handoff Contracts

Model Selection Guidance

Task Selection

Good Tasks for Agents:

• Fix bugs with clear reproduction steps
• Alter user interface features
• Implement well-defined features with clear specs

Handle Manually:

• Complex cross-repository refactoring
• Production issues, security, PII
• Ambiguous or open-ended exploration
• Tasks where you want deeper understanding

Design Principles

1. Maintain simplicity in your agent's design
2. Prioritise transparency by showing planning steps
3. Allow agents to introspect and improve
4. Have specialised agents that excel at one task
5. Use explicit checkpoints in workflows for resumability
6. Define iteration limits to prevent infinite loops (typically 3)
7. Provide exact delegation templates for specialist invocations

Checkpoint-Based Workflows (CRITICAL for Managers)

Manager agents should use explicit checkpoints to enable:

• Session resumption after interruption
• Handoffs to other agents mid-workflow
• Clear progress tracking for users

Checkpoint Pattern:

## Phase N: {Name}
1. **CHECKPOINT**: Update Resumption Section with current phase
2. Perform work step
3. **CHECKPOINT**: Write results to plan BEFORE proceeding
4. Verify results
5. **CHECKPOINT**: Update iteration count, move to next phase

Resumption Section Must Track:

• Current phase and step
• Last completed action (specific)
• Next action (specific)
• Iteration counts per specialist
• Files/items processed (N of M)

Size and Conciseness (CRITICAL)

Research-backed limits:

What to cut:

Contradictions waste reasoning tokens:

• GPT-5/Claude spend tokens trying to reconcile conflicts
• Review for conflicting instructions before finalizing
• Use the "intern test": Can someone follow this without asking clarifying questions?

Examples

Basic Agent File Structure

---
name: Agent Name
description: Brief description shown in chat
model: Claude Sonnet 4.5 (copilot)
tools: ['tool1', 'tool2']
---

# Agent Instructions

Your prompt and behavioural instructions.

Tool Configuration Examples

# Read-only agent
tools: ['search', 'fetch', 'read', 'usages', 'problems', 'changes']

# Full implementation agent
tools: ['search', 'read', 'edit', 'run', 'fetch']

Handoff Configuration

handoffs:
  - label: Start Implementation
    agent: agent
    prompt: Implement the plan above.
    send: false  # Require user confirmation

Complete Agent Template

---
name: Agent Name
description: Brief description shown in chat participant picker
model: Claude Sonnet 4.5 (copilot)
tools: ['tool1', 'tool2']
handoffs:
  - label: Handoff Label
    agent: target-agent
    prompt: Context for handoff
    send: false
infer: true
---

# Agent Name

<role_boundaries>
## What You DO:
- Primary responsibility 1
- Primary responsibility 2

## What You DON'T Do:
- Anti-responsibility 1 (with reason)
- Redefine coding standards (handled by instruction files)
- Tasks outside your specialisation (delegate to appropriate agent)
</role_boundaries>

<workflow>
## Phase 1: {Phase Name}
1. Step with specific action
2. Step with verification criteria
3. Step with output expectation

## Phase 2: {Phase Name}
1. Step building on Phase 1 output
2. Step with decision point
</workflow>

<stopping_rules>
## Stop When:
- Condition that signals completion
- Condition requiring user input
- Condition requiring escalation

## Escalate When:
- Blocker condition with structured data to include
- Uncertainty condition with questions to ask
</stopping_rules>

<error_handling>
## Error Recovery
- **Transient errors**: Retry with exponential backoff
- **Validation errors**: Log context, attempt correction
- **Blocking errors**: Escalate with full context

## Risk Assessment
- Evaluate consequences before destructive actions
- Prefer reversible operations when possible
</error_handling>

<stage_awareness>
## Stage-Aware Behavior (for specialists)

| Stage | Role | DO | DON'T |
|-------|------|-----|-------|
| **Spec** | Advisor | Evaluate requirements | Re-analyze code |
| **Plan** | Advisor | Confirm approach | Re-evaluate requirements |
| **Implement** | Validator | Fix specific issues | Re-review plan |
</stage_awareness>

<critical_subagent_behavior>
## Subagent Response Format (for specialists)

When invoked as a subagent, return structured JSON:

```json
{
  "status": "approve" | "concern" | "blocker",
  "summary": "Brief assessment",
  "findings": ["Finding 1", "Finding 2"],
  "suggestions": ["Actionable fix 1"],
  "filesReviewed": ["path/to/file.ts"]
}

• Keep response focused and actionable
• Do NOT include conversational preamble
• Manager will consume this JSON directly </critical_subagent_behavior>

<advisory_protocols>

Manager Integration (for specialists)

<context_consumption>

Consuming Context from Prior Stage (CRITICAL)

1. Read artifact from previous stage
2. Parse handoff section — extract file lists, recommendations
3. DO NOT re-analyze what prior stage validated </context_consumption>

<output_format>

Output Requirements (if applicable)

Structured Response Format

{
  "status": "approve" | "concern" | "blocker",
  "feedback": "Assessment summary",
  "suggestions": ["Actionable improvement 1"]
}

Artifact Location

Write output to: docs/{type}/ARTIFACT-NNN-{slug}.md </output_format>

<todo_list_usage>

Todo List (ALWAYS Use)

1. Create todo list at session start
2. Mark in-progress before starting each phase
3. Mark completed immediately when done
4. Add new todos only for blockers/scope changes </todo_list_usage>

### Subagent Usage

Use `#tool:agent/runSubagent` to delegate with isolated context. Provide self-contained prompts, specify exact output format, scope to ONE question per call.

### Specialist Invocation Templates (CRITICAL for Managers)

Manager agents should define **exact delegation templates** with:
1. File/item manifest for context
2. Quality criteria to apply
3. Specific checks to perform
4. Exact JSON return format

See [manager-agents.instructions.md](.github/instructions/manager-agents.instructions.md) for full template examples.

---

## Anti-Patterns

| Anti-Pattern | Why It's Problematic | Better Approach |
|--------------|---------------------|------------------|
| Duplicating coding standards in agents | Instructions files auto-inject; causes maintenance burden | Reference instruction files; agents define behaviour only |
| Missing `<error_handling>` section | Agent gives up too easily or crashes on errors | Always include recovery strategies |
| Missing `<stopping_rules>` | Agent runs indefinitely or stops too early | Define clear completion and escalation conditions |
| General-purpose agents | Jack of all trades, master of none | Create focused specialists for each domain |
| Hardcoded model names | Breaks when models deprecated | Use model selection guidance; prefer aliases |
| Missing `<todo_list_usage>` | User has no visibility into agent progress | Always use todo lists for multi-step work |
| Vague `<role_boundaries>` | Agent scope creep; unclear handoffs | Be explicit about what agent does AND doesn't do |

---

## References

- [GitHub Copilot Documentation](https://docs.github.com/en/copilot) - Official Copilot documentation
- [Supported AI Models](https://docs.github.com/en/copilot/reference/ai-models/supported-models) - Available models for agents
- [Model Comparison](https://docs.github.com/en/copilot/reference/ai-models/model-comparison) - Model selection by task type
- [Anthropic Agent Guidelines](https://docs.anthropic.com/en/docs/build-with-claude/agentic) - Building effective agents
- [OpenAI Agent Guidelines](https://platform.openai.com/docs/guides/agents) - Agent best practices
- [copilot-instructions.instructions.md](.github/instructions/copilot-instructions.instructions.md) - Instruction file standards
- [manager-agents.instructions.md](.github/instructions/manager-agents.instructions.md) - Manager agent patterns
- [specialist-agents.instructions.md](.github/instructions/specialist-agents.instructions.md) - Specialist agent patterns
- [prompt-files.instructions.md](.github/instructions/prompt-files.instructions.md) - Prompt file standards