Skip to content

Agent-level instructions field in opencode.jsonc does not resolve file contents into system prompt #35512

Closed as not planned

Description

@silvertakana

Problem

The instructions array field inside an agent config block in opencode.jsonc does not resolve file paths into actual file content injected into the agent's system prompt.

Config Example

{
  "agent": {
    "my-agent": {
      "instructions": ["path/to/instructions.md"]
    }
  }
}

Expected Behavior

The contents of instructions.md should be composed into the agent's system prompt, same as how the top-level instructions field (outside agent blocks) behaves.

Actual Behavior

The V1->V2 config migration (packages/core/src/v1/config/migrate.ts -- migrateAgent()) puts info.options (which includes the instructions array via normalize() moving unknown keys to options) into request.body as opaque provider parameters. These are never resolved as file paths or injected into the system prompt.

Similarly, the V1 prompt field maps to V2 system via the migration, but the V2 runner populates agent.info.system from the agent definition file (the .md file with YAML frontmatter in ~/.config/opencode/agents/ or .opencode/agents/), not from the config file. This means:

  • Config-level prompt is silently overridden by the definition file
  • Config-level instructions goes to request.body and is never read

Workaround

Append supplementary instructions directly to the agent definition file (~/.config/opencode/agents/<name>.md). The body after the YAML frontmatter is the agent's system prompt.

Evidence

  • The InstructionContext system (packages/core/src/instruction-context.ts) only discovers AGENTS.md files by walking up from cwd -- it does not read the config's instructions field
  • The V2 ConfigV2.Agent schema (packages/core/src/config/agent.ts) has system: Schema.String but no instructions field
  • Testing confirms: setting prompt: "TEST_STRING" in config with an existing definition file -- agent does NOT see the string. Appending content to the definition file body -- agent sees it immediately.

Environment

  • OpenCode version: v1.17.x
  • OS: Windows 11

Activity

  1. github-actions commented on Sep 5, 2026

    @github-actions
    Contributor

    To stay organized issues are automatically closed after 60 days of no activity. If the issue is still relevant please open a new one.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

No labels
No labels

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions