Mastering GitHub Copilot: Custom Agents, Project Structure, and Global Instructions

by prateekb | Apr 8, 2026 | General | 0 comments

Learn how to transform GitHub Copilot into a specialized team member. This guide explores the community-standard .github project structure for Custom Agents, compares local and cloud modes, and reveals how to bake persistent rules into every prompt using Custom Instructions.

The Awesome Copilot project

The Awesome Copilot project is a community-driven repository that provides ready-to-use templates for personalizing GitHub Copilot. It helps developers standardise AI behavior across teams using structured folders like .github/agents, .github/instructions, and .github/prompts.

Project Structure Explained

The directories under .github (or sometimes in the root) define how Copilot behaves in your specific workspace:

agents/: Contains .agent.md files. These define Custom Agents—specialized personas (like a “Security Auditor” or “Frontend Expert”) with specific tools, models, and boundaries.
instructions/: Contains .instructions.md files. These are rules that apply automatically to specific file types (e.g., .js) or tasks, ensuring Copilot always follows your coding standards without being asked.
prompts/: Contains reusable markdown files for complex, multi-step tasks. You can trigger these manually in the chat using / commands or the #prompt picker to avoid retyping long instructions.

Copilot Modes: Local vs. Cloud vs. CLI

GitHub Copilot offers different execution environments depending on how much control or background processing you need:

Mode	Where it Runs	Best For…
Local Agent (VS Code)	Your machine	Interactive daily tasks, quick bug fixes, and immediate code edits.
Cloud Agent	GitHub servers	Autonomous work on GitHub issues or background tasks that result in a Pull Request while you are away.
Copilot CLI	Your terminal	Running agents through the command line, often used for background sessions that survive IDE restarts.

How to Make Your Own Custom Agent

You can create a custom agent to handle specific tasks (like a “QA Engineer” for writing tests) in a few steps:

Create the file: Add a new file at .github/agents/my-agent.agent.md.
Add Frontmatter: Include a YAML header at the top to define the agent’s name, description, and available tools.
- -- name: "Test-Agent"description: "Persona of a QA engineer that writes and runs tests."tools: ["read", "execute", "edit"] ---
Write the Persona: Below the header, write the instructions (in plain Markdown) describing its role, responsibilities, and constraints.
Use it: Restart your IDE or CLI. The agent will appear in the chat’s agent dropdown or can be summoned via @test-agent.

How to Force Instructions in Every Prompt

To ensure certain rules are followed every time you interact with Copilot (without explicitly mentioning them), use Custom Instructions:

Project-Wide Rules: Create a file named .github/copilot-instructions.md. VS Code automatically injects the content of this file into every chat request for that workspace.
Targeted Rules: Use files in .github/instructions/*.instructions.md with an applyTo field in the frontmatter to target specific file extensions (e.g., applyTo: "**.ts").

Custom Agent Templates

Place these in .github/agents/ within your repository.

1. Security Review Agent (security-expert.agent.md)

This agent focuses on identifying vulnerabilities and ensuring secure coding practices.

---
name: "Security-Expert"
description: "Specialized in code audits for SQLi, XSS, and secret leaks."
tools: &#91;"read", "search"]
---
# Security Expert Agent
You are a senior security researcher. Your goal is to identify security vulnerabilities 
in the provided code.

### Your Responsibilities:
- Thoroughly check for potential issues like **SQL injection**, **Cross-Site Scripting (XSS)**, 
  and **insecure authentication**.
- Scan for **secrets or credentials** accidentally hardcoded in source files.
- Identify **vulnerable dependencies** in manifest files (e.g., `package.json`, `requirements.txt`).
- Provide a risk level (Low/Medium/High) and a recommended fix for every finding.

---

name: "Security-Expert"

description: "Specialized in code audits for SQLi, XSS, and secret leaks."

tools: ["read", "search"]

---

# Security Expert Agent

You are a senior security researcher. Your goal is to identify security vulnerabilities

in the provided code.

### Your Responsibilities:

- Thoroughly check for potential issues like **SQL injection**, **Cross-Site Scripting (XSS)**,

and **insecure authentication**.

- Scan for **secrets or credentials** accidentally hardcoded in source files.

- Identify **vulnerable dependencies** in manifest files (e.g., `package.json`, `requirements.txt`).

- Provide a risk level (Low/Medium/High) and a recommended fix for every finding.

2. Documentation Specialist Agent (docs-pro.agent.md)

Use this agent to maintain high-quality API documentation and README files.

---
name: "Docs-Pro"
description: "Generates high-quality API documentation, READMEs, and onboarding guides."
tools: &#91;"read", "edit"]
---
# Documentation Specialist Agent
You are a technical writer responsible for the project's documentation quality.

### Your Responsibilities:
- **Analyze source code** to generate accurate JSDoc, TSDoc, or docstrings.
- **Maintain the README.md**, ensuring it reflects the current architecture and setup steps.
- Use a **neutral and inclusive** tone, following professional documentation standards.
- Ensure all technical examples are current and use **place-holder data** instead of sensitive info.

---

name: "Docs-Pro"

description: "Generates high-quality API documentation, READMEs, and onboarding guides."

tools: ["read", "edit"]

---

# Documentation Specialist Agent

You are a technical writer responsible for the project's documentation quality.

### Your Responsibilities:

- **Analyze source code** to generate accurate JSDoc, TSDoc, or docstrings.

- **Maintain the README.md**, ensuring it reflects the current architecture and setup steps.

- Use a **neutral and inclusive** tone, following professional documentation standards.

- Ensure all technical examples are current and use **place-holder data** instead of sensitive info.

Global Instructions (The “Always On” Mode)

To execute specific instructions in every prompt without telling Copilot each time, create a file at .github/copilot-instructions.md. Copilot automatically injects this content into the background of all chat requests for the workspace. Example Content for .github/copilot-instructions.md:

Coding Standards: “Always use 2-space indentation and prefer functional programming patterns.”
Technology Stack: “This project uses React 18 with Tailwind CSS; do not suggest other styling frameworks.”
Error Handling: “Never swallow exceptions; always log errors using the internal Logger utility.”

Would you like a template for a testing specialist agent or more details on agent handoffs?

Further Exploration

Learn about the MCP protocol for giving agents more powers in the Awesome Copilot README.
See more complex multi-agent workflow examples on the GitHub Blog.
Explore best practices for writing effective custom instructions from GitHub Docs.

[1] https://clouddev.blog [2] https://www.youtube.com [3] https://docs.github.com [4] https://docs.github.com [5] https://github.com [6] https://code.visualstudio.com [7] https://learn.microsoft.com [8] https://github.blog [9] https://blairrobinson757.medium.com [10] https://docs.github.com [11] [https://github.com](https://github.com/github/awesome-copilot/blob/main/docs/README.agents.md#:~:text=To Activate/Use: * Access installed agents through,* Follow agent-specific instructions for optimal usage.) [12] https://github.blog