> ## Documentation Index
> Fetch the complete documentation index at: https://opencode.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```text theme={null}
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.

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

### 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:

```jsonc title="opencode.jsonc" theme={null}
{
  "$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.

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

See [Config](/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.