GitHub Copilot Instructions: Customize Your AI Pair Programmer
Configure .github/copilot-instructions.md for better AI code generation
GitHub Copilot Instructions are markdown files that teach Copilot your project's architecture, build process, and security requirements. Only 55% of AI-generated code meets security standards (Georgetown, 2024). Custom instructions fix this. Create .github/copilot-instructions.md for repository-wide rules or .github/instructions/*.instructions.md for path-specific patterns.
What are GitHub Copilot Instructions?
GitHub Copilot Instructions are configuration files that teach Copilot about your specific project. Think of them as a training manual for your AI pair programmer - instead of getting generic code suggestions, Copilot learns your frameworks, security patterns, and project structure.
These instructions live in .github/copilot-instructions.md for repository-wide guidance, or in .github/instructions/*.instructions.md for path-specific rules. When you're vibe coding with Copilot, these files ensure the AI generates code that matches your project's patterns rather than generic examples.
Copilot Instructions work across all editors where Copilot is installed - VS Code, JetBrains IDEs, Visual Studio, Neovim, and GitHub.com. One config file, consistent suggestions everywhere.
Where can I find Copilot instruction templates?
Get started faster with official documentation and community configurations:
How to set up Copilot Instructions
Setting up GitHub Copilot Instructions requires creating a markdown file in your repository's .github folder:
Create the .github folder
# Create .github folder if it doesn't exist
mkdir -p .githubCreate copilot-instructions.md
touch .github/copilot-instructions.mdAdd your project context
Include three essential sections: overview, build commands, and architecture:
# Next.js Project Instructions
## Overview
- Framework: Next.js 14 (App Router)
- Language: TypeScript (strict mode)
- Database: Supabase (PostgreSQL with RLS)
- Validation: Zod
- Auth: NextAuth.js v5
## Build Commands
- Install: `npm install`
- Dev: `npm run dev` (localhost:3000)
- Build: `npm run build`
- Test: `npm test`
## Architecture
- `/app` - Pages and API routes
- `/components` - React components
- `/lib/supabase` - Database client
- `/lib/validations` - Zod schemas
- `/types` - TypeScript types
## Coding Standards
- Use 'use client' for interactive components
- Use 'use server' for server actions
- All API routes must validate session
- All database queries use Supabase RLS
- All inputs validated with Zod
## Security
- Parameterized queries only (use Supabase client)
- Validate all user input with Zod
- Check authentication in API routes
- Environment variables for secrets
- Generic error messages to usersEnable in your editor
VS Code enables instructions by default. For other editors:
- VS Code: Enabled by default. Check
github.copilot.chat.codeGeneration.useInstructionFiles - Visual Studio: Settings → Copilot → Enable custom instructions
- JetBrains: Supports
.github/copilot-instructions.mdautomatically
Commit and test
Commit the file to your repository. Copilot automatically reads it. Test by asking Copilot to generate code - it should follow your patterns.
What are the different Copilot instruction file types?
GitHub Copilot supports multiple instruction file formats for different use cases. Understanding when to use each is critical for effective vibe coding.
.github/copilot-instructions.md Repository-wideSingle file applying to all Copilot requests in the repository. Best for project overview, build commands, and universal security rules.
.github/instructions/*.instructions.md Path-specificMultiple files with applyTo frontmatter for path-specific rules. Different instructions for different parts of your codebase.
AGENTS.md Cross-toolUniversal format supported by Copilot coding agent, Cursor, Claude Code, and Cline. Nearest file in directory tree takes precedence.
.github/
├── copilot-instructions.md # Repository-wide (all requests)
└── instructions/
├── api-routes.instructions.md # API-specific rules
├── components.instructions.md # Component patterns
├── database.instructions.md # Database queries
└── security.instructions.md # Security requirementsHow do I set path-specific instructions with applyTo?
Path-specific instructions let you customize Copilot behavior for different parts of your codebase. Create these in .github/instructions/ with filenames ending in .instructions.md.
---
applyTo: "app/api/**/*.ts"
excludeAgent: "code-review"
---
# API Route Instructions
All API routes must:
- Validate input with Zod schemas
- Use Supabase RLS for authorization
- Return proper HTTP status codes
- Include error handling with try/catch
- Log errors but return generic messagesFrontmatter options
| Option | Description | Example |
|---|---|---|
applyTo | Glob pattern for files this applies to | "app/api/**/*.ts" |
excludeAgent | Agent to exclude (code-review or coding-agent) | "code-review" |
description | Brief description of the instructions | "API route security rules" |
name | Display name in editor UI | "API Security" |
Common applyTo patterns
"**/*.ts" All TypeScript files"app/api/**/*.ts" API routes only"components/**/*.tsx" React components"lib/db/**/*" Database layer"**/*.test.ts,**/*.spec.ts" Test files (multiple patterns)What should I include in Copilot instructions?
According to GitHub's official guidance, every Copilot instructions file should include these five sections:
1. Project Overview
Elevator pitch: what the app does, audience, key features. Include frameworks and runtime.
2. Tech Stack
List backend, frontend, APIs, and testing frameworks. Brief implementation notes.
3. Build Commands
Exact commands for install, dev, build, test, lint. Include prerequisites.
npm install (requires Node 20+), npm run dev (port 3000)4. Project Structure
Folder organization with contextual descriptions. Helps Copilot suggest correct imports.
5. Coding Guidelines
Project-wide standards: type hints, testing mandates, security practices.
GitHub recommends ~2 pages maximum. An imperfect instructions file outperforms nothing at all.
Which IDEs support Copilot instructions?
Copilot Instructions work across multiple editors, but each has specific settings:
VS Code
- Enabled by default
- Setting:
github.copilot.chat.codeGeneration.useInstructionFiles - AGENTS.md:
chat.useAgentsMdFile - Nested agents:
chat.useNestedAgentsMdFiles
Visual Studio
- Disabled by default
- Enable: Tools → Options → Copilot → Enable custom instructions
- Supports same file format as VS Code
JetBrains IDEs
- Supports
.github/copilot-instructions.md - Global:
global-copilot-instructions.mdlocally - Path-specific files also supported
GitHub.com
- Reads instructions from repository
- Works with Copilot in PR reviews
- Coding agent uses instructions
How do I add security rules to Copilot instructions?
Security instructions teach Copilot to avoid common vulnerabilities in AI-generated code. According to Georgetown University research (2024), only 55% of AI-generated code meets security standards. Custom instructions dramatically improve this.
# Security Requirements
## Database Queries
ALWAYS use parameterized queries. NEVER concatenate user input into SQL.
## Input Validation
All user input MUST be validated with Zod schemas before processing.
## Authentication
All API routes MUST verify authentication before processing requests.
Check session with getServerSession() or equivalent.
## Authorization
Use Row Level Security (RLS) for data access control.
Never query data without checking user permissions.
## Secrets Management
NEVER hardcode secrets, API keys, or credentials.
Use environment variables: process.env.VARIABLE_NAME
## Error Handling
Log errors internally but return generic messages to users.
Never expose stack traces or internal details.SQL Injection Prevention
const user = await db.query(
`SELECT * FROM users WHERE id = ${userId}`
)const user = await db.query(
'SELECT * FROM users WHERE id = $1',
[userId]
)Input Validation with Zod
export async function POST(req: Request) {
const data = await req.json()
return await createUser(data)
}const UserSchema = z.object({
email: z.string().email(),
name: z.string().min(1).max(100)
})
export async function POST(req: Request) {
const data = UserSchema.parse(await req.json())
return await createUser(data)
}See our guides on SQL injection, missing authentication, and hardcoded secrets for more patterns.
Copilot Instructions vs other AI tools
Each vibe coding tool handles configuration differently. Here's how Copilot compares:
| Feature | GitHub Copilot | Cursor | Windsurf | Cline |
|---|---|---|---|---|
| Main file | .github/copilot-instructions.md | .cursor/rules/ | .windsurf/rules/ | .clinerules/ |
| Path-specific | .instructions.md with applyTo | Glob in frontmatter | Glob activation | Numeric prefixes |
| AGENTS.md | Yes (since Aug 2025) | Yes | No | Yes (fallback) |
| Cross-editor | Yes (all major IDEs) | Cursor only | Windsurf only | VS Code only |
| Global rules | User profile settings | ~/.cursor/rules/ | ~/.windsurf/global_rules.md | ~/Documents/Cline/Rules/ |
If your team uses multiple AI tools, maintain both .github/copilot-instructions.md (for Copilot users) and AGENTS.md (for Cursor/Claude Code users) in the same repository.
Best practices
✅ Do
- Keep repository-wide instructions to ~2 pages
- Use imperative language ("ALWAYS validate input")
- Include specific code examples with ❌/✅
- Document build preconditions (Node.js version, env vars)
- Update instructions when architecture changes
- Use path-specific instructions for security-critical code
❌ Don't
- Write 20-page instruction manuals
- Use vague suggestions ("consider validating")
- Describe patterns without code examples
- Let instructions become outdated
- Create conflicting path-specific rules
- Duplicate entire framework documentation
Common mistakes to avoid
Path-specific rules that contradict repository-wide rules confuse Copilot. Make path rules more specific, not opposite.
Documenting every coding preference creates noise. Focus on architecture, security, and non-obvious patterns.
Vibe coders often forget security instructions, relying on code review to catch issues. Add security rules upfront.
Instructions referencing old frameworks teach incorrect patterns. Review quarterly or when migrating.
Frequently asked questions
Do GitHub Copilot Instructions work in all editors?
Yes. GitHub Copilot Instructions work in VS Code, JetBrains IDEs, Visual Studio, Neovim, and GitHub.com. Once you commit .github/copilot-instructions.md to your repository, all team members see suggestions based on those instructions regardless of their editor.
How do I test if Copilot is reading my instructions?
Write a code comment requesting something specific from your instructions (like "create a validated API route") and check if Copilot follows your patterns. If it suggests Zod validation or your auth patterns, the instructions are working. VS Code also shows which files contributed to context.
Can I have different instructions for different branches?
Yes. Copilot reads instructions from the current branch, so feature branches can have different instructions than main. This is useful for testing new architectural patterns or security rules before applying them repository-wide.
Do instructions apply to Copilot Chat and inline suggestions?
Yes. According to GitHub documentation, Copilot uses instructions for both inline suggestions and chat responses. When you ask Copilot Chat to "create an API route," it applies your security rules and framework patterns from your instruction files.
What is the difference between .instructions.md and copilot-instructions.md?
copilot-instructions.md in .github/ applies to all requests repository-wide. Files ending in .instructions.md in .github/instructions/ use applyTo frontmatter for path-specific rules - different instructions for different parts of your codebase.
Does Copilot support AGENTS.md like other AI tools?
Yes. Since August 2025, GitHub Copilot coding agent supports AGENTS.md files alongside copilot-instructions.md. It also supports CLAUDE.md and GEMINI.md for cross-tool compatibility. The nearest AGENTS.md file in the directory tree takes precedence.
Verify Your Instructions Are Working
Copilot Instructions help prevent vulnerabilities, but can't catch everything. VibeShip Scanner automatically detects security issues in your vibe coded projects - even ones that slip past your instructions.
Scan Your Code Free