Skip to content

Latest commit

 

History

History
158 lines (99 loc) · 7.98 KB

part3-custom-agents.md

File metadata and controls

158 lines (99 loc) · 7.98 KB

Part 3 – Custom Copilot Agents

Navigation: Part 1 – Setup & Chat | Part 2 – Custom Skills | Part 3 | Part 4 – Issues & Review

Building Custom Agents

Goal: Create a custom Copilot agent — a specialized persona with its own behavior, tool access, and instructions.

What are Custom Agents?

Custom agents are specialized versions of Copilot tailored to specific workflows. Unlike skills (which are auto-loaded based on relevance), agents are manually selected by the user from a dropdown menu in Copilot Chat or on GitHub.com.

Agents are defined as Markdown files with YAML frontmatter, placed in .github/agents/.

How to think about Skills vs Agents

The simplest way to understand the difference:

  • A skill is knowledge — it teaches Copilot how to do something. Think of it like a reference card or a runbook. Copilot picks it up automatically whenever it's relevant, regardless of which "mode" you're in. A skill about your CI pipeline helps whether you're debugging, writing code, or planning a release.

  • An agent is a persona — it changes who you're talking to. When you select an agent, you're switching Copilot's entire personality, focus, and toolset. A code reviewer agent thinks differently than a documentation agent, even when looking at the same code.

Put another way: skills add to what Copilot knows, agents change how Copilot behaves. You can combine both — an agent can pick up skills, giving you a specialized persona that also has access to your team's domain knowledge.

Skills Agents
Concept Knowledge — how to do a task Persona — who is helping you
Analogy A reference card anyone can pick up A specialist you bring into the room
Invocation Automatic (Copilot loads when relevant) Manual (you select from a dropdown)
Effect Adds knowledge to the current session Changes behavior, tone, and focus
Tool control Inherits from context Can restrict via tools property
Structure Folder with SKILL.md Single .md file with YAML frontmatter
Location .github/skills/<name>/SKILL.md .github/agents/<name>.md
MCP servers No MCP config Can configure MCP servers
Combined Available to any agent automatically Can leverage any skill in the repo

Documentation: About custom agents

Exercise A: Create a code review agent

7. Build a code review agent

Step 1 — Create the agents directory

Make sure you're on your copilot-hackathon branch before creating these files.

  • In your repo, create the directory: .github/agents/

Step 2 — Define the agent

Key things to notice in the file:

  • tools: ["read", "search"] — this agent can only read and search, it cannot edit files
  • The prompt defines a review process and explicitly tells the agent not to modify anything
  • The description field is what Copilot shows in the agent dropdown

Step 3 — Test the agent

  • Open Copilot Chat in your IDE.
  • Look for the agent dropdown (model/agent selector) and select "Code Reviewer".
  • Ask it to review a file in your project.
  • Notice how it only uses read and search — it cannot edit files.

Exercise B: Create a documentation agent

8. Build a documentation agent

Step 1 — Define the agent

Make sure you're on your copilot-hackathon branch before creating this file.

Key things to notice:

  • tools: ["read", "search", "edit"] — unlike the reviewer, this agent can modify files
  • The prompt focuses on documentation, not code logic
  • Compare the tool lists between the two agents — this is how you shape what an agent can do

Step 2 — Test it

  • Select the "Doc Writer" agent in Copilot Chat.
  • Ask it to document a function or module in your project.
  • Notice it has edit access — it can create and modify documentation files.

BONUS: Build your own agent

BONUS. Design your own agent

Make sure you're on your copilot-hackathon branch before creating this file.

Now that you've seen how both agents work, create your own agent tailored to your team's needs.

Ideas to get started:

  • A security reviewer that scans for common vulnerabilities (read + search only)
  • A migration assistant that helps port code to a new library or framework
  • A test generator that focuses exclusively on writing tests for untested code
  • A release notes writer that drafts changelogs from commits and PRs

Steps

  • Create .github/agents/<your-agent-name>.md with a basic YAML frontmatter block (name, description, tools) and a one-paragraph summary of what you want the agent to do — you don't need to write polished instructions yourself.

  • Open Copilot Chat (Agent mode) and ask Copilot to expand your summary into full agent instructions. For example:

    "I've created .github/agents/security-reviewer.md with a short description. Please write detailed instructions for this agent following best practices for GitHub Copilot custom agents."

    Copilot will generate the full prompt body for you — review and tweak as needed.

  • (Optional) The community finalize-agent-prompt skill from github/awesome-copilot is purpose-built for exactly this. Copy it into your .github/skills/ folder and then ask Copilot to use it to polish your agent file — it will check structure, wording, and clarity against proven patterns.

  • Test your agent in Copilot Chat by selecting it from the agent dropdown.

  • Consider: would a skill complement this agent? Create a matching skill if so.

Key Takeaways

  • Agents give you persona-based control — you define what the agent can do, what tools it has, and how it behaves.
  • The tools property is powerful — restricting tools shapes the agent's capabilities (e.g., a reviewer that can read but not edit).
  • Agents can be shared across an organization or enterprise by placing them in a .github-private repository (see docs).
  • Combine agents with skills for maximum effect: agents define who is helping, skills define what they know.

Documentation & Resources

Getting started:

Technical reference:

Community & examples:

  • awesome-copilot — curated collection of community agents, skills, and extensions

Next up: Part 4 – Issues, Coding Agent & Review (continues at step 9)