GitHub Copilot Custom Instructions: Complete Setup Guide (2026)

Overview

GitHub Copilot custom instructions let you define project-specific rules that shape every suggestion Copilot generates. Instead of repeatedly correcting Copilot to use your team’s conventions — naming patterns, error handling strategies, import styles — you write them once in a markdown file that ships with your repo.

This guide covers the three instruction layers: repository-level instructions via .github/copilot-instructions.md, workspace-level VS Code settings, and the newer per-file instruction includes. You’ll have working custom instructions configured in under 10 minutes.

Prerequisites

• Editor: VS Code (recommended), JetBrains, Visual Studio, or Neovim with Copilot plugin installed
• Subscription: Any GitHub Copilot plan (Free tier supports custom instructions)
• Extension version: GitHub Copilot Chat extension updated to latest
• Git repo: Your project needs to be a git repository — instructions are read from the repo root

Step 1: Create the Instructions File

The primary mechanism is a markdown file at .github/copilot-instructions.md in your repository root. Copilot reads this file automatically — no configuration needed.

mkdir -p .github
touch .github/copilot-instructions.md

Open the file and add your instructions in plain language. Copilot treats the entire file content as a system-level prompt prepended to every interaction.

## Project Context
This is a TypeScript monorepo using pnpm workspaces.
Backend: Express + Prisma. Frontend: React 19 + Vite.

## Code Standards
- Use `type` over `interface` unless extending
- Error handling: return Result types, never throw in business logic
- Imports: use path aliases (@/lib, @/components)
- Tests: Vitest with Testing Library, no enzyme

## Naming
- React components: PascalCase files and exports
- Utilities: camelCase
- Database models: PascalCase, singular (User not Users)
- API routes: kebab-case (/api/user-profiles)

Step 2: Structure Instructions Effectively

Not all instructions are equal. Copilot responds best to specific, actionable rules — not vague principles. Structure matters.

What works:

## Error Handling
Always wrap async route handlers with asyncHandler():
asyncHandler(async (req, res) => { ... })
Never use try/catch blocks in route handlers directly.

What doesn’t work:

Please try to handle errors nicely and make sure the code is clean.

Organize your file with markdown headers. Copilot parses structure, so group related rules under clear H2/H3 headings: project context, coding standards, architecture decisions, forbidden patterns.

Include negative instructions (what NOT to do) alongside positive ones. Copilot handles explicit prohibitions well:

## Forbidden Patterns
- Do NOT use `any` type — use `unknown` and narrow
- Do NOT import from barrel files (index.ts) in the same package
- Do NOT use default exports except for React page components
- Do NOT use class components

Step 3: Configure VS Code Settings

Beyond the repo-level file, VS Code exposes settings for additional instruction control. Open your workspace or user settings (⌘ + , on macOS, Ctrl + , on Windows/Linux).

Add workspace-level instructions in .vscode/settings.json:

{
  "github.copilot.chat.codeGeneration.instructions": [
    {
      "text": "Always add JSDoc comments to exported functions"
    },
    {
      "text": "Use named exports, not default exports"
    },
    {
      "file": ".github/copilot/react.md"
    }
  ],
  "github.copilot.chat.testGeneration.instructions": [
    {
      "text": "Use Vitest and Testing Library. Follow AAA pattern."
    }
  ]
}

The file property lets you point to separate instruction files, keeping your settings clean. This is useful when you have framework-specific rules that would bloat the main instructions file.

Step 4: Use Per-File Instruction Includes

For larger projects, you can create multiple instruction files under .github/copilot/ and reference them contextually. This keeps instructions modular.

Example file at .github/copilot/react.md:

## React Component Rules
- Functional components only
- Use `useState` and `useReducer` for local state
- Global state via Zustand — no Redux, no Context for state management
- All components must be wrapped with `memo()` only when receiving
  callback props from parent
- Use CSS Modules (.module.css), not styled-components or Tailwind

## Component File Structure
1. Imports
2. Types/interfaces
3. Component function
4. Helper functions (below component)
5. Named export at bottom

And .github/copilot/api.md:

## API Layer
- All endpoints return { data, error, meta } shape
- Use Zod schemas for request validation
- Rate limiting middleware on all public endpoints
- Pagination: cursor-based, never offset-based
- Auth: JWT in httpOnly cookies, never localStorage

Step 5: Team Collaboration and Git

Custom instructions become powerful when shared. Commit .github/copilot-instructions.md and any files under .github/copilot/ to your repository. Every team member with Copilot gets the same context.

git add .github/copilot-instructions.md .github/copilot/
git commit -m "Add Copilot custom instructions for project standards"

For workspace-level VS Code settings, decide whether .vscode/settings.json should be committed. If your team uses VS Code uniformly, committing it ensures consistent behavior. Otherwise, document the recommended settings in your project README and let developers opt in.

Step 6: Verify Instructions Are Active

To confirm Copilot is reading your instructions, open Copilot Chat in VS Code and type:

What custom instructions are you following?

Copilot will summarize the active instructions. If it doesn’t reference your rules, check:

1. The file is at the exact path .github/copilot-instructions.md (case-sensitive)
2. The file is in the repository root, not a subdirectory
3. Your VS Code Copilot extension is up to date
4. The setting github.copilot.chat.codeGeneration.useInstructionFiles is not disabled

You can also test with a targeted prompt: ask Copilot to generate code that would violate one of your rules. If it follows the rule, your instructions are working.

Tips and Best Practices

• Iterate on instructions like code. Track which suggestions Copilot still gets wrong, and add specific rules for those patterns. Review and prune instructions quarterly.

• Use examples, not abstractions. A three-line code sample communicates a pattern more reliably than a paragraph of description. Show the before (wrong) and after (right) when the distinction matters.

• Layer instructions by scope. Repo-level .github/copilot-instructions.md for universal rules. VS Code settings for language- or framework-specific rules. Keep each layer focused.

• Prioritize high-frequency patterns. Instructions about error handling, imports, and naming conventions fire on almost every suggestion. Niche rules about rarely-used APIs provide less value per character.

• Test with Copilot Chat before trusting completions. Chat follows instructions more consistently than inline completions. If Chat ignores a rule, inline completions definitely will too — rewrite the rule.

JetBrains and Other Editors

JetBrains IDEs (IntelliJ, WebStorm, PyCharm) read .github/copilot-instructions.md the same way VS Code does. The repo-level instructions file is editor-agnostic.

However, the VS Code-specific settings (github.copilot.chat.codeGeneration.instructions) do not apply in JetBrains. For cross-editor teams, put all instructions in the markdown file rather than VS Code settings.

Neovim users with copilot.lua also get repo-level instruction support, though Chat-specific features depend on the plugin version. Visual Studio (not VS Code) supports the instructions file in recent Copilot updates.

Real-World Examples

Python data engineering project:

## Stack
Python 3.12, pandas 2.x, SQLAlchemy 2.x, Pydantic v2

## Rules
- Type hints on all function signatures
- Use `pathlib.Path`, never `os.path`
- DataFrames: always specify dtypes explicitly
- SQL: use SQLAlchemy ORM, never raw strings
- Logging: structlog with bound loggers, never print()

Go microservice:

## Architecture
Clean architecture: handler → service → repository layers
No business logic in handlers. No SQL in services.

## Go Standards
- Errors: wrap with fmt.Errorf("operation: %w", err)
- Context: first parameter in all functions that do I/O
- No init() functions
- No global mutable state
- Tests: table-driven with t.Run subtests

These examples show the right level of specificity. Each rule is a clear constraint Copilot can follow mechanically.

FAQ