How to Configure GitHub Copilot Custom Instructions for Your Projects
An independent telemetry study shows that developer activity increases code output by 5.4% to 20.0% with context-aware AI tools. This guide demonstrates how to configure github copilot instructions for repository-wide and path-specific scopes, ensuring your assistant respects project boundaries.
Why Grounding Coding Assistants in Project Context Matters
The adoption of artificial intelligence in software development has transformed how teams write code, yet standard models still struggle with project-specific alignment. While vendor-backed trials report dramatic developer productivity gains from AI assistants, the BlueOptima 2025 study indicates that actual code output volume increases are far more modest, ranging between 5.4% and 20.0%. The difference highlights the necessity of customizing the assistant environment using templates that provide context. Without tailored context, an assistant generates code based on public defaults, requiring manual code corrections that waste developer hours.
To solve this context gap, developers must configure explicit workspace instructions. GitHub Copilot custom instructions are repository-wide or path-specific Markdown configurations that enforce style guides and coding conventions automatically. By establishing these rules, teams can ensure that the assistant adheres to local architecture design patterns, testing frameworks, and linting rules.
Addressing Context Misalignment in Standard AI Models
Standard AI models are trained on public code bases, meaning they do not know your private APIs or local libraries. When developers write code, they often use internal packages or specific configurations. When the coding assistant suggests completions, it defaults to the most common public packages, causing compilation or runtime errors. For example, if a team uses a specific database client, the assistant might suggest syntax for a different library. Providing repository-wide context resolves this mismatch.
The Value of Collaborative Coding Substrates
Coding assistants function inside the local IDE, but software development is a team sport. Keeping rules local to a single machine prevents other team members from sharing the same context. A unified, shared substrate ensures that all developers and AI agents collaborate under the same constraints. Teams can manage instructions in source control, or use shared workspace environments like Fast.io workspaces to coordinate humans and agents on the same files.
How to Write a GitHub Copilot Instructions File
Repository-wide custom instructions apply to all files and prompts within a workspace. GitHub Copilot supports repository-wide custom instructions stored in the .github/copilot-instructions.md file at the repository root. Once committed to your repository, this file applies to all repository contributors, ensuring that everyone on the team uses the same formatting and coding conventions.
The markdown structure of this file should be clean and declarative. Use headings to organize rules and bullet points to list specific requirements. The assistant reads this file on every interaction, so keeping the instructions direct and action-oriented improves code quality. To get started, developers can review the GitHub customization library for structured templates.
Here is a standard directory path and markdown structure for repository-wide custom instructions:
### Repository Guidelines
#### Code Conventions
- Write all backend logic in TypeScript using ES modules.
- Use explicit types for function parameters and return values.
#### Testing Guidelines
- Write unit tests for all public helper functions.
- Place tests in the __tests__ folder adjacent to the source file.
Steps for Creating the Main Instructions File
To add this file to your project, open your terminal and run mkdir -p .github to create the configuration directory at the root of your repository. Next, create the copilot-instructions.md file using your text editor or by running touch .github/copilot-instructions.md. Open the file and write your natural language instructions. Keep the directives clear, starting each point with an imperative verb.
Enforcing Shared Conventions Across Team Contributors
By committing the .github/copilot-instructions.md file to your Git repository, you distribute the rules to all project contributors. When a team member opens the workspace, their editor automatically loads these instructions. This setup ensures that both human developers and autonomous AI agents follow the same coding standards, minimizing styling conflicts during code reviews.
Configuring Path-Specific Scopes and Exclusion Parameters
While repository-wide rules apply globally, complex projects often require different instructions for frontend and backend code. Storing frontend rules in a global file can confuse the assistant when it writes backend logic. To solve this, developers can configure path-specific instructions. Path-specific instructions allow you to apply specific rules to only certain directories or files based on folder paths.
These configuration files must be stored under the .github/instructions/ folder. The file name must end with .instructions.md, such as .github/instructions/frontend.instructions.md. At the beginning of the file, you must include a YAML frontmatter block containing the applyTo keyword. The applyTo keyword uses standard glob syntax to specify the target files or folders.
Path-specific instructions are specified in NAME.instructions.md files under the .github/instructions directory. The configuration details can be found in the GitHub custom instructions documentation.
For example, to apply instructions to all TypeScript files in your frontend directory, use the following block:
---
applyTo: "frontend/**/*.ts,frontend/**/*.tsx"
excludeAgent: "code-review"
---
If a developer works on a file that matches the glob pattern, Copilot loads both the repository-wide instructions and the path-specific instructions.
Defining Glob Patterns for Folder Restrictions
Glob patterns provide granular control over where your rules apply. Using src/*.ts matches TypeScript files in the root of the source directory, while src/**/*.ts matches all TypeScript files recursively. You can separate multiple patterns with commas to apply the rules across different directories, ensuring that only relevant context is sent to the assistant.
Excluding AI Agents and Reviewers by Workflow Type
You can restrict custom instructions using the excludeAgent keyword in the frontmatter block. The accepted values are code-review and cloud-agent. If you set excludeAgent: \"code-review\", the instructions will only be loaded by Copilot cloud agent during task execution. Conversely, setting excludeAgent: \"cloud-agent\" limits the rules to Copilot code review, preventing agents from reading them during development tasks.
Best Practices for Token Optimization in Copilot Configurations
Every line of custom instructions consumes input tokens in the assistant's context window. Stuffing files with verbose guidelines, excessive explanations, or redundant rules can lead to high latency and fast context exhaustion. To maintain developer productivity, teams must optimize their custom instruction files for token consumption.
A key best practice is to keep global instruction files concise. Focus only on high-level, non-negotiable coding conventions. For language-specific or database-specific patterns, use path-specific instruction files. This modular design ensures that the assistant only loads context when editing files inside the matching folders, preventing prompt bloat.
Alongside modular files, developers should manage their active editor tabs. GitHub Copilot uses open tabs as context for its code completions. Keeping many files open sends unnecessary tokens to the model, diluting its attention. Limit active tabs to three or five files related to the task. For detailed information on configuring AI tools, you can read the Fast.io MCP Server guide or onboard using agent onboarding guidelines.
Preventing Prompt Stuffing and Managing Context Windows
Prompt stuffing occurs when developers add rules for every edge case to their instructions. This practice dilutes the attention mechanism of the large language model, causing it to ignore critical instructions. Keep rules short and direct. If a rule requires detailed examples, place them in a dedicated folder and reference them only when necessary.
IDE Management Tactics for Saving Token Overhead
To minimize token consumption, clear your chat panel history when switching tasks. Long conversation histories are sent with every new prompt, consuming significant input token overhead. Start fresh chats to reset the context. Highlighting specific code blocks also limits the context sent to the editor to only the selected text.
Coordinate coding conventions across your team
Establish a central workspace where your team and developer agents share code, notes, and instructions with version control and semantic indexing. Start your 14-day free trial.
Collaborative Context Management and Safe Workspace Handoffs
Managing custom instructions and project assets across team members requires a secure, version-controlled workspace. While developers can use local folders, AWS S3, or Google Drive to store configuration files and developer documents, these traditional systems function as passive storage blocks. They lack built-in semantic indexing, version histories, or unified interfaces that allow humans and AI agents to collaborate on the same files.
Fast.io provides an alternative by serving as an intelligent workspace platform. When you enable Intelligence Mode, files in the workspace are automatically indexed, allowing semantic search and RAG-powered chat through the Fast.io MCP server. This allows team members and autonomous agents to collaborate on the same files, keeping notes, schemas, and configurations synchronized. For example, developers can document database schemas or API guidelines in Collaborative Notes, which the assistant reads via the Fast.io Model Context Protocol.
For teams managing multiple agents and contributors, Fast.io allows developers to start project workspaces, execute coding tasks, and perform ownership transfer to a human teammate once the task is complete.
For example, if you need to query database tables or process unstructured files like invoices or contracts, you can use Fast.io Metadata Views to turn those documents into structured, queryable databases.
The Fast.io Starter plan costs $29 per month and provides 1 TB of storage with 300,000 monthly credits. The Business plan costs $99 per month for up to 20 seats, providing 10 TB of storage and 1.2 million credits. For larger organizations, the Growth plan costs $299 per month, offering 50 TB of storage and 4.5 million credits. Every organization starts with a 14-day free trial, which requires a credit card. There is no permanent free plan or free agent tier.
Avoiding Secret Leaks in Configured Repositories
Never write sensitive data, such as API keys, database passwords, or auth tokens, in custom instruction files. Because these files are committed to version control, hardcoding secrets can expose your project credentials. Instead, configure your environment variables locally and reference them in your build configuration, preventing secret leaks.
Maintaining Chain of Custody with Version History
When autonomous agents make edits to configuration files, tracking revisions is important for system stability. Fast.io maintains a detailed, per-file version history and an append-only audit log. If an agent writes an incorrect instruction or corrupts a workspace setting, developers can view the exact changes and restore the previous version from the workspace interface.
Frequently Asked Questions
How do I add custom instructions to GitHub Copilot?
To add custom instructions for repository-wide use, create a markdown file named copilot-instructions.md inside the .github directory at the root of your project. For path-specific configurations, place files ending in .instructions.md under the .github/instructions directory and declare the files they apply to in the applyTo frontmatter block.
Where is the copilot-instructions.md file located?
The copilot-instructions.md file must be located in the .github directory at the absolute root of your repository path, resulting in the relative file path .github/copilot-instructions.md. Committing this file to your version control system ensures that the rules are shared automatically among all repository contributors.
How do I restrict Copilot instructions to a folder?
To restrict custom instructions to a specific folder or directory, create a path-specific configuration file inside the .github/instructions directory, such as .github/instructions/frontend.instructions.md. At the beginning of this file, declare a frontmatter block with the applyTo key pointing to a glob pattern that matches only your target folder, such as app/javascript/**/*.
Related Resources
Coordinate coding conventions across your team
Establish a central workspace where your team and developer agents share code, notes, and instructions with version control and semantic indexing. Start your 14-day free trial.