create-opencode-plugin

Files (13)

• SKILL.md
• CODING-TS.MD · references/
• events.md · references/
• examples.md · references/
• hook-patterns.md · references/
• hooks.md · references/
• publishing.md · references/
• testing.md · references/
• toast-notifications.md · references/
• tool-helper.md · references/
• ui-feedback.md · references/
• update-notifications.md · references/
• extract-plugin-api.ts · scripts/

SKILL.md (first lines)

---
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/plugins/ or ~/.config/opencode/plugins/.
  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

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

<workflow>

## Procedure Overview

| Step | Action               | Read                                                                            |
| ---- | -------------------- | ------------------------------------------------------------------------------- |
| 1    | Verify SDK reference | Run extract script                                                              |
| 2    | Validate feasibility | This file                                                                       |
| 3    | Design plugin        | `references/hooks.md`, `references/hook-patterns.md`, `references/CODING-TS.MD` |
| 4    | Implement            | `references/tool-helper.md` (if custom tools)                                   |
| 5    | Add UI feedback      | `references/toast-notifications.md`, `references/ui-feedback.md` (if needed)    |
| 6    | Test                 | `references/testing.md`                                                         |
| 7    | Publish              | `references/publishing.md`, `references/update-notifications.md` (if npm)       |

---

## Step 1: Verify SDK Reference (REQUIRED)

Before creating any plugin, MUST regenerate the API reference to ensure accuracy:

```bash
bun run .github/skill/create-opencode-plugin/scripts/extract-plugin-api.ts --workspace /absolute/path/to/opencode
```

This generates:

- `references/hooks.md` - All available hooks and signatures
- `references/events.md` - All event types and properties
- `references/tool-helper.md` - Tool creation patterns

---

## Step 2: Validate Feasibility (REQUIRED)

MUST determine if the user's concept is achievable with available hooks.

### Feasible as plugins:

- Intercepting/blocking tool calls
- Reacting to events (file edits, session completion, etc.)
- Adding custom tools for the LLM
- Modifying LLM parameters (temperature, etc.)
- Custom auth flows for providers
- Customizing session compaction
- Displaying status messages (toasts, inline)

### NOT feasible (inform user):

- Modifying TUI rendering or layout
- Adding new built-in tools (requires OC source)
- Changing core agent behavior/prompts
- Intercepting assistant responses mid-stream
- Adding new keybinds or commands
- Modifying internal file read/write
- Adding new permission types

**If not feasible**, MUST inform user clearly. Suggest:

- OC core changes: contribute to `packages/opencode`
- MCP tools: use MCP server configuration
- Simple automation: use shell scripts

---

## Step 3: Design Plugin

**READ**: `references/hooks.md` for available hooks, `references/hook-patterns.md` for implementation patterns.

**READ**: `references/CODING-TS.MD` for code architecture principles. MUST follow these design guidelines:

- **Modular structure**: Split complex plugins into multiple focused files (types, utilities, hooks, tools)
- **Single purpose**: Each function does ONE thing well
- **DRY**: Extract common patterns into shared utilities immediately
- **Small files**: Keep individual files under 150 lines - split into smaller modules as needed
- **No monoliths**: MUST NOT put all plugin code in a single `index.ts` file

### Plugin Locations

| Scope   | Path                                        | Use Case                   |
| ------- | ------------------------------------------- | -------------------------- |
| Project | `.opencode/plugins/<name>.ts`               | Team-shared, repo-specific |
| Global  | `~/.config/opencode/plugins/<name>.ts`      | Personal, all projects     |

### Basic Structure

```typescript
import type { Plugin } from "@opencode-ai/plugin"

export const MyPlugin: Plugin = async ({ project, client, $, directory, worktree }) => {
  // Setup code runs once on load

  return {
    // Hook implementations - see references/hook-patterns.md
  }
}
```

### Context Parameters

| Parameter   | Type       | Description                               |
| ----------- | ---------- | ----------------------------------------- |
| `project`   | `Project`  | Current project info (id, worktree, name) |

From Poorgramer-Zack/opencode-smol, MIT.

More from Poorgramer-Zack/opencode-smol