Feat: Introduce agent-level configuration for instructions, resources, and MCP server in .md agent config file

[spoons-and-mirrors]

Summary

The agent markdown config files now support:

• Instructions files
• MCP servers
• Resources (new feature, presenting a resource file as a tool for the LLM to call)

Core Feature

• Extended agent configuration to support mcp, instructions, and resources fields
• Added Resource schema for specifying file resources with descriptions
• Implemented dynamic resource tool creation from file paths
• Added agent-specific MCP client management with AgentMCP module
• Enhanced system prompt loading to include agent-level instruction files

Steps to test it:

• Run npx openmodes install example at the root to install the agent file, its instructions and resources
• Run opencode with bun dev
• Press tab and select the "EXAMPLE" agent/mode
• Ask: echo the verbatim list of tools you have access to, and give me the magic words

Success should show:

• 3 repomix MCP tools out of 6 totals
• 1 resource_the_other_magic_word tool according to our resource file name
• Echo the first "magic word" supplied to the request through an instruction file
• Get the resource with a tool call and echo the second "magic word"

Opening avenues

This ties in with the https://openmodes.dev project I've been working on lately (https://github.com/spoons-and-mirrors/openmodes.dev) and with the openmodes CLI tool, creating a simple way to discovering and using agents in OC.

Agents being integral to our agentic coding experience, I believe this PR allows for a better UX all around.

[thdxr]

do you know what the difference between system prompt and instructions are?

[spoons-and-mirrors]

I believe there's virtually no difference in function, but "instructions" allow for a more concise and cleaner agent prompt by offloading detailed guidelines into modular, reusable rule files, right?

[mstibbard]

System prompt and instructions are the same thing, so the content (excl. frontmatter) in this md file is already providing the instructions. Is this proposing:

1. that a system prompt can have many other system prompts?
2. to prescribe which subagents a given agent can call?

[spoons-and-mirrors]

As explained above and discussed on discord, this just adds modularity and organizational QoL improvements over stuffing everything in the "Agent Prompt" - it is already supported in opencode.json, and makes sense to have it here as well.

Plus, if you are using multiple coding tools... as they all have their own (stupid/opiniated) way of loading instructions (eg: .cursor/rules/something.mdc, .github/instructions/something.instructions.md, etc...) you don't need to constantly shuffle instructions files around and can just read from any folder you like : less mindless duplication, more power to the user.

[2asoft]

Thank you for this change!

The per-agent instructions is rather useful by itself.
Being able to split out parts of the prompt in order to reuse in different agents means being able to specialize agents for certain tasks without writing the same instructions. For example, I have a devloop.md, and language or framework specific .md files with code examples and specifics for the language or framework. With this change, I can string together multiple of them into a language or framework specific subagent, which the plan or build or other primary agents can then instruct to write the code.
I am aware the same effect can be obtained by external templating tools, but there is non-negligible overhead associated with doing so.

With per-agent MCP configuration, these subagents would also gain access to tooling specific to their area of expertise -- eg a typescript expert that has access to examples and libraries and tooling for typescript and that only, same for golang, etc.

@thdxr sorry for pinging on a weekend, what would it take to merge this?

[snhsky]

+1 for this feature from me for instructions on a per-agent level

do you know what the difference between system prompt and instructions are?

I have been running into trouble with agents that create documentation files, but they don't read these files in future sessions (Just like a real dev!). The "instructions" feature documented here should be able to resolve this issue by mounting the produced README.md files or other docs to a .opencode/agent/my-agent.md definition without polluting the context of the more general plan and build agents. I think of it as a way to force an agent to read specific files at the beginning of a session

The work around I have currently is to port and continuously update the agent definition file itself. That works, but the ability to use a glob pattern to basically say "read all the markdown files in this specific directory tree" would act as a kind of memory for an agent who works on that part of the codebase