How to Use Custom Instructions in VS Code with AGENTS.md and .instructions.md

Custom instructions tell the AI how you want code to be written. Instead of repeating the same conventions in every chat prompt, you write them once in a Markdown file and VS Code applies them automatically to every chat request.

Custom instructions do not affect inline code completions. They only shape chat responses and agent behavior.

There are three file types for custom instructions. Which one you pick depends on your workflow and team setup.

Instruction file types at a glance

Use a single copilot-instructions.md file for project-wide rules. Add .instructions.md files when different languages or folders need different rules. Use AGENTS.md when you want a portable format supported by VS Code and other compatible agents.

The current file locations and behavior are documented in the official VS Code custom instructions guide.

For creating reusable task templates (not rules), see /vscode/how-to-create-and-use-reusable-prompt-md-files-in-vs-code.

Set up a copilot-instructions.md file

This is the simplest way to start. Create one file and every chat request reads it.

Create the file

In your workspace root, create a folder named .github if it does not already exist. Inside it, create a file named copilot-instructions.md.

Write your instructions

Write instructions in Markdown. Keep each rule short and focused. Include the reason behind rules so the AI understands edge cases.

Here is a minimal example:

markdown

- Use TypeScript with strict mode. All new code must pass tsc --noEmit.
- Prefer date-fns over moment.js (deprecated, adds bundle size).
- API routes use try/catch with a standard error response shape.
- Name React components with PascalCase, files to match.
- Tests live in a __tests__ folder next to the code they test.

Verify it is working

Open the Chat view and ask: "What coding conventions should I follow in this project?" The AI should reference your instructions. If it does not, check that the file is at the exact path .github/copilot-instructions.md in your workspace root.

For other always-on formats, VS Code also supports AGENTS.md in the workspace root and CLAUDE.md for Claude compatibility. Their settings are chat.useAgentsMdFile and chat.useClaudeMdFile.

Set up file-based .instructions.md files

When you need different rules for different parts of your codebase, use .instructions.md files with applyTo patterns. The AI only reads the instructions that match the files you are working on.

File locations

You can organize files in subdirectories. For example:

text

.github/instructions/
  frontend/
    react.instructions.md
    accessibility.instructions.md
  backend/
    api-design.instructions.md
  testing/
    unit-tests.instructions.md

File format

Each file needs YAML frontmatter with an applyTo glob pattern and the instruction body in Markdown. The applyTo pattern uses glob syntax relative to the workspace root. Here is an example for Python files:

markdown

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

Use ** to match all files. If you omit applyTo, the instructions are not applied automatically. You can still attach them manually to a chat prompt.

Create an instructions file

Open the Chat view, select the gear icon for Configure Chat, go to the Instructions tab, and select New Instructions (Workspace) or New Instructions (User). Give it a name, fill in the frontmatter and body, and save.

Alternatively, run Chat: New Instructions File from the Command Palette.

You can also type /create-instruction in chat and describe the rule you want. The AI generates the file for you.

Generate instructions from your codebase

Type /init in the chat input. VS Code analyzes the workspace and drafts a workspace instruction file based on the conventions it finds.

Review the generated instructions before committing them. The AI may misunderstand conventions that are used inconsistently in your codebase.

For narrower instructions, use /create-instruction followed by a description. Example: "/create-instruction always use tabs and single quotes in this project." The AI asks clarifying questions and writes a targeted .instructions.md file.

Use nested AGENTS.md files (experimental)

Enable the chat.useNestedAgentsMdFiles setting to place AGENTS.md files in subfolders.

VS Code adds nested AGENTS.md file paths to the chat context. The agent decides which nested files are relevant to the request, so review the response references rather than assuming a subfolder file was applied.

This feature is experimental and may change.

Instruction priority

When multiple instruction sources conflict, the highest priority wins:

1. Personal (user-level .instructions.md files)
2. Repository (copilot-instructions.md, AGENTS.md, workspace .instructions.md)
3. Organization (GitHub org-level instructions)

All applicable instructions are sent to the AI. Higher-priority ones take precedence when they contradict lower-priority ones.

Tips for effective instructions

Keep instructions short. Each instruction should be one clear statement. Explain the reason behind rules: "Use date-fns instead of moment.js because moment.js is deprecated and increases bundle size" works better than "Do not use moment.js."

Show examples of preferred and avoided patterns. The AI responds better to concrete code examples than to abstract rules. Skip conventions that your linter or formatter already enforces. The AI does not need to be told to use Prettier.

Store project instructions in version control so your team shares the same conventions. If you use the same setup across machines, enable Settings Sync for prompts and instructions in your profile.

Troubleshooting

Instruction file not applying. Check that the file is in the correct location. A .instructions.md file must be in a folder listed in the chat.instructionsFilesLocations setting (default: .github/instructions). Verify that the applyTo pattern matches the files you are editing. Right-click in the Chat view and select Diagnostics to see loaded instructions and errors.

AGENTS.md is ignored. Enable chat.useAgentsMdFile in your settings. If the toggle is grayed out, your organization may manage this setting.

Instructions reference missing files. Use relative paths from the instruction file location. Markdown links to other files in the workspace are resolved automatically.

Instructions can also be referenced from prompt files and custom agents.

For dedicated personas with their own tool access, see /vscode/how-to-create-custom-agents-in-vs-code-with-agent-md-files.