Intermediate
How to create custom instructions file on GitHub Copilot
Quick Answer
Create a
.copilot-instructions.md file in your project root or workspace to provide custom context and coding preferences to GitHub Copilot. This file helps Copilot understand your project structure, coding standards, and specific requirements for better code suggestions.Prerequisites
- GitHub Copilot subscription
- Visual Studio Code with GitHub Copilot extension
- Basic understanding of file system navigation
- Knowledge of your preferred programming languages and frameworks
1
Create the instructions file in your project root
Navigate to your project's root directory and create a new file named
.copilot-instructions.md. This file should be placed at the same level as your package.json, README.md, or other main project files. Right-click in the file explorer and select New File, then name it exactly .copilot-instructions.md.Tip
The dot prefix makes this a hidden file on most systems, keeping your instructions private while allowing Copilot to access them.
2
Define your project context and architecture
Start your instructions file with a clear description of your project structure and architecture. Write a section titled
# Project Overview and describe your tech stack, main directories, and overall application purpose. Include information about your database schema, API structure, or any unique architectural patterns you're using.Tip
Be specific about folder structures and naming conventions to help Copilot suggest code in the right locations.
3
Specify coding standards and preferences
Add a
# Coding Standards section to define your preferred coding style, naming conventions, and formatting rules. Include details about indentation (tabs vs spaces), bracket placement, variable naming patterns (camelCase, snake_case), and any specific linting rules. Mention your preferred libraries or frameworks for common tasks.Tip
Include examples of well-formatted code snippets to demonstrate your preferred style.
4
Configure language-specific instructions
Create separate sections for each programming language you use, such as
# JavaScript Guidelines or # Python Standards. Specify preferred libraries, error handling patterns, async/await vs promises preferences, and any language-specific best practices. Include information about testing frameworks and documentation styles you prefer.Tip
Use code blocks with triple backticks to show examples of preferred patterns and anti-patterns.
5
Add security and performance guidelines
Include a
# Security & Performance section with specific requirements for data validation, authentication patterns, and performance considerations. Mention any security libraries you use, input sanitization requirements, and performance optimization strategies relevant to your project.Tip
Reference specific security vulnerabilities or performance bottlenecks you want Copilot to help avoid.
6
Set up environment and dependency preferences
Create an
# Environment Setup section that describes your development environment, preferred package managers, and dependency management strategies. Include information about environment variables, configuration files, and any specific build tools or deployment processes.Tip
Mention version constraints for dependencies to help Copilot suggest compatible code.
7
Test and refine your instructions
Save the
.copilot-instructions.md file and restart Visual Studio Code to ensure Copilot picks up the new instructions. Create a new file in your project and start coding to test if Copilot's suggestions align with your specified guidelines. Make adjustments to your instructions file based on the quality and relevance of suggestions.Tip
Monitor Copilot's suggestions over the next few coding sessions and update your instructions file as needed.
Troubleshooting
Copilot isn't following the custom instructions
Ensure your
.copilot-instructions.md file is in the project root and restart VS Code. Check that the file is properly formatted with clear markdown headers and that your instructions are specific rather than vague.Instructions file is too long and seems overwhelming
Keep your instructions concise and focus on the most important guidelines. Use bullet points and code examples rather than long paragraphs. Aim for 200-500 words total with clear sections.
Copilot suggestions don't match the specified coding style
Make your coding standards more explicit with concrete examples. Include both Do and Don't examples in code blocks to clearly demonstrate preferred patterns.
Multiple team members have different instruction preferences
Create a team-wide
.copilot-instructions.md file that reflects your shared coding standards and commit it to your repository. Ensure all team members pull the latest version and restart their editors.Ready to get started with GitHub Copilot?
Put this tutorial into practice. Visit GitHub Copilot and follow the steps above.
Visit GitHub Copilot →