Building with GitHub Copilot

Repository Custom Instructions: An Extra Layer of Context

In GitHub Copilot, different methods, layered on top of each other, allow you to assist the model in understanding your context better and constructing better prompts. We have already discussed implicit and explicit context, but there is another approach that can be very effective: custom instructions.

With custom instructions, you can shape how the generative AI behaves by setting clear preferences and development standards. These instructions act like a guidebook that helps the assistant understand your project's structure, coding conventions, general expectations, and more - without needing to repeat them every time you ask a question. Define once and reuse forever, that's the idea.

You can define these preferences in a simple Markdown file and choose whether they apply globally across all chats or only within specific files. You also have the option to attach them manually to individual requests when needed.

Here are the different types of custom instructions:

• Workspace global custom instruction file
• Specific targeted custom instruction files
• Model-level custom instructions

Workspace Global Custom Instruction File

A single custom instruction file is stored within the workspace called copilot-instructions.md, located under the .github folder (.github/copilot-instructions.md).

To use this feature, create the file .github/copilot-instructions.md in your project repository. In this file, you should add your instructions in natural language using Markdown syntax. For example, the following template can be used as a starting point:

## Project Overview


## Folder Structure


## Libraries and Frameworks


## Coding Standards


## UI guidelines


## Testing


## Error Handling and Logging


## Deployment and CI/CD


## Security Practices


## Shortcuts and Commands


## Additional Resources

You are free to customize this template and make it your own. You can also ask Copilot to create this file for you.

Use the Configure chat button in the top right corner of the chat panel, or use the shortcut Ctrl+Shift+P (or Cmd+Shift+P on Mac) -> Chat: Configure Instructions -> Generate Instructions.

When you delegate this task to Copilot, it will check if you have any existing instruction files using a regex (e.g., instructions|AGENT.md|AGENTS.md|CLAUDE.md|\.cursorrules|\.windsurfrules|\.clinerules|README.md,). If it finds any, it will use them as context to create a new one. If you don't have any, it will create a new file from scratch based on what it knows about your project.

Now, whenever you type a prompt, you'll notice that this file will be included in the context.

Specific Targeted Custom Instruction Files

One or more custom instruction files are stored under .github/instructions/ in your workspace or user data folder. These files use the -instructions.md naming convention and can target specific file types or patterns.

Just like the previous type of custom instructions, you can ask Copilot to create these files for you.

Use the Configure chat button in the top right corner of the chat panel, or use the shortcut Ctrl+Shift+P (or Cmd+Shift+P on Mac) -> Chat: Configure Instructions -> New Instruction File -> Choose the location (e.g., .github/instructions/) -> Name the file (e.g., python-instructions.md) -> Write your instructions.

These files can be stored in two locations:

• In your workspace
• In your system user data folder

Note: Depending on your OS, the user data folder is located in different places. For example, it can be located under ~/.config/Code/User/prompts/ on Linux.

These files are only used by Copilot Chat in "Chat" and "Edit" modes. They are not used in "Agent" mode (at the time of writing). This could be a bug (some other users reported the same issue) or a limitation of the Agent mode.

The following is an example of a custom instruction file for all Python files in a workspace:

---
applyTo: "**/*.py", "**/*.ipynb"
---

## General Guidelines
- Follow PEP 8 coding standards.
- Use type hints for all function signatures.
- Write docstrings for all functions and classes using the Google style.
- Ensure code is modular and reusable.
- Prioritize readability and maintainability over cleverness.

## Testing