A guide to GitHub Copilot agents

From your first custom agent to reliable, governed workflows: explore 28 illustrated chapters, one clear step at a time.

Start with the foundations, learn how to shape an agent's work, then connect those ideas to planning, validation and human oversight.

Read your way

Use the chapter tiles below, the chapter list, or search. Each chapter has Previous, Home and Next navigation at the bottom. The last chapter leads to Resources.

Switch between light and dark mode using the control in the header. The site uses a locally hosted Atkinson Hyperlegible font, generous line spacing, left-aligned text and restrained reading surfaces. Font preferences vary; no single font works best for every reader.

Your learning journey

Follow the chapters in order, or choose a topic. Each includes the original infographic and a readable explanation.

1. 
   Chapter 1

   What are custom agents?

   Understand personas, instructions, skills and tools before building your first agent.

   Read chapter →
2. 
   Chapter 2

   Anatomy of an agent

   Explore the configuration and Markdown guidance that make up an agent profile.

   Read chapter →
3. 
   Chapter 3

   Write clear agent instructions

   Turn a role description into focused review criteria and useful, structured output.

   Read chapter →
4. 
   Chapter 4

   Understand configuration scopes

   Separate personal preferences, repository guidance and organizational policy without assuming one universal precedence rule.

   Read chapter →
5. 
   Chapter 5

   Configure your working environment

   Consider suggestion behavior, language preferences and sensitive context using settings supported by your actual client.

   Read chapter →
6. 
   Chapter 6

   Choose a focused design pattern

   Compare domain experts, workflow automators and quality reviewers as starting points for agent design.

   Read chapter →
7. 
   Chapter 7

   Use custom agents deliberately

   Make profiles discoverable and select the right specialist for a bounded task.

   Read chapter →
8. 
   Chapter 8

   Ask for better results

   Write specific requests with existing examples, acceptance criteria, boundaries and a clear definition of done.

   Read chapter →
9. 
   Chapter 9

   Avoid common custom-agent pitfalls

   Replace vague personas, accidental tool access and contradictory instructions with focused responsibilities.

   Read chapter →
10. 
    Chapter 10

    Common questions about custom agents

    Resolve practical questions about selection, skills, team size and useful examples.

    Read chapter →
11. 
    Chapter 11

    Maintain effective custom agents

    Combine specific personas, examples, tested model choices and a maintainable repository structure.

    Read chapter →
12. 
    Chapter 12

    Connect agents to MCP tools safely

    Use the PostgreSQL example to distinguish external capability from permission and authorization.

    Read chapter →
13. 
    Chapter 13

    Package repeatable work as skills

    Separate an agent's role from task-specific instructions, examples and supporting resources.

    Read chapter →
14. 
    Chapter 14

    Choose the right coding-agent tasks

    Start with bounded, verifiable work and recognize tasks that need more human discovery first.

    Read chapter →
15. 
    Chapter 15

    Common questions about coding-agent work

    Set realistic expectations for duration, repository access, stalled work and concurrent tasks.

    Read chapter →
16. 
    Chapter 16

    Prepare the repository for agent work

    Make setup reproducible and supply clear conventions, repeatable guidance and validation.

    Read chapter →
17. 
    Chapter 17

    Monitor and steer remote work

    Understand the value of remote session control without assuming a specific command or interface is available.

    Read chapter →
18. 
    Chapter 18

    Use hooks as supporting controls

    Connect lifecycle events to deterministic checks while accounting for host support and failure behavior.

    Read chapter →
19. 
    Chapter 19

    Learn the language of agentic systems

    Define agents, architecture, branches, pull requests, workflows, validation and policy.

    Read chapter →
20. 
    Chapter 20

    Make the agentic workflow visible

    Connect the goal, proposed changes and review evidence through a plan-act-validate-merge loop.

    Read chapter →
21. 
    Chapter 21

    Map responsibilities to the SDLC

    Give planning, implementation, validation and deployment distinct responsibilities and control points.

    Read chapter →
22. 
    Chapter 22

    Define a task contract

    Specify inputs, outputs and success criteria so an agent's work can be evaluated against the real goal.

    Read chapter →
23. 
    Chapter 23

    Separate planning from execution

    Choose when a human reviews intent and enforce the boundary according to task risk.

    Read chapter →
24. 
    Chapter 24

    Make pull requests control points

    Combine structured proposals, required checks, expert review and protected deployment environments.

    Read chapter →
25. 
    Chapter 25

    Match autonomy to risk

    Extend pull-request governance with explicit approval boundaries and risk-sensitive decisions.

    Read chapter →
26. 
    Chapter 26

    Build reliable workflow handoffs

    Carry structured outputs between jobs, use the right context and gate execution according to event and risk.

    Read chapter →
27. 
    Chapter 27

    Observe and operate agents

    Combine evidence, bounded retries, safe tool access, secrets management and escalation.

    Read chapter →
28. 
    Chapter 28

    Architecture summary

    Bring the journey together: focused responsibilities, verifiable work, enforced boundaries and human oversight.

    Read chapter →