Custom instructions reference
AI agents: See llms.txt for documentation discovery and navigation. Documentation articles are also available as Markdown by appending .md to the article URL. Join VS Code at Microsoft Ignite or catch the sessions online. A year of VS Code, wrapped. Explore the highlights. Custom instructions reference View as Markdown Ask in VS Code Ask in VS Code Insiders Use this reference to look up instruction file formats, locations, activation rules, and settings for your agent harness.
For a first setup, examples, and verification steps, see Use custom instructions . Supported formats and locations The selected agent harness , not the language model, determines instruction support. The following table lists common project formats. Paths are relative to the repository root unless noted. Harness Project instructions Targeted instructions Copilot .github/copilot-instructions.md or AGENTS.md .github/instructions/**/*.instructions.md or nested AGENTS.md files Anthropic Claude CLAUDE.md or .claude/CLAUDE.md Markdown files in .claude/rules OpenAI Codex AGENTS.md AGENTS.md files along the path to the session's working directory Local The Local harness is deprecated and will be removed in February 2027.
Move your workflows to the Copilot harness before then. Learn more about Local harness deprecation . .github/copilot-instructions.md , AGENTS.md , or CLAUDE.md .github/instructions/**/*.instructions.md or Markdown files in .claude/rules AGENTS.md is a cross-agent instruction format. It is not a custom agent definition, and its discovery rules differ by harness. If your team uses multiple harnesses, choose a shared supported format where possible and keep any separate copies consistent.
Some harnesses support additional native formats. See the Copilot instruction locations , Claude instruction locations , and Codex instruction discovery for their runtime-specific rules. User instructions User instructions contain personal guidance across projects. ~ refers to the home directory on the machine where the agent runs. Harness Personal project-independent guidance Copilot ~/.copilot/copilot-instructions.md for general guidance; ~/.copilot/instructions/**/*.instructions.md for modular instructions Anthropic Claude ~/.claude/CLAUDE.md for general guidance; ~/.claude/rules for modular rules OpenAI Codex AGENTS.md in the Codex home directory, which defaults to ~/.codex Local The Local harness is deprecated and will be removed in February 2027.
Move your workflows to the Copilot harness before then. Learn more about Local harness deprecation . Instructions in the VS Code user profile, created through the Agent Customizations editor Harness user folders are separate from VS Code profile storage and don't roam through Settings Sync. To move existing profile instructions, see user customization migration . To sync Local profile instructions across devices, turn on Settings Sync , run Settings Sync: Configure from the Command Palette ( ⇧⌘P (Windows, Linux Ctrl+Shift+P ) ), and select Prompts and Instructions .
Additional search locations The editor searches instruction directories recursively, so .github/instructions can contain subfolders for languages, teams, or modules. The chat.instructionsFilesLocations Open in VS Code Open in VS Code Insiders setting adds search locations. It remains supported, and the editor forwards instructions from additional configured locations to Agent Host harnesses. Prefer native harness folders for portability: GitHub Copilot CLI and the GitHub Copilot app don't inherit editor settings.
See migrate configured locations . For Local sessions that open a subfolder of a repository, chat.useCustomizationsInParentRepositories Open in VS Code Open in VS Code Insiders enables discovery from the parent repository. This setting doesn't control other harnesses. See monorepo discovery . File syntax Project files such as .github/copilot-instructions.md , AGENTS.md , and CLAUDE.md contain Markdown instructions and don't require YAML frontmatter.
Instructions file fields An *.instructions.md file contains an optional YAML header between --- delimiters, followed by Markdown instructions: --- name : 'Python tests' description : 'Use when creating or updating Python tests.' applyTo : 'tests/**/*.py' --- Reuse fixtures from `tests/conftest.py` . Run `python -m pytest <test-file>` after changing a test. These fields describe the instruction format recognized by the editor.
Activation depends on the harness . Field Type Required Meaning name String No Display name in the UI. Defaults to the file name. description String No Describes the relevant task. In Local sessions, the agent can use it to decide whether to load the file on demand. applyTo String No One or more comma-separated glob patterns for matching files. Use ** for all files. There is no default pattern. For Local sessions, omitting both description and applyTo leaves the file available for manual attachment rather than automatic activation.
A description is not an additional condition that must match before applyTo takes effect. Files shared with other Copilot features can also use feature-specific fields such as excludeAgent . Check GitHub's instruction support reference and repository instruction configuration rather than assuming these fields switch the VS Code harness. Claude rules fields Markdown rules in .claude/rules use paths instead of applyTo : --- paths : - 'tests/**/*.py' --- Reuse fixtures from `tests/conftest.py` . paths is an array of glob patterns.
Omitting it makes the rule apply generally rather than restricting it to particular paths. Local also reads this format. See Claude rules for native harness behavior. Discovery and activation Discovery means a harness or the editor finds an instructions file. Inclusion means its contents become part of a request. Neither guarantees that the model follows every rule. File patterns For repository instruction files, patterns are relative to the workspace or project root, not the directory containing the instructions file.
Use / path separators across operating systems. Pattern Matches Does not match *.py app.py at the root src/app.py src/*.py src/app.py src/api/routes.py src/**/*.py src/app.py , src/api/routes.py tests/test_app.py tests/**/*.py tests/test_app.py , tests/unit/test_app.py src/app.py **/*.ts, **/*.tsx TypeScript and TSX files at any depth JavaScript files ** All files No files excluded by the pattern In Copilot sessions, applyTo targets files the agent works with.
In Local, matching file context can attach instructions automatically when chat.includeApplyingInstructions Open in VS Code Open in VS Code Insiders is on. Local can also offer instructions for on-demand loading based on their description. Don't use a description as a substitute for a pattern when you need file-scoped guidance. Nested project instructions Harness Nested-file behavior Copilot Discovers AGENTS.md at the repository root, working directory, intermediate directories, and along paths to files it works with.
Applicable instructions are combined. OpenAI Codex Builds an instruction chain from the project root to the session's working directory. To use instructions in a subfolder, start the session with that subfolder as its working directory. Local The Local harness is deprecated and will be removed in February 2027. Move your workflows to the Copilot harness before then. Learn more about Local harness deprecation . Workspace-root AGENTS.md is included when chat.useAgentsMdFile Open in VS Code Open in VS Code Insiders is on.
Nested files require both that setting and chat.useNestedAgentsMdFiles Open in VS Code Open in VS Code Insiders . Local nested-file discovery is experimental and off by default. When enabled, it lists nested files and their folder locations so the agent can load relevant instructions on demand. These Local settings don't change Copilot or Codex discovery. For Claude's directory-based loading, see Claude instruction discovery .
Reference other fil
The rest of this page is on the live site.