Skip to content

GitHub Copilot Custom Instructions Complete Guide [February 2026 Update] Setup, Pricing, Best Practices

GitHub Copilot Complete Guide

Target Audience

  • Teams setting up Copilot for the first time through those looking to systematically review existing configurations

How to Read This Article

GoalSections to Read
First-time setupImplementation Method (Steps 1-3) > Checklist
Understand the systemInstruction System Overview > Design Patterns
Configuration referenceVS Code Settings / YAML Frontmatter
TroubleshootingCommon Issues / FAQ
Quick Start (5 Minutes)
# 1. Create the file
mkdir -p .github && touch .github/copilot-instructions.md

# 2. Add minimal content
cat << 'EOF' > .github/copilot-instructions.md
# Project Guidelines
- Language: TypeScript (strict mode)
- Formatter: Prettier + ESLint
- Test: Jest + React Testing Library
- Always use type hints
EOF

# 3. Verify
cat .github/copilot-instructions.md

After setup, open Copilot Chat and verify that copilot-instructions.md appears in the References section.

Key Points

  • Personalized AI Assistance

    Effectively guide Copilot with project-specific rules

  • Team Development Consistency

    Unified quality and style through shared guidelines

  • Enhanced Development Efficiency

    Accurate code generation without repetitive explanations

  • Documentation-Driven Development

    Clear guidelines accessible to both humans and AI

Instruction System Overview

GitHub Copilot instructions are composed of 4 layers + 2 extension mechanisms. This article focuses on "Repository-wide" and "Path-specific" from this structure.

graph TB
    P["<b>1. Personal</b><br>User settings in VS Code / GitHub.com"]
    O["<b>2. Organization</b><br>Admin settings for Business/Enterprise"]
    R["<b>3. Repository-wide</b><br><code>.github/copilot-instructions.md</code>"]:::focus
    PA["<b>4. Path-specific</b><br><code>.github/instructions/*.instructions.md + applyTo</code>"]:::focus

    P --> O --> R --> PA

    SK["<b>Agent Skills</b> (On-demand)<br><code>.github/skills/&lt;name&gt;/SKILL.md</code>"]:::ext
    AG["<b>AGENTS.md</b> (Cross-tool unified management)<br>AGENTS.md at project root"]:::ext

    R -.- SK
    R -.- AG

    classDef focus fill:#e1f5fe,stroke:#0288d1,stroke-width:2px
    classDef ext fill:#fff3e0,stroke:#f57c00,stroke-width:2px,stroke-dasharray:5 5

Scope of This Article

This article focuses on 3. Repository-wide and 4. Path-specific, highlighted in blue in the diagram above. For details on extension mechanisms: Agent Skills Guide / AGENTS.md Unified Management Guide

MechanismWhen AppliedTypical Use Cases
copilot-instructions.mdAlways (all requests)Coding conventions, tech stack
.instructions.md + applyToWhen file path matchesFrontend/backend-specific rules
Agent SkillsWhen agent determines it's neededTerraform review procedures, release procedures
AGENTS.mdOn agent startupProject-wide policies (shared across multiple tools)

Guidelines for Choosing

  • Rules you always want applied > copilot-instructions.md / .instructions.md
  • Procedures needed only for specific tasks > Agent Skills
  • Standardize across multiple AI tools > AGENTS.md
  • Detailed comparison: applyTo Pattern Guide

What is GitHub Copilot Custom Instructions

GitHub Copilot Custom Instructions is a feature that became fully practical in 2024, allowing you to pre-configure project-specific development policies and coding conventions for Copilot. This enables receiving project-appropriate code generation and suggestions without providing detailed instructions each time.

Instruction files are "READMEs for AI"

Key Updates for 2025-2026 (Click to Expand)

Feature Additions:

  • Agent Mode (Announced February 2025 / Rolled out to all users April 2025) - Automates multi-file editing, test execution, and verification
  • Multiple .instructions.md Support (July 2025) - Path-specific instructions via YAML Frontmatter
  • Copilot Spaces (GA September 24, 2025) - Integrated management of code, documents, and notes
  • Agent-Specific Instructions (November 2025) - Control application to specific agents via excludeAgent property
  • Code Review Integration - copilot-instructions.md now supported in code review

Models:

  • Latest supported models: Claude Opus 4.6 (GA February 5, 2026, 1M tokens), GPT-5.1 series, Gemini 3 Pro -- Supported Models List
  • Some Claude 3 series and GPT-4 series models scheduled for deprecation on February 17, 2026 -- GitHub Changelog

Pricing & Plans: See GitHub Copilot Comprehensive Guide - Pricing Section

Key Features

  • Repository-level unified rules via .github/copilot-instructions.md
  • File-specific application via .instructions.md + applyTo
  • Available in VS Code, Visual Studio, JetBrains IDEs, Neovim, GitHub.com, GitHub Mobile, and GitHub CLI
  • Same instructions utilized in Copilot Code Review

Context Size and File Design Best Practices

Related article

The technical rationale behind "why keep it concise" (how System Prompt injection works) is explained with diagrams in Instruction Injection Mechanism Explained.

The more focused, the more accurate

File Size Constraints and Recommendations

While GitHub Copilot has an expanded context window with new AI models (GPT-5.1, Claude Opus 4.6, Gemini 3 Pro), it's important to keep the custom instructions file itself concise.

Important File Size Guidelines

Directly writing large amounts of context in custom instruction files is not recommended. Instead, leveraging external document reference patterns enables efficient operation.

# ❌ Not Recommended: Direct large context description
Coding Standards:
1. Use camelCase for variables
2. Function names start with verbs
3. Use PascalCase for class names
4. Indent with 2 spaces
5. Use double quotes for string literals
6. Don't omit semicolons
... (extensive detailed conventions continue)

# ✅ Recommended: Leverage reference patterns
Refer to [coding-standards.md](/generative-ai/github-copilot/docs/coding-standards/) for coding conventions.
Follow [debugging-guide.md](/generative-ai/github-copilot/docs/debugging-guide/) for debugging procedures.
Check [api-design.md](/generative-ai/github-copilot/docs/api-design/) for API design policies.

Implementation Method with 2025 New Features

# Copilot generates with defaults — SQL injection vulnerability, no type hints
def get_user(id):
    query = f"SELECT * FROM users WHERE id = {id}"
    result = db.execute(query)
    return result
# ORM usage, type hints, docstring — all per instructions
def get_user(user_id: int) -> User | None:
    """Retrieve a user by ID.

    Args:
        user_id: The unique identifier for the user.

    Returns:
        User object if found, None otherwise.
    """
    return db.session.query(User).filter_by(id=user_id).first()

Step 1: Create Basic Files (Get Started Immediately)

# 1. Create basic directory
mkdir -p .github/instructions

# 2. Create main instruction file
touch .github/copilot-instructions.md

# 3. Create dedicated instruction files (New feature from July 2025)
touch .github/instructions/frontend.instructions.md
touch .github/instructions/backend.instructions.md
touch .github/instructions/testing.instructions.md
project-root/
├── .github/
│   ├── copilot-instructions.md      # Main custom instructions
│   ├── instructions/                # 🆕 Multiple instructions support
│   │   ├── frontend.instructions.md # Frontend-specific instructions
│   │   └── backend.instructions.md  # Backend-specific instructions
│   ├── agents/                      # 🆕 Agent definitions (New in 2025)
│   │   ├── test-agent.agent.md      # Test-specific agent
│   │   └── docs-agent.agent.md      # Documentation generation agent
│   └── skills/                      # 🆕 Agent Skills (December 2025~)
│       └── terraform-plan-review/
│           └── SKILL.md             # On-demand procedural knowledge
├── AGENTS.md                        # 🆕 Unified instructions for AI agents
├── docs/
│   ├── coding-standards.md          # Detailed coding standards
│   └── ...
└── README.md

About AGENTS.md

AGENTS.md is an open standard developed by the Linux Foundation / Agentic AI Foundation. It is a project instruction file that can be shared across multiple AI tools including GitHub Copilot, Claude Code, Cursor, and Gemini CLI.

Enabling in VS Code:

{
  "chat.useAgentsMdFile": true,
  "chat.useNestedAgentsMdFiles": true
}

Choosing between copilot-instructions.md and AGENTS.md:

  • copilot-instructions.md: GitHub Copilot exclusive, always applied
  • AGENTS.md: Multi-tool shared, referenced on agent startup

> Details: AGENTS.md Cross-Tool Unified Management Guide

About Agent Skills

Agent Skills are "procedural knowledge packages" that bundle SKILL.md with supporting resources in a folder. When placed in .github/skills/, agents load them only when needed to improve task accuracy.

While copilot-instructions.md / .instructions.md serve as "always-applied rules," Skills are positioned as "specialized capabilities that activate on-demand when conditions match."

> Details: GitHub Copilot Agent Skills Guide

Step 3: YAML Frontmatter Usage (February 2026 Version, Compatibility-Focused)

Differences Between VS Code and GitHub.com

  • VS Code: Can use name / description / applyTo as UI display and selection metadata
  • GitHub.com: Primarily references applyTo and excludeAgent
  • For multiple applyTo values, comma-separated format is recommended (per GitHub Docs)

frontend.instructions.md example:

---
# name/description are also available in VS Code (optional)
name: "Frontend instructions"
description: "React/TypeScript implementation rules (UI/state management/naming, etc.)"

# Application scope (comma-separated recommended per GitHub Docs)
applyTo: "src/components/**/*.ts,src/components/**/*.tsx"

# Optional: exclude specific agents (example)
# excludeAgent: "code-review"
---

# Frontend Development Instructions

## When Creating React Components
- Use TypeScript strict mode
- Always specify React Hooks dependency arrays
- Use PascalCase for component names

## Styling
- Use Tailwind CSS (avoid inline styles)
- Always implement responsive design

backend.instructions.md example:

---
# name/description are also available in VS Code (optional)
name: "Backend instructions"
description: "Node.js/Express backend development instructions"

# Application scope (comma-separated)
applyTo: "src/api/**/*.js,src/api/**/*.ts"

# Optional: exclude specific agents
# excludeAgent: "code-review"
---

# Backend Development Instructions

## When Creating API Endpoints
- Use Express Router
- Always implement error handling
- Comply with OpenAPI 3.0 specification

How to Specify applyTo

  • Use glob patterns; specify multiple values with comma separation
  • Use excludeAgent to exclude application to specific agents (coding-agent, code-review, etc.)

Copilot Chat-Assisted Instruction Generation

Manual Instruction Generation and Improvement

You can use Copilot Chat to get help creating and improving custom instructions.

# 1. Request custom instruction generation
# Execute the following prompt in Copilot Chat:
"@workspace Generate custom instructions for this repository based on the current codebase"

# 2. Request improvements for existing instructions
"@workspace Review and suggest improvements for our copilot-instructions.md"

# 3. Generate instructions specialized for a specific area
"Generate .instructions.md for frontend development based on our React components"

Main Instruction File Configuration Example (2025 Best Practices)

# Project Development Guidelines

## 🏗️ Technology Stack
- **Frontend**: Next.js 14 + TypeScript + Tailwind CSS
- **Backend**: Node.js + Express + Prisma ORM
- **Database**: PostgreSQL
- **Testing**: Jest + React Testing Library
- **Package Manager**: pnpm (npm/yarn prohibited)

## 📝 Coding Conventions (Important)
- JavaScript/TypeScript uses **double quotes** + **tab indentation**
- Variables/functions: camelCase
- Components: PascalCase
- Constants: UPPER_SNAKE_CASE

## 🔗 Detailed Document References
Refer to the following documents for details:
- [Detailed Coding Standards](/generative-ai/github-copilot/docs/coding-standards/)
- [API Design Guidelines](/generative-ai/github-copilot/docs/api-design/)
- [Testing Strategy](/generative-ai/github-copilot/docs/testing-strategy/)

## ⚙️ Development Flow
1. Review design documents before feature implementation
2. Implement in TypeScript strict mode
3. Always create tests
4. Format code with ESLint + Prettier

Implementation Checklist (Get Started Immediately)

Basic Setup (Complete in 5 Minutes)

# 1. Create files
mkdir -p .github/instructions
echo "# プロジェクト開発ガイドライン" > .github/copilot-instructions.md

# 2. Add basic content
cat << EOF >> .github/copilot-instructions.md

## コーディング規約
- JavaScript/TypeScriptはダブルクォート使用
- インデントはタブまたはスペース2文字
- 変数名: camelCase、コンポーネント名: PascalCase

## 必須実装事項
- TypeScript strict モード使用
- エラーハンドリング必須実装
- テストコード作成必須
EOF

# 3. Add to Git and commit
git add .github/copilot-instructions.md
git commit -m "Add Copilot custom instructions"

Verifying Effectiveness

  1. Ask a question in VS Code Copilot Chat or GitHub.com Chat
  2. Check if .github/copilot-instructions.md appears in the References section (proof that it was applied)
  3. Verify that generated code follows the instructions
  4. Note: Custom instructions do not apply to code completions (inline suggestions)

Effective Instruction Design Patterns

1. Layered Reference Pattern

# Providing graduated detail levels

## Level 1: Immediately necessary information
- Technology: React 18 + TypeScript + Vite
- Package Manager: pnpm (npm/yarn prohibited)
- Code Formatter: Prettier + ESLint

## Level 2: Detailed Guidelines
- Detailed coding standards: [docs/detailed-coding-standards.md](/generative-ai/github-copilot/docs/detailed-coding-standards/)
- Architecture design: [docs/architecture-guide.md](/generative-ai/github-copilot/docs/architecture-guide/)

## Level 3: Special Case Handling
- Performance optimization: [docs/performance-guide.md](/generative-ai/github-copilot/docs/performance-guide/)
- Security guidelines: [docs/security-guidelines.md](/generative-ai/github-copilot/docs/security-guidelines/)

2. Role-Based Instructions

# Role-separated instructions

## Frontend Development
Refer to [./instructions/frontend.instructions.md](/generative-ai/github-copilot/instructions/frontend.instructions/) for frontend development details
# In Copilot Chat: you can specify with #file

## Backend Development
Refer to [./instructions/backend.instructions.md](/generative-ai/github-copilot/instructions/backend.instructions/) for backend development details
# In Copilot Chat: you can specify with #file

## DevOps & Infrastructure
Refer to [./instructions/devops.instructions.md](/generative-ai/github-copilot/instructions/devops.instructions/) for DevOps details
# In Copilot Chat: you can specify with #file

3. Context Separation Pattern

# Project-specific short-term context
- Current sprint goal: Authentication feature implementation
- Priority bugs: [docs/current-issues.md](/generative-ai/github-copilot/docs/current-issues/)

# Long-term project policies
- Product strategy: [docs/product-strategy.md](/generative-ai/github-copilot/docs/product-strategy/)
- Technical debt handling: [docs/technical-debt.md](/generative-ai/github-copilot/docs/technical-debt/)

Practical Usage Examples

Design for New Engineer Onboarding

The key is designing with the premise that "when an exceptionally talented new engineer joins, they can immediately understand the project background, development policies, and debugging procedures."

# New Engineer Onboarding

## 🚀 Essential Initial Reading
1. [Project Overview](/generative-ai/github-copilot/docs/project-overview/) - Complete project understanding in 10 minutes
2. [Development Environment Setup](/generative-ai/github-copilot/docs/setup-guide/) - Complete environment setup procedures
3. [Coding Standards](/generative-ai/github-copilot/docs/coding-standards/) - Minimum rules to follow

## 🔧 Daily Development References
- [Debugging Procedures](/generative-ai/github-copilot/docs/debugging-guide/) - Investigation methods when issues occur
- [Testing Methods](/generative-ai/github-copilot/docs/testing-guide/) - Local and CI testing procedures
- [Release Process](/generative-ai/github-copilot/docs/release-process/) - Deployment and release workflow

## 💬 Q&A References
- [FAQ](/generative-ai/github-copilot/docs/faq/) - Frequently asked questions and answers
- [Troubleshooting](/generative-ai/github-copilot/docs/troubleshooting/) - Known issues and solutions

Team Development Implementation Example

# Team Development Guidelines

## 🔄 Development Flow
1. Before implementation: Create [Feature Design Template](/generative-ai/github-copilot/docs/templates/feature-design/)
2. Code implementation: Follow [Coding Standards](/generative-ai/github-copilot/docs/coding-standards/)
3. Test creation: Based on [Testing Strategy](/generative-ai/github-copilot/docs/testing-strategy/)
4. Review request: Check [Review Guidelines](/generative-ai/github-copilot/docs/review-guidelines/)

## 🚨 Emergency Response
- Production incidents: [Incident Response Procedures](/generative-ai/github-copilot/docs/incident-response/)
- Security issues: [Security Incident Procedures](/generative-ai/github-copilot/docs/security-incident/)

Specific Examples and Anti-patterns

# Effective instruction examples

## Technology Choice Instructions
- Use Prisma ORM for database queries (avoid raw SQL)
- Use Zustand for state management (don't use Redux)
- Implement UI components based on shadcn/ui

## File Output Instructions
- Always specify target file names when outputting code
- When multiple files need changes, display them separately by file

## Error Handling Instructions
- Ask clear questions instead of guessing when uncertain
- Follow [Debug Guide](/generative-ai/github-copilot/docs/debugging-guide/) procedures when errors occur

## Reference Documents
- Detailed API specification: [api-spec.yaml](/generative-ai/github-copilot/docs/api-spec.yaml)
- Design system: [design-system.md](/generative-ai/github-copilot/docs/design-system/)

Anti-patterns to Avoid

# Problematic examples

## External Resource Dependencies (avoid)
- Refer to style guide at https://external-site.com/styleguide
- Follow styleguide.md in external my-org/my-repo repository

## Vague Instructions (avoid)
- "Answer in friendly colleague style"
- "Answer within 1000 characters"
- "Use words no longer than 12 characters"

## Context Overload (avoid)
Directly writing extensive coding standards, API specifications, design documents...

VS Code Configuration and Workflow Integration

Additional Configuration in settings.json (February 2026 Version)

Note on Deprecated Settings

github.copilot.chat.codeGeneration.instructions is marked as deprecated in VS Code Docs. Using instruction files is the recommended approach.

Recommended Configuration (Minimal):

{
  // Automatically loads .github/copilot-instructions.md
  "github.copilot.chat.codeGeneration.useInstructionFiles": true,

  // Search location for *.instructions.md (this is also the default)
  "chat.instructionsFilesLocations": {
    ".github/instructions": true
  }

  // Note: github.copilot.chat.codeGeneration.instructions is deprecated (avoid using)
}

Default Settings

The default for chat.instructionsFilesLocations is { ".github/instructions": true } (VS Code settings reference). Troubleshooting steps for when instruction files don't take effect (location, settings) are also documented in VS Code Docs.

Git Hook Integration

#!/bin/sh
# .git/hooks/pre-commit

# Check for custom instruction file changes
if git diff --cached --name-only | grep -q "copilot-instructions.md"; then
    echo "📝 Copilot instructions updated. Team notification recommended."
fi

Common Issues and Solutions (2025 Edition)

"Copilot Doesn't Reference Custom Instructions"

Causes and Solutions:

# 1. Verify file name and placement
ls -la .github/copilot-instructions.md
ls -la .github/instructions/*.instructions.md

# 2. Check YAML Frontmatter syntax
# Verify it's enclosed with --- and indentation is correct

# 3. Check file size (recommended: under 2KB)
wc -c .github/copilot-instructions.md

"Multiple .instructions.md Files Don't Work"

Using the July 2025 new feature:

# YAML Frontmatter at the beginning of the file is required
---
description: "Description text"
applyTo: "glob pattern for target files"
---

"Not Showing in References"

Verification Steps: 1. Ask a question in VS Code Copilot Chat 2. Check the "References" section 3. If the file doesn't appear in the list, there may be a syntax error

"Settings Differ Across Team Members"

Solution:

# Standardize settings via Git management
git add .github/copilot-instructions.md .github/instructions/
git commit -m "Standardize Copilot instructions across team"

# Can also be controlled via VS Code settings.json
{
  "github.copilot.chat.codeGeneration.useInstructionFiles": true
}

Effectiveness Measurement and Continuous Improvement (2025 Edition)

Improvement Using Auto-Generation Features

# Request improvement suggestions from Copilot
"@workspace Review and suggest improvements for our copilot-instructions.md based on recent code patterns"

# Regular review and updates (recommended monthly)
"@workspace Analyze recent commits and suggest updates to our custom instructions"

How to Verify Instruction Effectiveness

  1. Reference Check: Verify in the "References" section of Copilot Chat
  2. Response Quality: Regularly evaluate whether generated code follows instructions
  3. Team Feedback: Regularly collect usage impressions

Continuous Improvement Process

# Instruction Improvement Cycle

## Monthly Review
- [ ] Review improvement suggestions from Copilot
- [ ] Reflect new technologies and tools
- [ ] Collect team feedback

## Quarterly Review
- [ ] Reflect project policy changes
- [ ] Verify effectiveness of multiple .instructions.md files
- [ ] Optimize YAML Frontmatter settings

Summary: Effective Custom Instruction Strategy

Key Points

  1. Maintain Conciseness: Keep custom instruction files concise, manage details in external documents
  2. Leverage Reference Patterns: Efficiently reference documents using [file](path) and #file:path syntax
  3. Optimize for Both Humans and AI: Clarity that new engineers can understand
  4. Graduated Detail Levels: Hierarchical structure from immediately necessary information to detailed guidelines
  5. Continuous Improvement: Regular reviews and updates to adapt to project changes

Implementation Priority

  1. Basic Setup: Create .github/copilot-instructions.md
  2. Core Documents: Establish coding standards and debugging guides
  3. Reference Patterns: Design effective external document references
  4. Team Adoption: Share configurations and educate on usage methods
  5. Continuous Improvement: Establish regular review cycles

GitHub Copilot Custom Instructions is not just a configuration file, but an important tool for systematizing team development knowledge bases. When properly designed and operated, it can simultaneously achieve AI-assisted development efficiency and quality improvement.

Frequently Asked Questions (FAQ)

Q: Can copilot-instructions.md be shared across any IDE?

Yes, since it is placed in the .github/ directory of the GitHub repository, it can be used commonly across major IDEs supported by GitHub Copilot, such as VS Code, Visual Studio, and JetBrains IDEs.

Q: Which Copilot features do .instructions.md apply to?

It is effective in Copilot Chat and Agent Mode. It does not directly apply to inline code completion (Ghost Text), but it strongly influences code generation through Chat.

Q: Which takes precedence: personal settings or repository settings?

Basically, both contexts are considered, but if there is a conflict, the user's personal Custom Instructions settings tend to take precedence. However, if you want to enforce repository-specific rules, we recommend synchronizing settings within the team.