DEV Community

Arjun
Arjun

Posted on

Working with GitHub Copilot: Custom Instructions & Agents

#ai #github #tutorial #vscode

GitHub Copilot Custom Instructions & Custom Agents: A Practical Developer's Guide

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

To avoid confusion:

  • VS Code Agent mode refers to GitHub Copilot's built-in Agent Mode in Visual Studio Code—the mode that can plan and apply multi-file code changes.
  • Custom agents refer to user-defined agent profiles created via .github/agents and invoked explicitly (for example, @security-reviewer). Both use the word "agent," but they serve very different purposes.

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

Repository-level instructions are the most reliable and widely supported customization mechanism today.

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: Instructions "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: "We use Tailwind CSS for styling and Vitest for testing."
  • Naming conventions: "Always prefix interfaces with I (e.g., IUser)."
  • Strict restrictions: "Never use any in TypeScript."
  • Project context: "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 a lot of:
suggest-awesome-github-7_prompt.md
prompts for exploring community-sourced instruction files, agents, and templates. Pasting a prompt into VS Code Copilot Chat lets the AI recommend items relevant to your repository.
Example: the agent prompt at:
github-prompts/suggest-awesome-github-copilot-agents.prompt.md
can suggest which agent profiles could be useful. It is a powerful way to discover ready-to-use templates and workflows.

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:

  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
— 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:

  • 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 instructions: Framework conventions, reactivity, typing rules.
  • Backend instructions: naming, error handling, formatting.
  • IAM instructions: authentication/authorization rules.
  • Legacy framework instructions: safe modernization within constraints.

Custom Agents

Custom agents move Copilot from:
"AI that writes code" -> "AI that applies a specific engineering lens"
They can be defined:

  • For workspace: .github/agents
  • For user profile: 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

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.
  • Use @plan mode in VS Code Copilot to outline the feature or changes
  • Implement feature/functionality using VS Code Agent mode
  • Run @dotnet-security-reviewer -> flags missing authorization policy
  • Fix issue
  • Run @typescript-api-contract-reviewer -> flags nullable mismatch
  • Fix issue

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

You can't bake everything into VS Code Agent mode because:

  • 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

  1. Personal and organization instructions now sync with VS Code for most users.
  2. Custom agents can be linked with tools, subject to Copilot feature availability and workspace permissions.
  3. GitHub Copilot Chat is open source:

Resources

Top comments (0)