Notes
TL;DR: Just write your prompts directly in .github/copilot-instructions.md, for example:
## Project-specific Conventions
- Documentation and comments must be in **Chinese**; ensure consistency for all new content
Main Content
The following Chinese text is machine-translated. See the original at
Custom instructions allow you to define general guidelines and rules that automatically influence how AI generates code and performs other development tasks. Instead of manually adding context to every chat prompt, you can specify custom instructions via Markdown files to ensure AI responses align with your coding practices and project requirements.
You can configure custom instructions to be automatically applied to all chat requests or only specific files. Alternatively, you can manually attach custom instructions to specific chat prompts.
Note
Custom instructions are not considered for inline suggestions while typing in the editor.
Types of Instructions Files
VS Code supports several Markdown-based types of instruction files. If your project contains multiple types of instruction files, VS Code will merge them and add them to the chat context, though no specific order is guaranteed.
- A
.github/copilot-instructions.mdfile- Automatically applied to all chat requests within the workspace
- Stored within the workspace
- One or more
.instructions.mdfiles- Conditionally apply instructions using glob patterns based on file type or location
- Stored either in the workspace or in the user profile
- One or more
AGENTS.mdfiles- Useful if you’re using multiple AI agents within a workspace
- Automatically applied to all chat requests in the workspace or specific subfolders (experimental)
- Stored at the root or subfolders of the workspace (experimental)
Whitespace between instructions is ignored, so you can write instructions as a single paragraph, one per line, or separated by blank lines for readability.
To reference specific contexts such as files or URLs within instructions, use Markdown links.
Examples of Custom Instructions
The examples below demonstrate how to use custom instructions. For more community-contributed examples, see the Awesome Copilot repository.
Example: General Coding Standards
Markdown
---
applyTo: "**"
---
# Project general coding standards
## Naming Conventions
- Use PascalCase for component names, interfaces, and type aliases
- Use camelCase for variables, functions, and methods
- Prefix private class members with underscore (_)
- Use ALL_CAPS for constants
## Error Handling
- Use try/catch blocks for async operations
- Implement proper error boundaries in React components
- Always log errors with contextual information
Example: Language-Specific Coding Standards
Notice how these instructions reference the general coding guidelines file. You can separate instructions into multiple files to keep them organized and focused on specific topics.
Markdown
---
applyTo: "**/*.ts,**/*.tsx"
---
# Project coding standards for TypeScript and React
Apply the [general coding guidelines](./general-coding.instructions.md) to all code.
## TypeScript Guidelines
- Use TypeScript for all new code
- Follow functional programming principles where possible
- Use interfaces for data structures and type definitions
- Prefer immutable data (const, readonly)
- Use optional chaining (?.) and nullish coalescing (??) operators
## React Guidelines
- Use functional components with hooks
- Follow the React hooks rules (no conditional hooks)
- Use React.FC type for components with children
- Keep components small and focused
- Use CSS modules for component styling
Example: Documentation Writing Guidelines
You can create instruction files for different types of tasks, including non-development activities like writing documentation.
Markdown
---
applyTo: "docs/**/*.md"
---
# Project documentation writing guidelines
## General Guidelines
- Write clear and concise documentation.
- Use consistent terminology and style.
- Include code examples where applicable.
## Grammar
* Use present tense verbs (is, open) instead of past tense (was, opened).
* Write factual statements and direct commands. Avoid hypotheticals like "could" or "would".
* Use active voice where the subject performs the action.
* Write in second person (you) to speak directly to readers.
## Markdown Guidelines
- Use headings to organize content.
- Use bullet points for lists.
- Include links to related resources.
- Use code blocks for code snippets.
Using the .github/copilot-instructions.md file
Define a .github/copilot-instructions.md Markdown file at the root of your workspace to store custom instructions. VS Code automatically applies the instructions from this file to all chat requests within the workspace.
How to use the .github/copilot-instructions.md file:
- Enable the
github.copilot.chat.codeGeneration.useInstructionFilessetting. - Create a
.github/copilot-instructions.mdfile in your workspace root. Create a.githubdirectory first if needed. - Describe your instructions using natural language and Markdown formatting.
Note
GitHub Copilot also detects the.github/copilot-instructions.mdfile in Visual Studio and GitHub.com. If you have a workspace used in both VS Code and Visual Studio, you can use the same file to define custom instructions for both editors.
Using .instructions.md files
Instead of using a single instruction file for all chat requests, you can create multiple .instructions.md files that apply to specific file types or tasks. For example, you can create instruction files for different programming languages, frameworks, or project types.
By using the applyTo frontmatter property at the top of an instruction file, you can specify a glob pattern to automatically determine which files the instructions should apply to. Instruction files are typically used when creating or modifying files, but generally not for read operations.
Alternatively, you can manually attach an instruction file to a specific chat prompt via the “Add Context > Instructions” option in the chat view.
- Workspace instruction files: Available only within the workspace and stored in the workspace’s
.github/instructionsfolder. - User instruction files: Usable across multiple workspaces and stored in the current VS Code profile.
Instructions File Format
Instruction files are Markdown files with the .instructions.md extension and follow this structure:
Header (Optional)
The header uses YAML frontmatter format and includes the following fields:
Expand table
| Field | Description |
|---|---|
description |
A brief description of the instruction file. |
name |
The name of the instruction file, used in the UI. If not specified, the filename is used. |
applyTo |
An optional glob pattern defining which files the instructions should be automatically applied to, relative to the workspace root. Use ** to apply to all files. If no value is specified, the instructions won’t be applied automatically—you can still manually add them to chat requests. |
Body
The body of the instruction file contains the custom instructions sent to the LLM when the instructions are applied. Provide specific guidelines, rules, or other relevant information you want the AI to follow.
To reference agent tools within the body text, use #tool:<tool-name syntax. For example, to reference the githubRepo tool, use #tool:githubRepo.
Example:
Markdown
---
applyTo: "**/*.py"
---
# Project coding standards for Python
- Follow the PEP 8 style guide for Python.
- Always prioritize readability and clarity.
- Write clear and concise comments for each function.
- Ensure functions have descriptive names and include type hints.
- Maintain proper indentation (use 4 spaces for each level of indentation).
Create an instructions file
When creating an instructions file, choose whether to store it in your workspace or user profile. Workspace instructions files apply only to that workspace, while user instructions files can be used across multiple workspaces.
To create an instructions file:
- In the Chat view, select Configure Chat (gear icon) → Chat Instructions, then select New Instructions File.
Alternatively, use the Chat: New Instructions File command in the Command Palette (⇧⌘P). - Select where to create the instructions file:
- Workspace: Create the file in the
.github/instructionsfolder in your workspace to use it only within that workspace. Additional folders can be added via thechat.instructionsFilesLocationssetting. - User Profile: Create the file in your current profile folder to use it across all workspaces.
- Workspace: Create the file in the
- Enter a filename for your instructions file. This will be the default name used in the UI.
- Write custom instructions using Markdown format:
- Include a YAML front matter at the top of the file to configure description, name, and applicability conditions.
- Add instructions in the main body of the file.
To modify an existing instructions file, go to the Chat view, select Configure Chat (gear icon) → Chat Instructions, then pick a file from the list. Alternatively, use the Chat: Configure Instructions command in the Command Palette (⇧⌘P), and select the desired file from the quick pick menu.
Use an AGENTS.md file
If you’re using multiple AI agents in your workspace, you can define custom instructions for all agents using a AGENTS.md Markdown file located at the root of your workspace. VS Code automatically applies the instructions in this file to all chat requests within the workspace.
To enable or disable support for the AGENTS.md file, configure the chat.useAgentsMdFile setting.
Use multiple AGENTS.md files (experimental)
Using multiple AGENTS.md files in subfolders is helpful if you want to apply different instructions to different parts of your project. For instance, you could have one AGENTS.md file for frontend code and another for backend code.
Enable or disable support for nested AGENTS.md files in your workspace using the experimental setting chat.useNestedAgentsMdFiles.
When enabled, VS Code recursively searches all subfolders in the workspace for AGENTS.md files and adds their relative paths to the chat context. Agents can then decide which instructions to use based on the file being edited.
Tip
For folder-specific instructions, you can also use multiple
.instructions.mdfiles with differentapplyTopatterns to match folder structures.
Specify custom instructions in settings
You can configure custom instructions using VS Code user or workspace settings to meet specific scenario needs.
Expand table
| Instruction Type | Setting Name |
|---|---|
| Code Review | Use custom instructions in VS Code |
| Commit Message Generation | github.copilot.chat.commitMessageGeneration.instructions |
| Pull Request Title and Description Generation | github.copilot.chat.pullRequestDescriptionGeneration.instructions |
| Code Generation (deprecated)* | github.copilot.chat.codeGeneration.instructions |
| Test Generation (deprecated)* | github.copilot.chat.testGeneration.instructions |
* The codeGeneration and testGeneration settings have been deprecated since VS Code 1.102. We recommend using instructions files (.github/copilot-instructions.md or *.instructions.md) instead.
You can define custom instructions as plain text within the setting value (text property), or reference an external file in your workspace (file property).
The following snippet shows how to define a set of instructions in your settings.json file.
JSON
{
"github.copilot.chat.pullRequestDescriptionGeneration.instructions": [
{ "text": "Always include a list of key changes." }
],
"github.copilot.chat.reviewSelection.instructions": [
{ "file": "guidance/backend-review-guidelines.md" },
{ "file": "guidance/frontend-review-guidelines.md" }
]
}
Generate an instructions file for your workspace
VS Code can analyze your workspace and generate a .github/copilot-instructions.md file containing custom instructions tailored to your coding standards and project structure.
To generate an instructions file for your workspace:
- In the Chat view, select Configure Chat (gear icon) → Generate Chat Instructions.
- Review the generated instructions file and make any necessary edits.
Sync user instructions files across devices
VS Code can sync your user instructions files across multiple devices using the Settings Sync feature.
To sync your user instructions files, enable Settings Sync to include prompts and instructions:
- Make sure Settings Sync is enabled.
- Run Settings Sync: Configure via the Command Palette (⇧⌘P).
- Select Prompts and Instructions from the list of items to sync.
Tips for defining custom instructions
- Keep instructions short and self-contained. Each instruction should be a single, simple statement. If multiple points are needed, use separate instructions.
- For task- or language-specific instructions, use multiple
*.instructions.mdfiles per topic, selectively applying them using theapplyToproperty. - Store project-specific instructions in your workspace so they can be shared with team members and included in version control.
- Reuse and reference instructions files in your prompt files and custom agents to keep them clean and focused, avoiding duplication.