Opencode concepts

This is a draft post.

Expect this to be incomplete, inaccurate or both.

The tooling around agentic coding is rapidly evolving field. At the moment of this writing, my tool of choice is OpenCode [blocked] which supports a few different mechanisms to interact with the agents.

I put together this quick guide to help me decide when to use each of those mechanisms.

Rules

Custom instructions that get automatically loaded at the beginning of every session.

They are created by writing an AGENTS.md file. No need to include metadata (i.e. frontmatter) in it.

You can have a global AGENTS.md file that affects all of your projects and individual ones in each of your projects. Both will be combined.

Tools

External programs the agent can execute.

They are usually grouped so as to make it easier to assign permissions. A bunch of predefined tool groups are already built-in in opencode (bash, webfetch, edit, ...).

Users can define their own functions by creating simple JS or TS modules that can be used to execute any logic (including scripts executables written in other languages) and placing them in a tools folder. OpenCode docs do a very good job at explaining the details.

It is possible to restrict access to different tools to different agent

Tools are not invoked explicitly. The agent has access to them and decides when to use them. Some agents are better than others at deciding when and how to use a tool, which can make a big difference in the results you get.

Commands

Mostly a saved prompt.

You can, optionally, add the provider/model combo that you want be used to run it. Otherwise Opencode will fallback to your currently selected provider/model.

Overriding the provider/model is a good option when you know a specific model is especially good at the given task, or if the task is simple enough that a less expensive or faster model is enough.

They avoid having to repeat yourself and save you typing. They are most useful for frequent tasks. They support arguments with a very simple syntax.

I use them for things like committing, raising a PR or fixing errors in the CI pipeline.

Commands are invoked by typing / followed by the name of the command.

It is possible to specify which (#agents) should execute the command. This can be useful if you want to use the same configuration (model, provider, permissions) as an already defined agent. That also includes subagents

Here are the official docs [blocked].

Agents

A full configuration combo. It can include all of the following:

A prompt
A model configuration: model, provider, temperature.
Tools: what tools the model is allowed to use or which ones are forbidden or require the model to ask for permission every time
Max Steps: A way to limit the number of steps the agent can take when trying to solve the task.
Mode: primary|subagent|all whether the agent can be called as primary agent, a subagent or both. Defaults to all.
Hidden: a boolean. If true the subagent will be hidden from the subagents menu and it will only be accessible via the task tool.

Primary agents

Opencode makes it easy to switch between agents with the TAB key.

Opencode includes two built-in primary agents plan and build. You can customise them and you can create your own too.

Subagents

Subagents are specialised agents that primary agents can automatically call for specific tasks.

Useful: Primary agents and subagents are defined in the same way.

Skills

What are skills? Skills are reusable capabilities for AI agents. They provide procedural knowledge that helps agents accomplish specific tasks more effectively. Skills can include code generation patterns, domain expertise, tool integrations, and more.