Theory
Rules give agents project-level context. Custom agents go one step further: they package a specific persona, a specific set of instructions, and a specific set of tools into a reusable configuration you can switch into with a single click.
The key insight is that different tasks need different setups. A planning agent should not be able to edit files; you want it to think and propose, not accidentally change things. A security reviewer agent should be skeptical and focused on vulnerabilities, not general coding help. A commit message generator just needs to read the diff and write one thing. When you bundle the right instructions and the right tools together, the agent is less likely to drift and more likely to be useful immediately.
What a custom agent is made of
Custom agents are defined in a single Markdown file. In VS Code and Copilot this file has the .agent.md extension and lives in .github/agents/. In Claude Code, they live in .claude/agents/ as regular .md files.
At the top you put a YAML header with the configuration:
---
name: PR Reviewer
description: Reviews pull request diffs for bugs, security issues, and missing tests
tools: ['codebase', 'fetch']
---
Below the header, you write the instructions in plain Markdown. This is where you define the persona: what the agent focuses on, what it should always check, what it should never do, and how it should format its output.
Tool scoping matters
One of the most practical things custom agents let you do is restrict which tools are available. A read-only research agent that has no ability to write files cannot accidentally break something. An implementation agent that only has editing tools and terminal access won't go off looking up unrelated documentation mid-task. Scoping tools is both a quality improvement and a safety measure.
Handoffs
VS Code and Copilot support handoffs: after one agent finishes, it shows a button that switches to the next agent in a workflow, pre-filling the prompt with relevant context. This makes it easy to build lightweight multi-step workflows, like Plan → Implement → Review, without any custom infrastructure.
When to build a custom agent
A custom agent is worth building when you find yourself running the same kind of task repeatedly and always giving the same setup instructions manually. If you keep writing "review this for security issues, focus on injection risks, format findings as a numbered list" in every chat, that is a custom agent waiting to be created.
Practice
Run this in a repository you already know, not a toy project. The point is to feel where the practice helps and where it gets in the way on code that has history.
Build a custom agent that solves a real, recurring problem in your daily work. The goal is to have something genuinely useful at the end, not a toy example.
Step 1: Pick a problem worth automating.
Think about tasks you do repeatedly that follow a predictable pattern. Good candidates:
- Reviewing a PR diff for a specific class of issues (security, missing tests, accessibility)
- Writing commit messages or PR descriptions from a diff
- Generating a test file for a given module following your team's conventions
- Summarizing a GitHub issue into a task breakdown
- Checking a new API endpoint against your team's API design standards
Step 2: Design the agent before you write it.
Answer these questions first:
- What is the single job this agent does? (One sentence)
- What tools does it need? Does it need to edit files, or just read and respond?
- What should it always do? What should it never do?
- How should it format its output?
Step 3: Create the agent file.
Use the format for your tool:
- VS Code / Copilot: create
.github/agents/your-agent.agent.md - Claude Code: create
.claude/agents/your-agent.md - Cursor: create a custom agent from the settings or use the
.cursor/rules/approach with a dedicated role file
Write a tight YAML header (name, description, tools) and a clear instruction body. Keep the instructions specific: tell it what to focus on, how to structure the output, and any constraints.
Step 4: Run it on real work.
Use the agent on at least three real tasks, not made-up examples. For each one, note:
- Did it follow the instructions without prompting?
- Did it do something you didn't expect?
- How much editing did the output need?
Step 5: Iterate and commit.
Refine the instructions based on what you observed. Then commit the agent file to your repo so your team can use it too. A well-built custom agent is a shared productivity asset, not a personal configuration.