OpenCode Plugin Creator
Use opencode-agent-creator for agent definitions, permissions, and task delegation. Keep plugin mechanics here.
Match the host before coding
Record opencode --version and the installed @opencode-ai/plugin version. This skill's template targets OpenCode 1.18.35, tag commit 53d1eabb61e21162157817bf677da0a4ad3332e3.
Choose the API from the target package's exports and types. The released root import uses a Plugin function returning Hooks; its V2 Promise/Effect exports are different APIs. Current V2 documentation can describe fields absent from 1.18.35. Do not mix its examples into a V1 hook object.
For terminal UI behavior, load the official CLI-plugin guide and the target host's @opencode-ai/plugin/tui types. Use its distinct TUI entrypoint/API and package ./tui export; match the guide's imports to the installed version rather than using server hooks for UI work.
Build and verify
- Load references/hooks.md when choosing an entrypoint or interception hook; check its host call site as well as its type.
- Copy assets/template/ into the target project. Set the package name and supported host range; pin the SDK/plugin version used for development.
- Implement only the required hooks. Mutate the provided
outputfields in place. Load references/custom-tools.md when adding model-callable actions. - Load references/patterns.md for initialization, cancellation, logging, state ownership, or teardown.
- Run the template's typecheck and tests in its own directory. Test the returned hooks and custom tool, including the blocked/error path.
- Load references/publishing.md when installing or packaging. Start the matching host in an isolated project, confirm initialization, and exercise the intended behavior. Report unit/typecheck evidence separately from host execution.
- Inspect the package contents before an authorized publication.
Minimal server plugin
import type { Plugin, PluginModule } from "@opencode-ai/plugin"
const Guard: Plugin = async () => ({
"tool.execute.before": async (input, output) => {
if (input.tool === "read" && output.args.filePath === "blocked.txt")
throw new Error("This read is blocked by the project guard.")
},
})
export default { id: "example.guard", server: Guard } satisfies PluginModule
A guard for one tool is scoped to that tool. Set agent/config permissions for access policy; a type declaration alone does not establish that a permission hook runs.
The template exports one explicit server module. Keep helper functions in imported siblings rather than exporting them from a legacy plugin entrypoint.