Skip to content

By using VS Code, you agree to its license and privacy statement. By using VS Code, you agree to License & Privacy.

Use custom instructions in VS Code

Custom instructions give an agent reusable guidance about your project, such as where to add code, which libraries to use, and which tests to run. Store this guidance in Markdown files instead of repeating it in every prompt, and share project instructions through source control.

Start with one convention the agent repeatedly misses. Create instructions in the Agent Customizations editor, then test their effect in a new chat before adding more targeted guidance. For supported locations, file syntax, and settings, see the Custom instructions reference.

Instructions guide the model. They don't guarantee compliance or replace tests, code review, or security controls. They don't apply to inline suggestions as you type.

Get started with project instructions

Open the repository root and select the agent harness you intend to use. The harness determines which instruction files it reads. Choosing a Claude model in a Copilot session, for example, doesn't switch to the Claude harness.

For this first setup, work in the current folder rather than a new worktree so the test session can access your uncommitted instructions.

Create project instructions

  1. Run Chat: Open Customizations from the Command Palette (⇧⌘P (Windows, Linux Ctrl+Shift+P)) to open the Agent Customizations editor and select the Instructions tab.

  2. To add a project instructions file, select + next to Workspace and choose the project instruction file offered for your harness, such as AGENTS.md or CLAUDE.md. The editor creates or opens the file in your workspace.

    If your repository already has a project instructions file, open it instead of creating a competing copy.

  3. Add a few specific rules that address the repeated problem. For example, a Node.js API project might use the following instructions. Replace the paths and test command with ones that work in your repository.

    # Project instructions

* Add HTTP handlers under `src/api/routes`.
* Keep database access in `src/repositories` so handlers remain independently testable.
* Add or update tests for behavior changes, and run `npm test -- <test-file>` for the affected tests.

  4. Save the file. No frontmatter is needed for these project instruction files.

Create the file directly

If you prefer to create the file outside the Agent Customizations editor, use a supported project instructions file for your harness. Paths below are relative to the repository root. Create missing folders as needed.

Harness Project instructions file
Copilot .github/copilot-instructions.md or AGENTS.md
Anthropic Claude CLAUDE.md
OpenAI Codex AGENTS.md
Local .github/copilot-instructions.md or AGENTS.md

Add your rules, save the file, and verify it as described below. AGENTS.md is a cross-agent format, not a Codex-only file. See supported formats before sharing one file across harnesses.

Verify your instructions

Test a small task where the rules affect the outcome. Use the same harness and repository throughout:

  1. Run Chat: Open Customizations from the Command Palette (⇧⌘P (Windows, Linux Ctrl+Shift+P)). Select Instructions and confirm that the file is listed. This checks discovery, not whether the agent follows the rules.
  2. Start a new chat so the test doesn't depend on guidance from the conversation that created the instructions.
  3. Ask for a small change without repeating the rules in the prompt. For the API example, ask the agent to add an endpoint using the project's existing patterns.
  4. Check the response's References section, where available, for the instructions file. If you need more detail, inspect the request in Agent Debug Logs.
  5. Review the changes and tool activity. For the example, check where the handler was added, how it accesses data, and whether the agent ran the relevant tests.

If the result meets your goal, review and commit the instructions file so your team can use it. If not, identify whether the file was discovered, included, or followed before adding more rules.

For a complete before-and-after comparison and team rollout workflow, follow Configure AI for your codebase.

How instructions apply

Scope and activation answer different questions. Scope determines where guidance is available and who shares it. Activation determines when that guidance is included in a request.

Scope Use it for
Workspace or repository Project conventions shared with contributors through source control
User Personal preferences across projects, in a location supported by your harness
Organization Centrally managed guidance for supported experiences

Start with project instructions for rules that apply broadly. Use targeted instructions for guidance needed only in part of your codebase.

Activation How it works
Project-wide The harness includes guidance from its project instruction files.
File pattern An .instructions.md file uses applyTo, or a Claude rules file uses paths, to match files the agent works with.
Task relevance In Local sessions, a description lets the agent decide whether to read an instructions file for the task. This is separate from pattern matching.
Manual Attach guidance for a particular request when automatic discovery or activation isn't appropriate.

An instruction file such as AGENTS.md provides guidance to an existing agent. It doesn't define a custom agent. For a reusable multi-step workflow rather than coding conventions or project context, consider an agent skill. Look for an existing skill in the Customization Marketplace before writing the workflow yourself. Keep repository-specific commands and conventions in your project instructions.

Apply instructions to specific files or tasks

Keep project-wide rules in your main instructions file. Add targeted guidance when, for example, tests need different conventions from application code. The following example scopes Python testing rules to a tests directory.

Start in the Agent Customizations editor with the intended harness selected. Use the steps for your harness below, then adapt the paths and rules to your project.

  1. Run Chat: Open Customizations from the Command Palette (⇧⌘P (Windows, Linux Ctrl+Shift+P)) and select Instructions.
  2. Select the + button next to Workspace and choose the action for a new instructions file, rather than a project-wide file such as AGENTS.md.
  3. Choose .github/instructions if prompted and enter python-tests as the file name.
  4. In the generated file, add the following frontmatter and instructions.

Use applyTo to specify which files the instructions apply to:

---
applyTo: 'tests/**/*.py'
---
# Python tests

* Reuse fixtures from `tests/conftest.py` instead of duplicating setup.
* Name tests `test_<behavior>_<condition>`.
* Run `python -m pytest <test-file>` after changing a test.

The pattern matches tests/test_api.py and tests/unit/test_api.py, but not src/api.py. It is relative to the workspace or project root, not the .github/instructions directory.

If you prefer to create the file directly, save it as .github/instructions/python-tests.instructions.md. Use separate .instructions.md files for guidance that applies to different languages, folders, or tasks.

In Local sessions, you can also add a description, such as 'Use when creating or updating Python tests.', for task-based discovery. The description is not an extra restriction on applyTo. The agent can load the file by relevance separately from pattern matching.

After creating the file:

  1. Save it and start a new chat with the same harness.
  2. Ask the agent to add or update a test in the matching directory.
  3. Verify inclusion and behavior. Check that the test follows the naming and fixture conventions and that the agent runs the test command.

For additional patterns and nested-file behavior, see instruction activation.

Attach instructions to one request

For a one-time requirement, put the guidance in your prompt rather than creating a shared rule.

To reuse an existing instructions file for one request, select Add Context (+ icon) in the chat input and select the file before sending the request.

Write effective instructions

Write rules that help the agent make project-specific decisions, rather than describing everything in the repository.

Instead of Write
Write good tests. Reuse fixtures from tests/conftest.py and run python -m pytest <test-file> after changing a test.
Follow the architecture. Keep database access in src/repositories so HTTP handlers remain independently testable.
Follow our style. Use the existing error type in src/errors.ts rather than returning an error string.
  • Keep rules concise. Use a short statement for each requirement and explain non-obvious constraints.
  • Prefer actionable details. Name the command, directory, library, or existing example the agent should use.
  • Avoid unnecessary context. Don't duplicate rules enforced by formatters or linters. Move specialized guidance out of the project-wide file.
  • Maintain instructions with the code. Review changes through source control and update rules when commands, architecture, or dependencies change.
  • Reference supporting documentation carefully. Use Markdown links with relative paths and / separators. A link doesn't guarantee that the document's contents reach the model. Check referenced-file behavior.

Resolve conflicting instructions

Keep shared requirements consistent across personal, repository, and organization guidance. Don't rely on a universal precedence order: combination rules differ by harness.

If a personal instruction requests one library and the repository requires another, remove or narrow the conflicting personal rule. Don't add another rule to compensate. Repeat the same representative task in a new chat after resolving the conflict.

Manage project and personal instructions

Return to Instructions in the Agent Customizations editor to find and edit existing instructions. To add personal instructions, select + next to User. Follow the prompts for a name and storage location supported by your harness, save the file, and verify it in a new chat with that harness.

Use user scope for personal preferences across projects. Don't put your individual response preferences in a shared project file unless your team wants them too. For locations and synchronization limits, see user instructions.

You can also distribute instructions as rule components in an agent plugin, alongside related agents, skills, or tools. Support depends on the selected harness and plugin format. Check plugin compatibility before sharing the bundle across clients.

Instruction formats and settings

Use the Custom instructions reference to look up:

Troubleshoot instructions

Identify the failure stage before changing your guidance:

What you observe What to check
The file isn't listed in the Customizations editor. Confirm the selected harness, file name, supported location, and whether the session uses the folder containing your changes.
The file is discovered but isn't included for the task. Check frontmatter errors and activation conditions. Test a matching file, or attach the instructions manually. For Local, check the applicable discovery settings.
The file is included but the result doesn't follow it. Check for contradictory or vague rules. Clarify one rule, repeat the task in a new chat, and compare the actual changes and tool activity.

The response's References section, where available, helps check inclusion, not compliance. For detailed evidence, follow instruction diagnostics. Prepare logging before reproducing the issue.

Related resources

11/4/2026