Skip to Content
IDEsOpenCodeRules

OpenCode rules and instruction cost

Every OpenCode turn resends rules: AGENTS.md, instructions files from opencode.json, and skill metadata in the skill tool description. Unlike MCP schemas, skill bodies load only when invoked — but metadata still costs input tokens every turn.

This page answers opencode agents.md, opencode instructions, and opencode rules trimming.

Hub: Tokenminning in OpenCode.

AGENTS.md from /init

Running /init in the TUI analyzes your project and generates AGENTS.md in the repo root (Intro ). Useful for onboarding — but the file resends on every turn until trimmed.

ActionToken effect
Run /init onceOne-time generation cost
Leave file verboseFull file on every message — dominant input tax
Trim to ~50 linesKeep structure pointers, drop duplicated style
Regenerate after driftShorter than manual patch-up over time

Prefer referencing linter configs and CONTRIBUTING.md over pasting style guides into AGENTS.md. See Prompt hygiene.

instructions array

Load additional rule files via instructions in opencode.json (Config ):

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

Glob patterns are supported — but each matched file adds input every turn:

{
  "instructions": [".cursor/rules/*.md"]
}

Avoid broad globs unless every matched file is essential. Prefer explicit paths over **/* patterns.

Config merges from remote (.well-known/opencode), global (~/.config/opencode/opencode.json), and project opencode.json — project wins on conflicts. Audit all layers for duplicate rules.

Skills metadata vs full load

Skills live in .opencode/skills/*/SKILL.md (and Claude-compatible paths). OpenCode lists <available_skills> in the skill tool description every turn; the full body loads only on skill({ name: "..." }) (Skills ).

PhaseContext cost
Every turnSkill name + description (metadata)
On skill() callFull SKILL.md body

Trim skill descriptions to 1–2 sentences. Disable skills on Plan if you only need them during Build:

{
  "agent": {
    "plan": {
      "permission": {
        "skill": {
          "*": "deny",
          "git-release": "allow"
        }
      }
    }
  }
}

Or disable the skill tool entirely on Plan:

{
  "agent": {
    "plan": {
      "tools": { "skill": false }
    }
  }
}

Claude-compatible paths

OpenCode also loads .claude/skills/ and ~/.claude/CLAUDE.md unless disabled. If you do not use Claude Code paths, turn them off via env vars (CLI env vars ):

export OPENCODE_DISABLE_CLAUDE_CODE_SKILLS=true
export OPENCODE_DISABLE_CLAUDE_CODE_PROMPT=true

Prevents duplicate skill metadata and prompt files from stacking on top of your OpenCode config.

Audit checklist

  1. Count lines in AGENTS.md — target under ~50 for routine work
  2. List instructions entries — remove globs you do not need every session
  3. Run opencode stats --days 7 before/after trimming (Token usage)
  4. Compare input-heavy vs output-heavy — rules problems show as input dominance
Last updated on
AgentsContext