A tiny always-visible router plus OpenCode references beats both a big AGENTS.md and skills alone

opencode.json — references advertise the central docs; only the descriptions are always in context

{
  "references": {
    "team-docs": {
      // identical filesystem at work: a common local path works
      "path": "/work/shared/team-docs",
      "description": "Use for Java source/build changes;
        team Java guidelines and build conventions."
    },
    "frontend-docs": {
      // or a Git repository reference for versioning/portability
      "repo": "git@git.internal:platform/team-docs.git",
      "description": "Use for frontend UI changes;
        includes accessibility requirements."
    }
  },
  "instructions": [
    // only genuinely mandatory, compact rules — always loaded
    "docs/mandatory-security-rules.md"
  ]
}

Project AGENTS.md — a tiny router, always loaded, never a copy of the docs

# Payments service
Spring Boot payments API; frontend in /web.

## Commands
Build: ./gradlew build   Test: ./gradlew check

## Routing
Follow the team guidelines before writing code:
- Java work: consult the @team-docs reference.
- Frontend work: consult @frontend-docs
  (accessibility rules are mandatory).
Never restate guidelines here; read the source docs.

Always loaded vs on demand

AGENTS.md and every file in instructions are combined into context on every turn. Reference descriptions and resolved paths are always advertised, but the referenced content loads only when the agent reads it. A path written conversationally inside AGENTS.md can work, but OpenCode does not automatically parse such references — configured references are the reliable route. Commit opencode.json or distribute it via managed bootstrap tooling.