opencode-build
Skill0 starsChanged 6 days agoMITView on GitHub
Use when writing, changing or reviewing an opencode plugin (server, TUI, GUI or RPC part, Plugin.define, hooks, custom tools, package.json exports, loading from opencode.json), using @opencode/plugin, @opencode/sdk or @opencode/client, porting a v1 plugin (@opencode-ai/plugin), or unsure whether an opencode API is v1 or v2.
In this repository10 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- capturing-tk-screenshots-headlessSkill
- concept-parableSkill
- opencode-apiSkill
- opencode-cliSkill
- provider-onboardingSkill
- pygameturboSkill
- thonny-pluginSkill
- timestampSkill
The file
We split this skill into the rules it gives an agent
3 rules. About 0 are common, 1 is distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 34
When they disagree, the higher source wins.
- Very specific: line 56
Check that a plugin loads, without a model or your real config: python scripts/plugin_probe.py <plugin-dir> (needs the v2 CLI.
- Very specific: line 66
No cached page for it? The live Markdown of any docs page is its URL with the trailing / replaced by .md.
≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
opencode Build docs (v2)
Overview
opencode v2 replaced the v1 plugin API, and what you remember is probably v1
(v1 -> v2): @opencode-ai/plugin -> @opencode/plugin; exported async
function returning hooks -> Plugin.define({ id, setup(ctx) }); tool() ->
ctx.tool.transform; config "plugin" -> "plugins"; .opencode/plugin/ ->
.opencode/plugins/. Do not write opencode plugin code from memory. Look
it up first, in this order:
- Installed types (the authority for the version the project uses):
dist/promise/<area>.d.ts(tool.d.ts,plugin.d.ts,command.d.ts, ...) innode_modules/@opencode/plugin/, or in bun's cache~/.bun/install/cache/@opencode/plugin@<version>*/(Windows:%USERPROFILE%\.bun\install\cache\...). ERRATA.mdbeside this file: known mistakes in the docs below.references/: the v2 Build docs cached as Markdown. A pageX.mdmay have aX.local.mdbeside it: our additions to that page (Reference sections with the real type declarations, notes), written from the installed types. Read it with its page.
When they disagree, the higher source wins.
Which reference
| Task | Read |
Parts (server/TUI/GUI/RPC), package.json exports, loading, plugins config, publish | references/plugins.md |
| How opencode finds parts and checks a plugin's default export; dependencies of a by-path plugin; lazy loading; checking a plugin loaded | references/plugins.local.md |
Server part: setup(ctx), tools, hooks, transforms, agents, commands, MCP | references/plugins-server.md |
Type of ctx (Plugin.Context) and of each ctx.<domain>, and how they derive from the client | references/plugins-server.local.md |
| TUI part: commands, keymaps, slash commands, toasts, dialogs, routes, slots | references/plugins-cli.md |
| GUI part (Desktop panels, settings, main process) | references/plugins-gui.md |
GUI limits: no agent switch, Desktop picker vs server switchAgent, hiding app controls, user-only output | references/plugins-gui.local.md |
| Typed methods/events between parts and clients | references/plugins-rpc.md |
| Porting v1 code, or supporting v1 and v2 from one package | references/plugins-migrate-v1.md |
| What a v1+v2 package did on real opencode 1.18.29 and 2.2.6; V1 config key, CLIs, sharing code | references/plugins-migrate-v1.local.md |
| Effect API versions | references/plugins-effect.md, references/plugins-effect-rpc.md |
| Driving a running server from code | references/client.md, references/client-effect.md |
Type of the client object (OpenCodeClient): every group and method | references/client.local.md |
| Embedding opencode in your app | references/sdk.md, references/sdk-effect.md, references/sdk-cloudflare.md |
| What the Build section covers | references/intro.md |
Check that a plugin loads, without a model or your real config:
python scripts/plugin_probe.py <plugin-dir> (needs the v2 CLI; details in
its docstring and references/plugins.local.md "Load").
plugins-server.md (~1800 lines) and plugins-gui.md (~3700 lines) are
large: list their headings first (grep -n '^##' <file>), then read only the
section you need.
Keeping it current
- No cached page for it? The live Markdown of any docs page is its URL with
the trailing
/replaced by.md; the index ishttps://opencode.ai/docs/llms.txt. - Cite the page URL without
.md(it is inreferences/manifest.json). - Found a doc mistake (the docs contradict the installed types or real
behavior)? Add an entry to
ERRATA.mdwith your evidence. - Refreshing the downloaded pages, or writing or updating a
references/*.local.md(where it goes, its style, the scripts that print type declarations): readMAINTAINING.mdfirst. Never edit the downloaded pages.
Common mistakes
| Mistake | Fix |
| v1 imports or exported async function | import { Plugin } from "@opencode/plugin"; export default Plugin.define({ id, setup(ctx) { ... } }) |
Guessing an exports key | plugins.md "Parts" lists them (., ./tui, ./gui-experimental, ./rpc) |
editor.namespace() but no options.namespace on the tool (id stays un-prefixed; Code Mode shows tools.<name>()) | Pass options: { namespace } on every add; see ERRATA.md E01 |
Editing only event.result.content in execute.after (Code Mode returns output; MCP tools always set it) | Edit output too; see ERRATA.md E03 |
| Reading a whole 2000-line reference | Search headings, read one section |
| Trusting a reference over the installed types | Types win; record the conflict in ERRATA.md |
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.