Working with GitHub Copilot: Custom Instructions & Agents

Source: Dev.to

I recently explored Custom Instructions and Custom Agents in GitHub Copilot. While these features seem simple at first, they fundamentally change how Copilot behaves in real‑world codebases—especially when used intentionally.

This guide reflects my current understanding and practical takeaways, based entirely on GitHub Copilot Chat in Visual Studio Code (unless explicitly stated otherwise).

Terminology Clarification

Custom Instructions vs. Custom Agents (Mental Model)

• Custom Instructions provide persistent project context.
• Custom Agents provide specialized behavior for a specific chat interaction.

Think of instructions as the project’s rulebook, and custom agents as specialized reviewers you invoke deliberately.

Custom Instructions

1. Repository‑wide instructions

Create a file at:

.github/copilot-instructions.md

This file:

• Applies across the repository.
• Acts as Copilot’s persistent project context.
• Serves as a shared rulebook (not an enforcement mechanism).
• VS Code can generate this file automatically by analyzing the codebase. Treat it as a starting point, not an authoritative specification — human review is still required.

2. Path‑specific instructions

You can create scoped instruction files using apply‑to globs, e.g.:

.github/instructions/**/*.instructions.md

These instructions are loaded only when files matching the path are in context, so frontend rules don’t leak into backend code and vice‑versa.

Examples

• .github/instructions/csharp-coding-standards.instructions.md → C# backend files
• .github/instructions/typescript-coding-standards.instructions.md → TypeScript frontend files

All instructions—repository‑wide or path‑specific—are guidance, not hard constraints.

Example: “Never use any in TypeScript.”
Copilot usually avoids any, but it may still insert it if types are ambiguous or for brevity. Human review or custom agents are still needed for enforcement.

What to Include in Instruction Files

Include only information Copilot cannot infer from code:

• Tech‑stack choices – e.g., “We use Tailwind CSS for styling and Vitest for testing.”
• Naming conventions – e.g., “Always prefix interfaces with I (e.g., IUser).”
• Strict restrictions – e.g., “Never use any in TypeScript.”
• Project context – e.g., “This is a legacy monolithic project; prioritize compatibility over new features.”
• Avoid duplicating rules already enforced by compilers, linters, or CI.

Awesome Copilot Repository

The Awesome Copilot repository contains many community‑sourced prompts, instruction files, agents, and templates.

• Prompt example: suggest-awesome-github-7_prompt.md – paste into VS Code Copilot Chat to get AI‑recommended items relevant to your repository.
• Agent prompt example: github-prompts/suggest-awesome-github-copilot-agents.prompt.md – suggests which agent profiles could be useful.

Personal & Organization Instructions

GitHub Copilot also supports:

• Personal instructions
• Organization instructions

These now sync with VS Code via Settings Sync, so rules defined on GitHub.com apply in your IDE as well.

Instruction Priority

When multiple sources exist, Copilot combines them and generally follows this precedence (higher on the list = higher priority):

1. Personal/User instructions
2. Repository instructions (.github/copilot-instructions.md)
3. Organization instructions

Conflict resolution is probabilistic—behavior is not strictly deterministic.

Instruction File Strategy (Avoid Instruction Bloat)

Instead of one massive file, split instructions by domain and technology:

.github/
│
├─ copilot-instructions.md          # global, non‑negotiables
└─ instructions/
   ├─ frontend.instructions.md
   ├─ backend.instructions.md
   ├─ security-iam.instructions.md
   └─ dotnet-framework-legacy.instructions.md

Global Playbook (.github/copilot-instructions.md)

Include non‑negotiables only:

• Architecture: Prefer composition over inheritance. Follow Zero Trust for public APIs.
• Security: Never log PII, raw tokens, or secrets.
• Performance: Prefer O(n) or better; explicitly mark async I/O.
• Documentation: Document public contracts and complex logic only.

Keep this file small and stable.

Scoped Instruction Examples

• Frontend: Framework conventions, reactivity patterns, typing rules.
• Backend: Naming, error handling, formatting.
• IAM: Authentication/authorization rules.
• Legacy framework: Safe modernization within constraints.

Custom Agents

Custom agents shift Copilot from:

“AI that writes code” → “AI that applies a specific engineering lens”

Definition Locations

• Workspace‑level: .github/agents (specific to a repository)
• User‑profile level: Shared across workspaces

Custom agents are not more powerful than VS Code Agent mode—they are more focused and opinionated.

Practical Use of Custom Agents

(Content continues in the original guide – keep the same sections and examples as needed.)

Agents

A Lightweight Team Pattern

• VS Code Agent mode → implementation only
• Custom agents → required reviewers (by team convention, not enforced by Copilot)

Treat custom‑agent output like PR review feedback, not suggestions.

Example Workflow

Recommended: Repository‑wide and path‑specific instructions are configured to improve results.

1. Use @plan mode in VS Code Copilot to outline the feature or changes.
2. Implement the feature/functionality using VS Code Agent mode.
3. Run @dotnet-security-reviewer → flags missing authorization policy.
4. Fix the issue.
5. Run @typescript-api-contract-reviewer → flags nullable mismatch.
6. Fix the issue.

Why Not Bake All of This Into VS Code Agent Mode?

• Goals conflict (speed vs. caution)
• Rules dilute as constraints grow
• Context matters—most checks aren’t always relevant
• Humans bypass friction when slowed down
• LLMs average; they don’t arbitrate
• Completion bias beats prevention

Silent violations are worse than explicit reviews.

VS Code Agent mode builds. Custom agents judge.
That separation is the difference between AI that helps and AI you can trust.

Final Notes

• Personal and organization instructions now sync with VS Code for most users.
• Custom agents can be linked with tools, subject to Copilot feature availability and workspace permissions.

GitHub Copilot Chat is open source:

• VS Code Copilot Chat

Built‑in agents (like Plan mode) are visible here:

• Plan‑agent.md

Resources

• Creating custom agents in VS Code
• Awesome Copilot