Instructions

Instructions are privileged context that guide an agent throughout a session. V2 combines built-in context, discovered AGENTS.md files, and dynamic sources such as skill, reference, MCP, and session context into a durable instruction baseline.

AGENTS.md

Use AGENTS.md for persistent guidance such as build commands, architecture, code conventions, and verification requirements. Commit project files so the whole team receives the same instructions.

V2 loads:

1. The global file at $XDG_CONFIG_HOME/opencode/AGENTS.md, normally ~/.config/opencode/AGENTS.md.
2. Every AGENTS.md from the current Location up to and including the project root.

For example, when the Location is packages/web, OpenCode can load all three project files below:

my-project/
├── AGENTS.md
└── packages/
    ├── AGENTS.md
    └── web/
        └── AGENTS.md

The files are combined rather than selecting a single winner. They are rendered in this order: global, then project files from the Location toward the project root. OpenCode does not resolve conflicts between their contents, so keep broad guidance global and put scoped guidance in the relevant project directory.

If the Location is outside the project root, only the global file is loaded. Setting OPENCODE_DISABLE_PROJECT_CONFIG=1 also skips project AGENTS.md discovery but does not disable the global file.

Current V2 discovery only recognizes AGENTS.md. The CLAUDE.md fallback and related precedence described by older OpenCode documentation do not apply.

Nested instructions

An AGENTS.md below the Location is not part of the initial upward scan. When the read tool successfully reads a file or lists a directory, OpenCode discovers AGENTS.md files from that target upward to, but not including, the Location. It adds newly discovered files to the session in nearest-first order.

Each nested file is injected once per session and recorded in durable session history. Reading the same area again does not inject it again. Consequently, editing an already injected nested AGENTS.md does not replace its earlier session entry automatically; start a new session if the updated text must apply immediately.

Config entries

The V2 config schema accepts an instructions array of strings:

opencode.jsonc

{
  "$schema": "https://opencode.ai/config.json",
  "instructions": [
    "CONTRIBUTING.md",
    "docs/guidelines/*.md",
    "https://example.com/shared-instructions.md"
  ]
}

Configuration is loaded from global through project-local files. If more than one config defines instructions, the highest-precedence, closest config’s entire array is selected; arrays are not merged.

V2 currently parses and retains this field but does not resolve its entries into instruction sources. Local files, glob patterns, and HTTP or HTTPS URLs in instructions therefore do not reach the model yet. Use AGENTS.md for active V2 instructions. URL fetching and timeout behavior documented for V1 are not supported by the current V2 implementation.

See Config for config locations and general precedence.

Ordering

The selected agent or provider system prompt is sent first. OpenCode then sends the session’s instruction baseline, composed in this order:

1. Built-in environment and date context.
2. Ambient AGENTS.md discovery.
3. Available skill, reference, and MCP guidance.
4. Session-specific instruction entries supplied through the API.

These sources are combined; ordering is not an override mechanism. Nested AGENTS.md files discovered by reads are chronological session entries rather than part of the baseline.

Changes

Before each model step, V2 compares live instruction sources with what that session’s model was last told:

• A new or changed ambient AGENTS.md aggregate is announced as a system update that replaces the previous ambient aggregate.
• Removing all ambient files announces that the previous ambient instructions no longer apply.
• A temporary read or discovery failure preserves the session’s last known instructions instead of treating them as deleted. If no baseline exists yet, the first model step waits until required sources are available.
• Completed conversation compaction creates a fresh baseline from the current sources. Moving a session or committing a revert also resets its instruction checkpoint so the next step establishes a new baseline.

Updates are durable session history. OpenCode does not rewrite the original baseline on every change; it records the change so subsequent model steps see both the established baseline and the chronological update.