Documentation
Topics Overview Overview Linux macOS Windows VS Code for the Web Raspberry Pi Network Additional Components Uninstall VS Code Tutorial Copilot Quickstart User Interface Personalize VS Code Install Extensions Tips and Tricks Intro Videos Overview Setup Quickstart Overview Language Models Context Tools Agents Customization Trust & Safety Overview Agents Tutorial Agents Window Planning Memory Tools Subagents Local Agents Copilot CLI Cloud Agents Third-Party Agents Overview Chat Sessions Add Context Inline Chat Review Edits Checkpoints Artifacts Panel Debug Chat Interactions Prompt Examples Overview Instructions Prompt Files Custom Agents Agent Skills Language Models MCP Hooks Plugins Context Engineering Customize AI Test-Driven Development Edit Notebooks with AI Test with AI Test Web Apps with Browser Tools Debug with AI MCP Dev Guide OpenTelemetry Monitoring Inline Suggestions Smart Actions Best Practices Security Troubleshooting FAQ Cheat Sheet Settings Reference MCP Configuration Workspace Context Display Language Layout Keyboard Shortcuts Settings Settings Sync Extension Marketplace Extension Runtime Security Themes Profiles Overview Voice Interactions Command Line Interface Telemetry Basic Editing IntelliSense Code Navigation Refactoring Snippets Overview Multi-Root Workspaces Workspace Trust Tasks Debugging Debug Configuration Testing Port Forwarding Integrated Browser Overview Quickstart Staging & Committing Branches & Worktrees Repositories & Remotes Merge Conflicts Collaborate on GitHub Troubleshooting FAQ Getting Started Tutorial Terminal Basics Terminal Profiles Shell Integration Appearance Advanced Overview Enterprise Policies AI Settings Extensions Telemetry Updates Overview JavaScript JSON HTML Emmet CSS, SCSS and Less TypeScript Markdown PowerShell C++ Java PHP Python Julia R Ruby Rust Go T-SQL C# .NET Swift Working with JavaScript Node.js Tutorial Node.js Debugging Deploy Node.js Apps Browser Debugging Angular Tutorial React Tutorial Vue Tutorial Debugging Recipes Performance Profiling Extensions Tutorial Transpiling Editing Refactoring Debugging Quick Start Tutorial Run Python Code Editing Linting Formatting Debugging Environments Testing Python Interactive Django Tutorial FastAPI Tutorial Flask Tutorial Create Containers Deploy Python Apps Python in the Web Settings Reference Getting Started Navigate and Edit Refactoring Formatting and Linting Project Management Build Tools Run and Debug Testing Spring Boot Modernizing Java Apps Application Servers Deploy Java Apps GUI Applications Extensions FAQ Intro Videos GCC on Linux GCC on Windows GCC on Windows Subsystem for Linux Clang on macOS Microsoft C++ on Windows Build with CMake CMake Tools on Linux CMake Quick Start C++ Dev Tools for Copilot Editing and Navigating Debugging Configure Debugging Refactoring Settings Reference Configure IntelliSense Configure IntelliSense for Cross-Compiling FAQ Intro Videos Get Started Navigate and Edit IntelliCode Refactoring Formatting and Linting Project Management Build Tools Package Management Run and Debug Testing FAQ Overview Node.js Python ASP.NET Core Debug Docker Compose Registries Deploy to Azure Choose a Dev Environment Customize Develop with Kubernetes Tips and Tricks Overview Jupyter Notebooks Data Science Tutorial Python Interactive Data Wrangler Quick Start Data Wrangler PyTorch Support Azure Machine Learning Manage Jupyter Kernels Jupyter Notebooks on the Web Data Science in Microsoft Fabric Foundry Toolkit Overview Foundry Toolkit Copilot Tools Create Agents Models Playground Agent Builder Agent Inspector Evaluation Tool Catalog Fine-Tuning (Automated Setup) Fine-Tuning (Project Template) Model Conversion Tracing Profiling (Windows ML) FAQ File Structure Manual Model Conversion Manual Model Conversion on GPU Setup Environment Without Foundry Toolkit Template Project Migrating from Visualizer to Agent Inspector Overview Getting Started Resources View Deployment VS Code for the Web - Azure Containers Azure Kubernetes Service Kubernetes MongoDB Remote Debugging for Node.js Overview SSH Dev Containers Windows Subsystem for Linux GitHub Codespaces VS Code Server Tunnels SSH Tutorial WSL Tutorial Tips and Tricks FAQ Overview Tutorial Attach to Container Create Dev Container Advanced Containers devcontainer.json Dev Container CLI Tips and Tricks FAQ Default Keyboard Shortcuts Default Settings Substitution Variables Tasks SchemaOn this page there are 13 sections
Try this
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.
Use the Agent Customizations editor (Preview) to discover, create, and manage all your agent customizations in one place. Run Chat: Open Customizations from the Command Palette.
Custom instructions are not taken into account for inline suggestions as you type in the editor.
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
-
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, you can use Markdown links.
Which approach should you use? Start with a single .github/copilot-instructions.md file for project-wide coding standards. Add .instructions.md files when you need different rules for different file types or frameworks. Use AGENTS.md if you work with multiple AI agents in your workspace.
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:
-
Create a .github/copilot-instructions.md file at the root of your workspace. If needed, create a .github directory first.
-
Describe your instructions in Markdown format. Keep them concise and focused for optimal results.
VS Code also supports the use of an AGENTS.md file for always-on instructions.
The following example shows how to configure the instructions file locations to only allow workspace-level instructions:
--- 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:
Type /instructions in the chat input to quickly open the Configure Instructions and Rules menu.
-
In the Chat view, select Configure Chat (gear icon) to open the Agent Customizations editor and then select the Instructions tab.
-
Select New Instructions (Workspace) or New Instructions (User) from the dropdown, depending on where you want to store the instructions file.
Alternatively, use the Chat: New Instructions File command from the Command Palette (⇧⌘P (Windows, Linux Ctrl+Shift+P)).
-
Select the location and enter a file name for your instructions file. This is the default name that is used in the UI.
-
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.
You can modify existing instruction files by opening them in the Agent Customizations editor.
Generate an instructions file with AI
You can use AI to generate a targeted instructions file. Type /create-instruction in chat and describe the convention or guideline you want to enforce (for example, "always use tabs and single quotes in this project"). The agent asks clarifying questions and generates an .instructions.md file with the appropriate applyTo pattern and content.
You can also extract instructions from an ongoing conversation. For example, if you corrected the agent's import style during a chat session, ask "extract an instruction from this" to capture that correction as a project convention.
/create-instruction generates targeted, on-demand instruction files. To generate workspace-wide always-on instructions, use the /init command instead.
Notice how these instructions reference the general coding guidelines file. You can separate the instructions into multiple files to keep them organized and focused on specific topics.
--- 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 chat.useAgentsMdFile setting.
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 chat.useNestedAgentsMdFiles setting to enable or disable support for nested AGENTS.md files in your workspace.
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.
For folder-specific instructions, you can also use multiple .instructions.md files with different applyTo patterns that match the folder structure.
Use a CLAUDE.md file
VS Code automatically detects a CLAUDE.md file and applies it as always-on instructions, similar to AGENTS.md. This is useful if you use Claude Code or other Claude-based tools alongside VS Code and want a single set of instructions recognized by all of them.
VS Code searches for CLAUDE.md files in these locations:
| Workspace root | CLAUDE.md in the root of your workspace |
| .claude folder | .claude/CLAUDE.md in your workspace |
| User home | ~/.claude/CLAUDE.md for personal instructions across all projects |
| Local variant | CLAUDE.local.md for local-only instructions (not committed to version control) |
To enable or disable support for CLAUDE.md files, configure the chat.useClaudeMdFile setting.
For .claude/rules instructions files, VS Code uses a paths property instead of applyTo for glob patterns, following the Claude Rules format. The paths property accepts an array of glob patterns and defaults to ** (all files) when omitted.
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:
- It discovers existing AI conventions in your workspace, such as copilot-instructions.md or AGENTS.md files.
- It analyzes your project structure and coding patterns.
- It generates comprehensive workspace instructions tailored to your project.
To generate custom instructions for your workspace:
-
Type /init in the chat input box and press Enter.
-
Type /create-instructions, followed by a description of the instructions you want to generate.
-
In the Agent Customizations editor, select Generate Instructions from the dropdown.
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 github.copilot.chat.organizationInstructions.enabled to true.
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 and run Settings Sync: Configure from the Command Palette (⇧⌘P (Windows, Linux Ctrl+Shift+P)). Select Prompts and Instructions from the list of settings to sync.
Specify custom instructions in settings
Settings-based code generation and test generation instructions are deprecated as of VS Code 1.102. Use file-based instructions instead.
For code review, commit messages, and pull request descriptions, you can still use VS Code settings to define custom instructions. These settings accept an array of objects with either a text property (inline instruction) or a file property (path to a Markdown file).
| Code review | github.copilot.chat.reviewSelection.instructions |
| Commit messages | github.copilot.chat.commitMessageGeneration.instructions |
| Pull request descriptions | github.copilot.chat.pullRequestDescriptionGeneration.instructions |
Instruction priority
When multiple types of custom instructions exist, they are all provided to the AI. Higher-priority instructions take precedence when conflicts occur:
- Personal instructions (user-level, highest priority)
- Repository instructions (.github/copilot-instructions.md or AGENTS.md)
- 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 because 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?
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.
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 (or their subdirectories) specified in the chat.instructionsFilesLocations 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 for pattern-based instructions, chat.includeReferencedInstructions for instructions referenced via Markdown links, chat.useAgentsMdFile 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:
- Select Chat: Configure Instructions from the Command Palette (⇧⌘P (Windows, Linux Ctrl+Shift+P)).
- 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.