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.

For how instructions compare with the other customization options, see Customization concepts.

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 Nested AGENTS.md files is experimental and might change or be removed.
  • Stored in the root of the workspace or in subfolders Nested AGENTS.md files is experimental and might change or be removed.

• Organization-level instructions

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

• CLAUDE.md file

  • For compatibility with Claude Code and other Claude-based tools
  • Stored in the workspace root, .claude folder, or user home directory

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, use Markdown links or the #file: syntax. Relative file paths resolve from the instructions file. To reference your environment user home folder, use ~, or start a path with ~/, such as [personal coding standards](~/copilot/coding-standards.md). Use Unix-style / path separators to keep instructions files portable across operating systems.

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. The following table lists the supported file locations for instructions files based on their scope.