Use custom instructions in VS Code

Custom instructions enable you to define common guidelines and rules that automatically influence how AI generates code and handles other development tasks. Instead of manually including context in every chat prompt, specify custom instructions in a Markdown file to ensure consistent AI responses that align with your coding practices and project requirements.

You can configure custom instructions to apply automatically to all chat requests or to specific files only. Alternatively, you can manually attach custom instructions to a specific chat prompt.

Types of instruction files

VS Code supports two categories of custom instructions. If you have multiple instruction files in your project, VS Code combines and adds them to the chat context, no specific order is guaranteed.

Always-on instructions

Always-on instructions are automatically included in every chat request. Use them for project-wide coding standards, architecture decisions, and conventions that apply to all code.

• A single .github/copilot-instructions.md file

  • Automatically applies to all chat requests in the workspace
  • Stored within the workspace

• One or more AGENTS.md files

  • Useful if you work with multiple AI agents in your workspace
  • Automatically applies to all chat requests in the workspace or to specific subfolders (experimental)
  • Stored in the root of the workspace or in subfolders (experimental)

• Organization-level instructions

  • Share instructions across multiple workspaces and repositories within a GitHub organization
  • Defined at the GitHub organization level

File-based instructions

File-based instructions are applied when files that the agent is working on match a specified pattern or if the description matches the current task. Use file-based instructions for language-specific conventions, framework patterns, or rules that only apply to certain parts of your codebase.

• One or more .instructions.md files
  • Conditionally apply instructions based on file type or location by using glob patterns
  • Stored in the workspace or user profile

To reference specific context in your instructions, such as files or URLs, you can use Markdown links.

Use a .github/copilot-instructions.md file

VS Code automatically detects a .github/copilot-instructions.md Markdown file in the root of your workspace and applies the instructions in this file to all chat requests within this workspace.

Use copilot-instructions.md for:

• Coding style and naming conventions that apply across the project
• Technology stack declarations and preferred libraries
• Architectural patterns to follow or avoid
• Security requirements and error handling approaches
• Documentation standards

Follow these steps to create a .github/copilot-instructions.md file in your workspace:

1. Create a .github/copilot-instructions.md file at the root of your workspace. If needed, create a .github directory first.

2. Describe your instructions in Markdown format. Keep them concise and focused for optimal results.

---
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

Use .instructions.md files

You can create file-based instructions with *.instructions.md Markdown files that are applied dynamically based on the files or tasks the agent is working on.

The agent determines which instructions files to apply based on the file patterns specified in the applyTo property in the instructions file header or semantic matching of the instruction description to the current task.

Use .instructions.md files for:

• Different conventions for frontend vs. backend code
• Language-specific guidelines in a monorepo
• Framework-specific patterns for specific modules
• Specialized rules for test files or documentation

Instructions file locations

You can define instructions for a specific workspace or at the user level, where they are applied across all your workspaces.

You can configure additional file locations for workspace instructions files with the

Instructions file format

Instructions files are Markdown files with the .instructions.md extension. The optional YAML frontmatter header controls when the instructions are applied:

The body contains the instructions in Markdown format. To reference agent tools, use the #tool:<tool-name> syntax (for example, #tool:githubRepo).

---
name: 'Python Standards'
description: 'Coding conventions for Python files'
applyTo: '**/*.py'
---
# Python coding standards
- Follow the PEP 8 style guide.
- Use type hints for all function signatures.
- Write docstrings for public functions.
- Use 4 spaces for indentation.

Create an instructions file

When you create 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 are available across multiple workspaces.

To create an instructions file:

1. In the Chat view, select Configure Chat (gear icon) > Chat Instructions, and then select New instruction file.

   

   Alternatively, use the Chat: New Instructions File command from the Command Palette (⇧⌘P (Windows, Linux Ctrl+Shift+P)).

2. Choose the location where to create the instructions file.

   • Workspace: create the instructions file in the .github/instructions folder of your workspace to only use it within that workspace. Add more instruction folders for your workspace with the

     chat.instructionsFilesLocations

     • Open in VS Code
     • Open in VS Code Insiders
     setting.

   • User profile: create the instructions files in the current profile folder to use it across all your workspaces.

3. Enter a file name for your instructions file. This is the default name that is used in the UI.

4. Author the custom instructions by using Markdown formatting.

   • Fill in the YAML frontmatter at the top of the file to configure the instructions' description, name, and when they apply.
   • Add instructions in the body of the file.

To modify an existing instructions file, in the Chat view, select Configure Chat (gear icon) > Chat Instructions, and then select an instructions file from the list. Alternatively, use the Chat: Configure Instructions command from the Command Palette (⇧⌘P (Windows, Linux Ctrl+Shift+P)) and select the instructions file from the Quick Pick.

---
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

---
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.

For more community-contributed examples, see the Awesome Copilot repository.

Use an AGENTS.md file

VS Code automatically detects an AGENTS.md Markdown file in the root of your workspace and applies the instructions in this file to all chat requests within this workspace. This is useful if you work with multiple AI agents in your workspace and want a single set of instructions recognized by all of them, or if you want subfolder-level instructions that apply to specific parts of a monorepo.

Use AGENTS.md when:

• You work with multiple AI coding agents and want a single set of instructions recognized by all of them
• You want subfolder-level instructions that apply to specific parts of a monorepo

To enable or disable support for AGENTS.md files, configure the

Use multiple AGENTS.md files (experimental)

Using multiple AGENTS.md files in subfolders is useful if you want to apply different instructions to different parts of your project. For example, you can have one AGENTS.md file for the frontend code and another for the backend code.

Use the experimental

When enabled, VS Code searches recursively in all subfolders of your workspace for AGENTS.md files and adds their relative path to the chat context. The agent can then decide which instructions to use based on the files being edited.

Generate custom instructions for your workspace

VS Code can analyze your workspace and generate always-on custom instructions that match your coding practices and project structure. These instructions then apply automatically to all chat requests in the workspace.

When you generate instructions, VS Code performs the following steps:

1. It discovers existing AI conventions in your workspace, such as copilot-instructions.md or AGENTS.md files.
2. It analyzes your project structure and coding patterns.
3. It generates comprehensive workspace instructions tailored to your project.

Use the /init slash command

The quickest way to prime your workspace with custom instructions is to type the /init slash command in the chat input box.

The /init command is implemented as a contributed prompt file, so you can customize its behavior by modifying the underlying prompt.

Use a command to generate instructions

To generate custom instructions for your workspace with a command:

1. In the Chat view, select Configure Chat (gear icon) > Generate Chat Instructions.

2. Review the generated instructions file and make any necessary edits.

Share custom instructions across teams

To share custom instructions across multiple workspaces and repositories within your GitHub organization, you can define them at the GitHub organization level.

VS Code automatically detects custom instructions defined at the organization level to which your account has access. These instructions are shown in the Chat Instructions menu alongside your personal and workspace instructions, and are automatically applied to all chat requests.

To enable discovery of organization-level custom instructions, set

Learn how you can add custom instructions for your organization in the GitHub documentation.

Sync user instructions files across devices

VS Code can sync your user instructions files across multiple devices by using Settings Sync.

To sync your user instructions files, enable Settings Sync for prompt and instruction files:

1. Make sure you have Settings Sync enabled.

2. Run Settings Sync: Configure from the Command Palette (⇧⌘P (Windows, Linux Ctrl+Shift+P)).

3. Select Prompts and Instructions from the list of settings to sync.

Specify custom instructions in settings

For specialized scenarios like code review or commit message generation, you can use VS Code settings to define custom instructions. For general coding instructions, use file-based instructions instead.

{
  "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" }
  ]
}

Instruction priority

When multiple types of custom instructions exist, they are all provided to the AI. Higher-priority instructions take precedence when conflicts occur:

1. Personal instructions (user-level, highest priority)
2. Repository instructions (.github/copilot-instructions.md or AGENTS.md)
3. Organization instructions (lowest priority)

Tips for writing effective instructions

• Keep your instructions short and self-contained. Each instruction should be a single, simple statement. If you need to provide multiple pieces of information, use multiple instructions.

• Include the reasoning behind rules. When instructions explain why a convention exists, the AI makes better decisions in edge cases. For example: "Use date-fns instead of moment.js — moment.js is deprecated and increases bundle size."

• Show preferred and avoided patterns with concrete code examples. The AI responds more effectively to examples than to abstract rules.

• Focus on non-obvious rules. Skip conventions that standard linters or formatters already enforce.

• For task or language-specific instructions, use multiple *.instructions.md files per topic and apply them selectively by using the applyTo property.

• Store project-specific instructions in your workspace to share them with other team members and include them in your version control.

• Reuse and reference instructions files in your prompt files and custom agents to keep them clean and focused, and to avoid duplicating instructions.

• Whitespace between instructions is ignored, so you can format instructions as a single paragraph, on separate lines, or separated by blank lines for legibility.

Frequently asked questions

Why is my instructions file not being applied?

If your instructions file is not being applied, check the following:

• Verify that your instructions file is in the correct location. A .github/copilot-instructions.md file must be in the .github folder at the root of your workspace. A *.instructions.md file must be in one of the folders specified in the

  chat.instructionsFilesLocations

  • Open in VS Code
  • Open in VS Code Insiders
  setting (default: .github/instructions) or in your user profile.

• For *.instructions.md files, check that the applyTo glob pattern matches the file you are working on. If no applyTo property is specified, the instructions file is not applied automatically. Verify the References section in the chat response to see which instructions files were used.

• Check that the relevant settings are enabled:

  chat.includeApplyingInstructions

  • Open in VS Code
  • Open in VS Code Insiders
  for pattern-based instructions,
  chat.includeReferencedInstructions

  • Open in VS Code
  • Open in VS Code Insiders
  for instructions referenced via Markdown links,
  chat.useAgentsMdFile

  • Open in VS Code
  • Open in VS Code Insiders
  for AGENTS.md files.

For advanced diagnostics, check language model requests in the Chat Debug view or debug the applyTo matching logic.

How do I know where a custom instruction file comes from?

Custom instruction files can come from different sources: built-in, user-defined in your profile, workspace-defined instructions in your current workspace, organization-level instructions, or extension-contributed instructions.

To identify the source of a custom instruction file:

1. Select Chat: Configure Instructions from the Command Palette (⇧⌘P (Windows, Linux Ctrl+Shift+P)).
2. Hover over the instruction file in the list. The source location is displayed in a tooltip.

Use the chat customization diagnostics view to see all loaded instruction files and any errors. Right-click in the Chat view and select Diagnostics. Learn more about troubleshooting AI in VS Code.

Related resources

• Use Agent Skills
• Create custom agents
• Community contributed instructions, prompts, and custom agents