Skill: Create an OpenCode Plugin

Scaffold a working OpenCode plugin for use in OpenWork.

When to use

• User asks "create a plugin that does X"
• User asks "write a plugin" or "make a plugin"
• User wants to extend OpenWork/OpenCode with custom tools

Plugin API

An OpenCode plugin is an async factory function that returns a hooks object.

File location

Plugins can live in:

• Project: .opencode/plugins/my-plugin.ts (auto-discovered)
• Global: ~/.config/opencode/plugins/my-plugin.ts
• npm: published as a package, referenced in opencode.json plugin array
• URL: file: or https: path in the plugin array

Minimal shape

import { z } from "zod";

export default async () => ({
  tool: {
    my_tool_name: {
      description: "What this tool does.",
      args: z.object({
        input: z.string().describe("The input parameter."),
      }).shape,   // NOTE: .shape, not the ZodObject itself
      async execute(args: { input: string }) {
        // Your logic here. Can use fetch(), fs, child_process, etc.
        return `Result: ${args.input}`;
      },
    },
  },
});

Key rules

1. Export default an async function that returns the hooks object.
2. Tool args use zodSchema.shape (a ZodRawShape), not the ZodObject.
3. execute returns a string or { output: string; metadata?: Record<string, unknown> }.
4. Tools are declared, not registered imperatively, return them in the hooks object.
5. fetch() works, plugins run in-process inside the OpenCode runtime.
6. process.env is accessible, use env vars for secrets/config.

Available hooks

{
  // Modify the system prompt
  "experimental.chat.system.transform": async (input, output: { system: string[] }) => {
    output.system.push("Extra instruction for the agent.");
  },

  // Define tools the agent can call
  tool: {
    tool_name: { description, args, execute },
  },