Custom instructions reference

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.

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

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.

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

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 files

Markdown links let instructions point to supporting files and URLs. Relative file links resolve from the instructions file. Linking to a document is not a guarantee that its contents are included in every request.

In Local, chat.includeReferencedInstructions Open in VS Code Open in VS Code Insiders controls automatic inclusion of referenced instructions and is off by default. Other harnesses use their native inclusion mechanisms. See Copilot file references and Claude instructions.

Keep essential rules in the instructions themselves. For a task that depends on a supporting document, attach that document or explicitly ask the agent to read it, and verify the resulting request or tool activity.

Manual attachment

Sessions that support instruction attachments offer Add Context > Instructions in the chat input. If that option isn't available, attach the Markdown file as ordinary file context and ask the agent to follow it for the current task. See attach instructions to one request.

Combine instruction sources

There is no precedence rule that applies across all harnesses.

• Copilot combines applicable user and repository instructions without a general precedence order between instruction files.
• Local can include multiple applicable instruction files. Avoid contradictory rules rather than relying on their order.
• Codex combines project instructions from the root toward the working directory, with more specific guidance later in the chain. Its native configuration also supports override files.
• Claude uses its own loading rules for user, project, and directory guidance.

For details, use the native documentation linked in supported formats. To resolve conflicting rules, change their sources and repeat a representative task.

Organization instructions

Organization instructions are managed on GitHub rather than in a repository file. Their availability depends on the client and feature, so don't assume that signing in makes them available to every harness.

Local has an organization instruction provider controlled by github.copilot.chat.organizationInstructions.enabled Open in VS Code Open in VS Code Insiders , which is on by default. Verify discovery for your account and session in the Agent Customizations editor.

For organization configuration and supported GitHub experiences, see organization custom instructions. Keep applicable organization and project guidance consistent.

Settings

Local harness settings

These settings control Local discovery and activation, not the native discovery rules of other harnesses:

For Claude instruction files, Local checks the workspace-root CLAUDE.md, .claude/CLAUDE.md, ~/.claude/CLAUDE.md, and CLAUDE.local.md. Add personal project files such as CLAUDE.local.md to .gitignore if they shouldn't be shared.

For defaults and additional configuration, see custom instruction settings. The additional-location setting is described separately under search locations.

Generated-content settings

Code review, commit message generation, and pull request description generation have separate settings. Each accepts an array of objects with either a text property for an inline rule or a file property for a Markdown file path.

Settings-based code generation and test generation instructions are deprecated. Use instruction files for those scenarios instead.

Related resources

• Use custom instructions to create and test project guidance.
• Migrate customizations when changing harnesses or storage locations.
• Debug instruction inclusion to inspect what reached the model.