Your AGENTS.md Is a Line Item, Not a README

AGENTS.md is not a README for the agent but a line item on every request, so the way to make an agent follow your rules is a shorter file where every line is an order you would otherwise type again tomorrow.

Rick Hightower

Cover image for “Your AGENTS.md Is a Line Item, Not a README” by Rick Hightower

OpenCode sends your instruction files on every step of every request. Cut them to the rules you would type again tomorrow, and move everything else to where it loads only when you need it.

The agent said the change was done and never ran the tests, even though your AGENTS.md mentions npm test on line 23 of sixty, and you are paying for all sixty lines on every request.

In this article: Day 5 of a 17-day guide. Start here writes a three-line AGENTS.md for Ticket Triage, commits it, and checks that a new OpenCode session quotes the rules word for word and runs the tests the first rule asks for. Going deeper explains where AGENTS.md sits in every request and what it costs, which instruction files OpenCode finds and when an edit reaches the model, three questions that cut a sixty-line generated file to three rules, the instructions array, references that put a folder in reach without putting it in the request, and three ways to share one set of rules with Claude Code.

Part 4 gave Ticket Triage its first opencode.jsonc, so the agent asks before most shell commands and can never push. Today gives the agent standing rules of its own, in a file it receives with every request.

Start here

By the end of today Ticket Triage has a three-line AGENTS.md, committed, and you have checked that a new OpenCode session receives its rules word for word and follows the first one.

Starting fresh or fell behind? Run git switch -C main opencode/day-04. This replaces your main with the end of Day 4; to keep your own work, run git branch my-backup first.

A file of rules the model receives every time

AGENTS.md is a plain Markdown file of instructions at the root of your project. Each time the agent needs a reply from the model, OpenCode sends a request: the agent's own instructions, the list of tools it may call, the conversation so far, and the text of your AGENTS.md. It does this on every request, in every session, before your prompt. The model does not have to open the file, and you do not have to mention it. If you have used Claude Code, AGENTS.md plays the role of CLAUDE.md.

Two consequences follow, and they shape everything you write in the file. First, a rule in AGENTS.md reaches every session, including one you start tomorrow, so the file is the place for anything you would otherwise type again. Second, every line goes out with every request, so a line that tells the model nothing useful still takes up room each time. A short file where every line is a rule beats a long file that describes the project.

Three questions for every line

Every line has to pass three questions, and a line that fails any of them goes.

  1. Would you type it again tomorrow if the file did not exist? A rule you would repeat in every session belongs in the file. A fact you would never think to mention does not.
  2. Can the model learn it from one read? "This project uses ES modules" is in package.json. "Tests live in test/" is one glob away, but one short line that saves a search on every task can stay.
  3. Is it a rule about this repository? "Write clean code" is true of every repository and changes nothing about this one.

A description of the project usually fails the second question, because the model reads package.json and the source the first time it looks. A line that says what to do, and when, usually passes all three.

Three lines for Ticket Triage

Ticket Triage needs three rules, and each one is an instruction rather than a description.

- Run `npm test` before you say a change is done, and report the result.
- Source lives in `src/` and tests in `test/` (Node's built-in runner with `node:assert/strict`).
- Ask before you edit anything under `.opencode/`.

Each line passes the three questions for a reason you can name.

  • The test rule has a trigger, "before you say a change is done," and an output, "report the result." In this series, done means a command ran and printed a result, and this line asks for exactly that.
  • The layout rule saves a search on every task, and it names the assertion style, so a new test matches the ones you wrote in Part 1.
  • The .opencode/ rule protects the folder where OpenCode keeps a project's own agents, commands, and plugins. It is guidance, not enforcement, because the model can still ignore it. The permission rules from Part 4 are the tool for enforcement.

Write the file and commit it

Start from a clean tree, so the commit holds only today's change.

cd ~/code/ticket-triage
git status --short

The command prints nothing, because Part 4 ended with a commit. Now write the file. cat > AGENTS.md <<'EOF' writes every line up to the closing EOF into AGENTS.md, and replaces the file if one is already there. wc -l counts the lines in a file.

cat > AGENTS.md <<'EOF'
- Run `npm test` before you say a change is done, and report the result.
- Source lives in `src/` and tests in `test/` (Node's built-in runner with `node:assert/strict`).
- Ask before you edit anything under `.opencode/`.
EOF
wc -l AGENTS.md

wc -l prints 3 AGENTS.md. If you tried /init in Part 1's Going deeper, you already had an AGENTS.md, and the command replaced it. Run git diff AGENTS.md to see what the draft said before you let it go; Going deeper explains why most of it was not worth keeping. Then commit, so every session and every teammate gets the same rules.

git add AGENTS.md
git commit -m "Add AGENTS.md with three rules"

Check that a new session receives the rules

Ask a new session to quote its rules without opening any file. The model is the one you connected in Part 1, google/gemini-4-hydrogen (tested on OpenCode 2.3.0 on November 16, 2026).

opencode run -m google/gemini-4-hydrogen "Without using any tool, quote the rules from your project instructions file, one per line, exactly as written. If you have none, answer NONE."

The output names the agent and the model, then prints your three lines.

> build · gemini-4-hydrogen
- Run `npm test` before you say a change is done, and report the result.
- Source lives in `src/` and tests in `test/` (Node's built-in runner with `node:assert/strict`).
- Ask before you edit anything under `.opencode/`.

No → Read line appears, because the agent did not open the file; OpenCode sent it with the request. Before AGENTS.md existed, the same prompt answered NONE. If your answer misses a line or words it differently, check cat AGENTS.md against the block above, and run the prompt again.

Put the first rule to work

Now ask for a small change, and do not mention the tests.

opencode run -m google/gemini-4-hydrogen "Add a test to test/classify.test.js: \"Where is my delivery? It has been two weeks\" should be classified as shipping."

Watch the tool calls as they appear. The agent reads the test file, the classifier, and package.json, shown as → Read lines, then edits the test file, shown as a ← Edit test/classify.test.js line followed by the diff. Then a $ npm test line appears: the agent ran the suite on its own, and Part 4's npm test * allow rule let it run without a question. In a run like this one, with no one to answer, a command that would ask is rejected instead, and the agent continues without it. The reply ends with the result: how many tests passed and how many failed.

The edit appends one test like this one, which is the version on the opencode/day-05 tag; your agent may name it differently.

test("delivery delay goes to shipping", () =>
  assert.equal(classify("Where is my delivery? It has been two weeks"), "shipping"))

Some models run the tests without being told. The rule turns that habit into a standing instruction for every session, and the quote check above is how you know the model received it.

Do not take the reply's word for the result. Run the suite yourself and check the tree.

npm test
git status --short

The summary shows one more test than before, and fail 0. git status --short lists one changed file, M test/classify.test.js. Commit it.

git add test/classify.test.js
git commit -m "Add the delivery test"

Today's win is two checks you ran yourself: a new session quoted your three rules word for word, and npm test printed fail 0 with the new test included.

You can stop here. Going deeper explains why this works and where it breaks.

Going deeper

This section is for readers who want the exact order of what OpenCode sends, where it finds instruction files and when an edit applies, how to measure what a line costs, the instructions array, references, and how to share one set of rules with Claude Code. It assumes you finished Start here in this part and in Parts 1 to 4.

The test that never ran

Picture the day without the three-line file. You ask the agent for one more test on Ticket Triage. "Where is my delivery? It has been two weeks" should land in shipping. The agent edits test/classify.test.js, replies "Added the test," and stops. It never runs npm test, even though your permission rules let it run npm test without asking. You run the suite yourself, and it does not even load: the new test is missing a closing parenthesis. The scenario is illustrative, but most developers who use a coding agent have watched one call a change done without checking.

The odd part is that your AGENTS.md mentions npm test. You open the file OpenCode's /init command drafted (the shortcut in Part 1's Going deeper, described in the 2.3.0 source as "guided AGENTS.md setup") and find it on line 23 of about sixty: "Tests use Node's built-in runner; run them with npm test." It describes the project. It does not tell the agent to do anything. It sits between a paragraph about ES modules the model could read from package.json and a directory list that one glob call would reproduce. All sixty lines went out with every request you sent this week.

The fix is not a longer file with more emphasis. It is a shorter file where every line is a rule. Going deeper covers the layer of context engineering you control most directly in OpenCode, the instruction files sent before your prompt, and cuts a real project's AGENTS.md from sixty lines to three.

Scene: a frustrated developer at a desk frowning at line 23 of a sixty-line AGENTS.md, a failed test run beside it, after the agent said the test was added without running it

The scene is the opening moment: a developer who has just found the only mention of npm test buried as a description in a long instruction file, with the six rows of every OpenCode request on the monitor as the reason the file matters.

Row four of every request

The OpenCode instructions page gives the order in which every session's opening is assembled. Read it with one question in mind: which rows do you write yourself?

1. Agent or provider system prompt
2. Code Mode tool guidance, when enabled
3. MCP server, reference, and skill guidance
4. Global and project AGENTS.md files, then configured instructions
5. Built-in date and environment context
6. Session-specific instruction entries supplied through the API

Rows 1, 2, and 5 belong to OpenCode. Row 3 grows as you add MCP servers, references, and skills, which Parts 11 and 13 do. Row 4 is entirely yours, and the docs add that "these sources are combined rather than used as overrides." Nothing in row 4 replaces anything else; it all ships.

The six sources OpenCode combines at the start of every request, with row 4 (AGENTS.md files, then configured instructions) highlighted as the one you write, feeding a request of about 5,900 input tokens on the first call, 18,247 with 56 personal skills

In the author's own test on OpenCode 2.3.0, on google/gemini-3.5-flash, a model Google's models page no longer lists, the first request in a near-empty sample project sent 18,247 input tokens before any work: the system prompt, the tool definitions, a short AGENTS.md, and the descriptions of the 56 personal skills in the author's home folder. With an empty home folder, the same request sends about 5,900 tokens (Part 6). A sixty-line file adds roughly 700 to 900 tokens on top, at about four characters per token, and with a warm prompt cache it is nearly free in dollars: OpenCode's Console price list prices Claude Sonnet 5.5's cached reads at $0.10 per million tokens. Three things make those lines expensive anyway.

  • It rides every step, not every prompt. Every step of a tool loop resends the opening, and the author's eleven measured sessions averaged about six steps per prompt. Warming pings, when you turn warming on, carry the file too. Subagents pay as well: in the author's 2.3.0 test, on google/gemini-3.5-flash-lite, a general child that answered a question from AGENTS.md sent 16,653 input tokens in its single request.
  • Compaction cannot touch it. Compaction "cannot create room when a request is mostly fixed instructions and tool schemas." No summary will ever reclaim a line in row 4.
  • Every line competes for attention. This one is judgment, not measurement. Sixty unranked lines give "run the tests" the same weight as "use descriptive variable names."

Infographic: every line rides every step. The 18,247-token opening measured on OpenCode 2.3.0 with 56 personal skills in view, about six steps per prompt, a subagent request of 16,653 tokens, and no relief from compaction

Every line in row 4 rides every step. In the author's tests, with 56 personal skills in view, a first request opened at 18,247 input tokens, prompts averaged about six steps that each resent the opening, and a subagent child paid 16,653 tokens for a single request that read AGENTS.md. Compaction has nothing in row 4 it can summarize away.

Where OpenCode finds instruction files

Before you cut anything, find out which files you are actually sending. OpenCode "loads the global file followed by every AGENTS.md from the current workspace directory toward the home directory." For a workspace outside your home directory, it stops at the project root. For a project at ~/code/ticket-triage, the stack looks like this.

~/.config/opencode/AGENTS.md        global, if it exists
~/code/AGENTS.md                    upward, if it exists
~/code/ticket-triage/AGENTS.md      current workspace

Every file in that list loads if it exists: the global file first, then the files from the workspace upward, closest first.

Gotcha: an AGENTS.md you left in ~/code/ during some experiment loads into every project below it, on every request, and nothing warns you. Check once for strays before you start trimming.

ls -l ~/.config/opencode/AGENTS.md ~/code/AGENTS.md 2>/dev/null

On a typical setup it prints nothing, and the project's own file is the whole stack. Each kind of source loads, and picks up edits, at its own moment, and the timing answers most "why is my rule ignored?" questions.

  • Global and workspace files load in every session, global first, into the opening of the request. An edit to either applies before the next request.
  • Nested AGENTS.md files below the workspace load only when the agent reads or lists that area, into session history. An edit is not detected after one loads, so the new text needs a new session.
  • instructions entries load after every AGENTS.md, in listed order. Local files update like AGENTS.md; URLs refresh only when configuration loads.

Instruction file stack: the global, workspace, and upward AGENTS.md files plus instructions entries load into the opening of every session and update before the next request, while a nested AGENTS.md joins session history only when the agent reads that area and needs a new session to pick up edits

Nested files let a monorepo keep per-package rules without paying for every package on every request: a session that never touches packages/web never pays for its file. And OpenCode "combines the files and does not resolve conflicts between them." If the global file says "use tabs" and the project file says "use two spaces," the model receives both and picks. Write deeper files to add detail, never to contradict.

Two more facts matter before you cut. Edit a global or upward file while a session runs, and "before the next model request, OpenCode detects the change and adds an instruction update before delivering pending input." You restart nothing. And the file name is fixed: "OpenCode V2 recognizes AGENTS.md only. It does not use CLAUDE.md as a fallback." A CLAUDE.md beside it is invisible to OpenCode, with no warning.

Three questions that cut the file

Start here gave the three questions every line has to pass. The flowchart puts them in order.

The three-question filter: a line survives only if you would type it again tomorrow, the model cannot learn it from one read, and it is a rule about this repository; a survivor is rewritten as an order with a trigger and an output

Run the questions over a typical generated draft. The excerpt below is illustrative, because /init output varies and this series has not recorded a 2.3.0 run, but your own draft probably has the same shape.

## Project overview
Ticket Triage is a small Node.js service that classifies support tickets
as `refund`, `shipping`, or `other`.

## Tech stack
- JavaScript with ES modules (`"type": "module"` in package.json)
- Node.js built-in test runner

## Testing
Tests use Node's built-in runner; run them with `npm test`.

## Code style
- Use descriptive variable names.
- Keep functions small and focused.

The overview and tech stack fail the second question: the model learns both from package.json and src/classify.js the first time it looks. The code style lines fail the third. The testing line is the interesting one. It holds the right fact in the wrong grammar, a description of how tests run rather than an order to run them. An agent can read it on every request and still stop without checking.

Replace the whole file with the three lines from Start here.

- Run `npm test` before you say a change is done, and report the result.
- Source lives in `src/` and tests in `test/` (Node's built-in runner with `node:assert/strict`).
- Ask before you edit anything under `.opencode/`.

Each line has a job.

  • The test rule turns the description into an order with a trigger ("before you say a change is done") and an output ("report the result").
  • The layout rule saves a search on every task and names the assertion style, so a new test matches the existing ones.
  • The .opencode/ rule protects the directory where agents, skills, and plugins live. It is guidance, not enforcement; a permission rule would enforce it.

Infographic: keep only lines that earn their place. The three questions as a process, a long description file beside three rules with triggers, and the three rules that survived for the sample project

The cut works as a checklist for any repository: ask the three questions of every line, replace descriptions with orders, and expect a handful of rules to survive. For the sample project, the survivors are the test rule, the layout rule, and the rule that guards .opencode/.

If you start from the opening, with a long draft and an open TUI session, the same fix shows how an edit reaches a running session. Leave the TUI session open and write the file from a second terminal, so the running session receives it as an instruction update.

cd ~/code/ticket-triage
cat > AGENTS.md <<'EOF'
- Run `npm test` before you say a change is done, and report the result.
- Source lives in `src/` and tests in `test/` (Node's built-in runner with `node:assert/strict`).
- Ask before you edit anything under `.opencode/`.
EOF
wc -l AGENTS.md

wc -l should report three lines. Back in the TUI, ask for the fix the opening needed.

Fix the delivery test you added in test/classify.test.js.

Sequence of an instruction update: you rewrite AGENTS.md from a second terminal, OpenCode detects the change before the next request and sends an instruction update ahead of your prompt, and the agent is expected to edit the test and then run npm test under the existing allow rule

Watch what happens after the edit: the agent should call the shell tool with npm test, which an npm test * allow rule runs with no prompt, and report the passing count instead of stopping at "Fixed." This series has not recorded this TUI run on 2.3.0; the opencode run check in Start here is the tested path. If it stops without a test run, check git diff AGENTS.md and look for a stray upward file that contradicts the rules. Then commit, so your teammates' agents get the same rules.

git add AGENTS.md test/classify.test.js
git commit -m "Cut AGENTS.md to three rules; fix the delivery test"

A test run in the reply is weak evidence on its own. In my test on November 16, 2026, google/gemini-4-hydrogen ran npm test after adding the Start here delivery test in two control runs with no AGENTS.md at all. The quote check in Start here is the direct evidence that the file arrived.

Measure the lines you removed

The four-characters-per-token estimate is a rule of thumb. For the real number, run the same prompt headless against the old file and the new one. git log --oneline -- AGENTS.md lists the commits that changed the file, and the older one goes in place of <commit>; with --format json, each step_finish event carries the step's token counts.

git show <commit>:AGENTS.md > AGENTS.md
opencode run --format json --archived "Reply with OK." | grep step_finish
git checkout -- AGENTS.md
opencode run --format json --archived "Reply with OK." | grep step_finish

For the first step_finish event of each run, add tokens.input, tokens.cache.read, and tokens.cache.write, because input counts only the tokens not served from cache. The difference between the two sums is what the deleted lines cost on every step.

The instructions array points at files you already maintain

Sometimes the rules already exist in a file your team keeps for humans, usually CONTRIBUTING.md. Copying them into AGENTS.md makes two copies that drift. The instructions array points OpenCode at the original.

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

The docs' own example shows every kind of entry. Relative paths and globs are searched from the workspace up to the project root, ~/ paths resolve from your home directory, absolute paths are used as written, and URLs are fetched when configuration loads, with a five-second timeout. Missing files are skipped without an error, so a typo fails silently.

Gotcha: an instructions entry costs exactly what pasting the file into AGENTS.md would cost, because it loads into row 4 on every request. A four-hundred-line CONTRIBUTING.md written for humans is a four-hundred-line AGENTS.md you still pay for, and a glob grows whenever someone adds a file. Point instructions at short files written as rules.

References put a folder in reach without putting it in the request

Why a crushed mug goes to shipping is a support policy, not a coding convention. Suppose the policies live in a sibling folder the support team maintains. You want the agent to read the damage policy when a routing question comes up, without every policy on every request. References, "named access to directories outside the current project," exist for exactly this. Create the folder with two short policy files.

mkdir -p ~/code/support-policies
printf '# Damage\nA damaged item is a shipping claim. If the customer asks for money back, it is a refund.\n' > ~/code/support-policies/damage.md
printf '# Refunds\nRefund requests always go to the refunds team, whatever else the ticket says.\n' > ~/code/support-policies/refunds.md
ls ~/code/support-policies

Now add a references block to Ticket Triage's opencode.jsonc, above the eight permission rules from Part 4 that are already there. Read the references entry and the permission rules that follow it, because the two decide what the agent may do with the folder.

{
  "$schema": "https://opencode.ai/config.json",

  // Named access to a folder outside the project. The description tells
  // agents when it is relevant; the folder's contents load only on request.
  "references": {  // ①
    "policies": {  // ②
      "path": "../support-policies",  // ③
      "description": "Support team routing policies. Use when deciding which category a ticket belongs in.",  // ④
    },
  },

  "permissions": [  // ⑤
    { "action": "external_directory", "resource": "*", "effect": "ask" },
    { "action": "shell", "resource": "*", "effect": "ask" },
    { "action": "shell", "resource": "git status *", "effect": "allow" },
    { "action": "shell", "resource": "git diff *", "effect": "allow" },
    { "action": "shell", "resource": "npm test *", "effect": "allow" },
    { "action": "shell", "resource": "git push *", "effect": "deny" },
    { "action": "*", "resource": "*.env*", "effect": "deny" },
    { "action": "*", "resource": "*.env.example", "effect": "allow" },
  ],
}

① The references block is the only addition in this chapter; everything around it is carried over.

② policies is the alias clients use to attach the reference, so it cannot be empty or contain /, \, whitespace, a backtick, or a comma.

③ A relative path resolves from the directory that holds the config file, which makes this the sibling folder ~/code/support-policies.

④ The description advertises the reference in agent instructions on every turn; without it, the model learns about the folder only when you attach it.

⑤ Part 4's eight permission rules follow unchanged, in order, because the last matching rule wins.

Note: The full extracted listing at code/opencode/part-5-every-turn/listings/01-opencode-config-references.jsonc holds the complete opencode.jsonc from this step.

The description is the part that costs you every turn, and the reason it is worth it: "References with a description appear in agent instructions with their alias and resolved path." The cost is one short line in row 3, not the folder.

Gotcha: the string shorthand is a trap for one character. "policies": "../support-policies" works, but a shorthand string is a local path "only when it starts with ., /, or ~." A bare "support-policies" is read as a Git repository.

Run opencode debug config to confirm the config loads. Attaching a reference gives the agent "a non-recursive listing of the root's immediate files and directories," not their contents, so you then name the file you want read.

Read damage.md in the attached policies reference. Does "The box showed up crushed and I want my money back" belong in refund or shipping, and does src/classify.js agree?

The first time the agent reads outside the project, the external_directory ask rule stops it for approval, because "References do not grant extra tool permissions." Approve it once. The answer should say refund, and that classify() agrees because its refund check runs first. Commit the config; the path is relative, so a teammate who keeps the policies repository beside the project gets the same alias.

What goes where

The deciding question for any text is whether it rides every request.

Decision flow for where knowledge belongs: rules go in AGENTS.md, rules already in a short file go in an instructions entry, material the agent should find on its own becomes a described reference, material you attach by hand becomes an undescribed reference, and a one-off file is an @ attachment

Table: Mechanism, What reaches the model, When, On every request. Rows: A line in AGENTS.md; An instructions entry; A reference with a description; A reference without a description; An @ file attachment.

Five mechanisms put text in front of an OpenCode model. The Mechanism column names each one, "What reaches the model" says what text arrives, "When" gives the moment, and "On every request" says whether you pay for it on every step.

  • A line in AGENTS.md sends the line itself in every session, on every request. Use it for rules you would repeat, such as the verification command.
  • An instructions entry sends the whole file, or every glob match, after AGENTS.md on every request. Use it for rules already in a short team file.
  • A reference with a description sends its alias, path, and description in row 3, one short line on every request. Use it for material the agent should find on its own.
  • A reference without a description sends nothing until you attach it, then only a root listing. Use it for material you attach by hand, such as an archive.
  • An @ file attachment sends the file's text only in the prompt you attach it to: right for "look at this now," wrong for a rule.

Infographic: pay every turn only for rules. Mechanisms that ride every request (AGENTS.md lines, instructions entries, one line per described reference) beside mechanisms that cost nothing until used (undescribed references and @ attachments)

The five mechanisms fall into two groups: the ones you pay for on every request and the ones you pay for only when you use them. Rules belong in the first column, and reference material belongs in the second.

One source of truth for OpenCode and Claude Code

Plenty of repositories serve both OpenCode and Claude Code users. A repository that keeps only CLAUDE.md gives OpenCode users no rules at all, and one that keeps two hand-maintained files will see them drift within a month. Pick one file as the source of truth and point the other tool at it. With a current Claude Code, a third way points nothing at all.

  • AGENTS.md only, no CLAUDE.md. Both tools read the same file. Claude Code reads AGENTS.md itself when no CLAUDE.md is in the working directory or above it, starting with v2.1.277 (September 18, 2026), and on Amazon Bedrock, Google Vertex AI, and Microsoft Foundry since 2.1.281. Choose this when every teammate runs a current Claude Code.
  • CLAUDE.md that imports @AGENTS.md. For a Claude Code older than 2.1.277, or for a few Claude-only rules on top of the shared ones. Make CLAUDE.md a one-line import, @AGENTS.md, using the @path syntax Claude Code supports. Claude Code loads the imported file in full and never reads AGENTS.md twice, and OpenCode reads AGENTS.md directly.
  • CLAUDE.md as the source. List it in OpenCode's instructions array, which accepts any relative path.
{
  "instructions": ["CLAUDE.md"],
}

The third form has one catch. The instructions page documents files, globs, and URLs and says nothing about expanding @ imports inside them, so assume any @path lines in your CLAUDE.md reach OpenCode as plain text, not as the files they name.

If you already use Claude Code: OpenCode reads none of CLAUDE.md, its @ imports (which Claude Code follows up to four hops deep), or .claude/rules/. V2 dropped the V1 CLAUDE.md fallback. Its nearest match for a path-scoped rule is a nested AGENTS.md. Skills in .claude/skills are the exception: OpenCode's skills page lists them as a compatibility source.

Do this today

Everyone

  • Repeat the check. Ask a new session to quote its rules, then run the suite yourself. The answer is your three lines, word for word, and the summary shows fail 0.

    opencode run -m google/gemini-4-hydrogen "Without using any tool, quote the rules from your project instructions file, one per line, exactly as written. If you have none, answer NONE."
    npm test
    
  • Start one habit: the second time you type an instruction, put it in the file. Apply the three questions, write it as a rule with a trigger, and commit it.

If you read Going deeper

  • Measure what you send now. Count the lines in your instruction files, check for strays upward and globally, and record a baseline request.

    wc -l AGENTS.md
    ls -l ~/.config/opencode/AGENTS.md ../AGENTS.md 2>/dev/null
    opencode run --format json --archived "Reply with OK." | grep step_finish
    
  • Cut AGENTS.md to the rules you would repeat. Apply the three questions to every line, rewrite descriptions as orders with a trigger, and re-run the baseline to compare the sum of tokens.input, tokens.cache.read, and tokens.cache.write.

  • Add an instructions entry only for a short rules file. If CONTRIBUTING.md is long and written for humans, skip it; you would pay for every line on every request.

  • Add one reference. Give it a local path starting with ., /, or ~ and a one-sentence description, attach it, and approve the external_directory ask when it appears.

  • Point your other tool at the same rules. Choose AGENTS.md alone (Claude Code 2.1.277 or later), @AGENTS.md in CLAUDE.md, or "instructions": ["CLAUDE.md"] in opencode.jsonc, and commit it.

Pay for rules, not for prose

The agent that skipped the tests was not ignoring you. It was reading sixty lines of description on every step, and the one sentence that mattered was phrased as a fact instead of an order. OpenCode delivered every line faithfully; the file just never asked for anything.

Treat AGENTS.md as a line item on every request. Keep the rules you would type again tomorrow, write each one with a trigger and an output, and move everything else to where it loads only when you need it: a reference, a short instructions file, or a single @ attachment.

Three good lines beat sixty polite ones, every turn.


This is Part 5 of "OpenCode, Day-to-Day," a 17-part guide to using OpenCode V2 as a daily, provider-neutral coding agent.