create-opencode-plugin

star 10

Create OpenCode plugins using the @opencode-ai/plugin SDK. Use for building custom tools, event hooks, auth providers, or tool execution interception. Use proactively when developing new plugins in .opencode/plugin/ or ~/.config/opencode/plugin/. Examples: - user: "Create a plugin to block dangerous commands" -> implement tool execution before hook with blocking logic - user: "Add a custom tool for jira" -> design tool schema and implementation using SDK context - user: "Show toast on file edit" -> react to file edit events and display status message - user: "Build a custom auth provider" -> implement auth flow for new model provider - user: "Intercept git commits" -> add hook to validate commit messages before execution

IgorWarzocha By IgorWarzocha schedule Updated 2/4/2026
play_arrow Run Skill in Manus View GitHub

name: create-opencode-plugin description: |- Create OpenCode plugins using the @opencode-ai/plugin SDK. Use for building custom tools, event hooks, auth providers, or tool execution interception. Use proactively when developing new plugins in .opencode/plugin/ or ~/.config/opencode/plugin/. Examples: - user: "Create a plugin to block dangerous commands" -> implement tool execution before hook with blocking logic - user: "Add a custom tool for jira" -> design tool schema and implementation using SDK context - user: "Show toast on file edit" -> react to file edit events and display status message - user: "Build a custom auth provider" -> implement auth flow for new model provider - user: "Intercept git commits" -> add hook to validate commit messages before execution

Creating OpenCode Plugins

Re-read this file periodically during plugin development to refresh context and ensure you're following the correct procedure.

Workflow (Ordered)

  1. Verify SDK reference (HIGHLY RECOMMENDED)

    • SHOULD regenerate references when possible. MAY skip if installed SDK is sufficient.
    • Run from this package root:
      bun run ./skills/create-opencode-plugin/scripts/extract-plugin-api.ts

  2. Validate feasibility

    • MUST confirm the request is possible with available hooks.
    • If not feasible, suggest OC core changes, MCP tools, or scripts.

  3. Design

    • READ: references/hooks.md, references/hook-patterns.md, references/examples.md, references/CODING-TS.MD.
    • Keep modules small; avoid monoliths.

  4. Implement

    • READ: references/tool-helper.md (if tools), references/events.md (if events).
    • Follow the modular structure and common mistakes checklist.

  5. UI feedback (optional)

    • READ: references/toast-notifications.md, references/ui-feedback.md.
    • Use references/failure-guidance.md if a feature fails.

  6. Test

    • READ: references/testing.md.
    • Build first; use dist/index.js for local opencode.json.

  7. Publish (optional)

    • READ: references/publishing.md, references/update-notifications.md.

Feasibility

Feasible:

  • Block/intercept tool calls
  • React to events
  • Add custom tools
  • Modify LLM params
  • Custom auth providers
  • Customize session compaction
  • Show status messages (toast/inline)

Not feasible (inform user and suggest alternatives):

  • Modify TUI rendering/layout
  • Add new built-in tools (requires OC source)
  • Change core agent behavior/prompts
  • Intercept assistant output mid-stream
  • Add new keybinds or commands
  • Modify internal file read/write
  • Add new permission types

Design Checklist

  • Modular structure (types/utils/hooks/tools)
  • Single-purpose files, <150 lines
  • DRY and simple

Plugin locations:

  • Local: ./index.ts
  • Project: .opencode/plugin/<name>/index.ts
  • Global: ~/.config/opencode/plugin/<name>/index.ts

Context parameters: project, client, $, directory, worktree

Common Mistakes

  • client.registerTool() -> use tool: { name: tool({...}) }
  • Wrong event properties -> check references/events.md
  • Sync hook handlers -> always async
  • Missing block throw -> throw new Error() in tool.execute.before
  • Missing types -> import type { Plugin } from "@opencode-ai/plugin"

Debug Logging Policy

  • Logging is ONLY allowed when the user reports a failure and the path to resolution is not obvious.
  • If logging is needed, write to a single file next to dist/index.js.
  • The log file MUST be overwritten on each run.
  • Remove all logging before publishing.

Quick Test

  1. Build plugin.
  2. Create opencode.json pointing to dist/index.js.
  3. Run opencode run hi.

Reference Files Summary

File Purpose When to Read
hooks.md Hook signatures (auto-generated) Workflow steps 3-4
events.md Event types (auto-generated) Step 4 (if events)
tool-helper.md Tool helper patterns Step 4 (if tools)
hook-patterns.md Hook implementation examples Step 3-4
CODING-TS.MD Architecture principles Step 3
examples.md Complete plugin examples Step 3-4
command-skip-llm.md Command handled without LLM Step 4 (if commands)
config-bundling.md Skills/agents/commands config Step 4 (if bundling)
toast-notifications.md Toast popup API Step 5 (if toasts)
ui-feedback.md Inline message API Step 5 (if inline needed)
failure-guidance.md User-facing failure guidance Step 5 (if failures occur)
testing.md Testing procedure Step 6
readme-template.md End-user README template Step 7 (if publishing)
publishing.md npm publishing Step 7
update-notifications.md Version toast pattern Step 7 (if npm plugins)
Install via CLI
npx skills add https://github.com/IgorWarzocha/create-opencode-plugin --skill create-opencode-plugin
Repository Details
star Stars 10
call_split Forks 1
navigation Branch main
article Path SKILL.md
More from Creator
IgorWarzocha
IgorWarzocha Explore all skills →