GitHub Copilot Instructions: Complete Setup and Optimization Guide

GitHub Copilot supports a copilot-instructions.md file that injects custom context into all Copilot chat requests in your repository. It's less flexible than Cursor's or Claude's rule systems, but it's the standard for teams already on GitHub — and it integrates directly with Copilot Workspace, pull request reviews, and Copilot Coding Agent.

Creating the Instructions File

Create the file at exactly this path in your repository:

.github/copilot-instructions.md

This file is read by:

• Copilot Chat in VS Code, JetBrains IDEs, Visual Studio, Xcode, and Eclipse
• Copilot Code Review in VS Code, Visual Studio, and GitHub.com
• Copilot Coding Agent (for pull request and issue assignments)

Note: Copilot instructions do not affect inline autocomplete ghost text — only Chat, code review, and the coding agent.

Path-Specific Instructions

Copilot also supports scoped instruction files in the .github/instructions/ directory:

codeCopy
.github/
  copilot-instructions.md                # Repository-wide
  instructions/
    react-components.instructions.md     # Scoped to .tsx files
    api-routes.instructions.md           # Scoped to API files

Each file uses YAML frontmatter with glob patterns:

markdownCopy
---
applyTo: "**/*.tsx,**/*.jsx"
---
Use functional components with hooks. Named exports only.

When both repository-wide and path-specific files match, instructions from both are combined.

Personal Instructions

Personal instructions (configured in your IDE settings) take the highest priority, followed by repository instructions, then organization instructions.

File Format and Structure

The file is plain Markdown. GitHub recommends keeping it focused and structured:

markdownCopy
# Copilot Instructions for [Project Name]

## Overview
Brief description of the project for Copilot's context.

## Tech Stack
- Node.js 20 LTS
- Express 4 with TypeScript
- PostgreSQL via Drizzle ORM
- Jest for testing

## Code Style
- Use async/await (not callbacks or raw promises)
- Named exports only
- All functions must have JSDoc comments

## Repository Structure
- `src/routes/` — Express route handlers
- `src/services/` — Business logic
- `src/models/` — Drizzle schema definitions
- `src/middleware/` — Express middleware

## Testing Requirements
- Unit tests for all service functions
- Integration tests for all API routes
- Minimum 80% coverage

What Copilot Instructions Can and Cannot Do

All three tools now support multi-file rules with path scoping. Copilot uses .github/instructions/ with applyTo frontmatter, Cursor uses .cursor/rules/ with globs, and Claude Code uses .claude/rules/ with paths.

Writing Effective Copilot Instructions

1. Be Explicit About Versions

Copilot's training includes many framework versions. Always specify the exact version to avoid outdated suggestions:

markdownCopy
## Exact Versions in Use
- React 18.3 (NOT React 19 — avoid useFormStatus, useOptimistic, use())
- Next.js 14.2 (Pages Router — NOT App Router, we haven't migrated yet)
- Prisma 5.x (not Drizzle — we use Prisma Client everywhere)

2. Describe Your Monorepo Package Contexts

For monorepos, define which conventions apply where:

markdownCopy
## Monorepo Package Conventions

### packages/web (React frontend)
- React 18 + TypeScript
- Tailwind CSS for styling
- Vite for bundling

### packages/api (Node.js backend)
- Express 4 + TypeScript
- No React, no Tailwind
- Return all errors as: `{ success: false, error: { code: string, message: string } }`

### packages/shared (shared utilities)
- Pure TypeScript — no framework-specific code
- CommonJS + ESM dual build

3. Security Context

markdownCopy
## Security Requirements
- Never include API keys, tokens, or credentials in code — use environment variables
- Always validate user input with Zod schemas before processing
- SQL: use parameterized queries via Drizzle (never string interpolation)
- CORS: restrict to known origins in `src/middleware/cors.ts`
- Authentication: all protected routes use `requireAuth` middleware

Copilot Coding Agent: Advanced Configuration

With GitHub Copilot Pro+, you can assign issues and PRs to the Copilot Coding Agent. Your copilot-instructions.md is the agent's primary context for understanding your repository.

For agent tasks, add an Agent-Specific section:

markdownCopy
## Copilot Agent Instructions

When working on assigned issues or PRs:

1. **Always run tests** before submitting: `npm test`
2. **Follow PR conventions**: small, focused PRs; descriptive commit messages
3. **Check the style guide**: run `npm run lint` before committing
4. **Add tests**: every new function needs a corresponding test in `__tests__/`
5. **Update documentation**: if changing public APIs, update `docs/api.md`

### File Creation Rules
- New Express routes go in `src/routes/[resource].router.ts`
- New services go in `src/services/[resource].service.ts`
- New tests mirror the source structure in `__tests__/`

Team Rollout and Governance

Requiring the Instructions File

Add enforcement to your CONTRIBUTING.md:

markdownCopy
## AI Tools

This repository includes a `.github/copilot-instructions.md` file. If you use GitHub Copilot:
1. Ensure the instructions file loads in your IDE (check Copilot Chat settings)
2. Don't duplicate or override these instructions with personal settings that conflict
3. Propose changes via PR with justification

Maintenance Process

Combining Copilot Instructions with Other Tools

Most teams now use multiple AI tools. Share the core context across all of them:

bashCopy
# Minimal sync: copy the shared core to each tool
cp .github/copilot-instructions.md .cursorrules
cp .github/copilot-instructions.md CLAUDE.md

# Or use a build script to generate all from a shared source
# See: https://agent-rules.com/builder for multi-format export

The Agent Rules Builder can generate coordinated rule files for Cursor, Claude Code, GitHub Copilot, and Windsurf simultaneously from a single configuration.