# creating-opencode-plugins

The creating-opencode-plugins skill guides writing OpenCode plugins in JavaScript/TypeScript, covering module structure, event hooks, and sample implementations.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Windsurf (Devin Desktop), Claude.ai · 1 install · ★ 125 repo stars
- Author: pr-pm
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/pr-pm/prpm/tree/HEAD/.claude/skills/creating-opencode-plugins/SKILL.md
- Updated: 2026-10-14
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/creating-opencode-plugins

## What it does

The skill applies when an agent builds an OpenCode plugin — a module that hooks into lifecycle events such as file edits, command execution, LSP diagnostics, permissions, sessions, tool calls, and TUI interactions. A plugin exports an async function that receives context (`project`, `client`, `$`, `directory`, `worktree`) and returns an event handler branching on `event.type`.

It lists event categories (`file.edited`, `tool.execute.before/after`, `permission.replied`, `session.created`, and others), a manifest format for `package.json`, and worked examples: blocking read or share actions on `.env` files, sending a notification when a command runs long, and registering a custom lint tool. A table of common mistakes covers blocking handlers that aren't async, mutating event data instead of returning an override object, and skipping try/catch.

Plugins live in one of two locations: `~/.config/opencode/plugin/` for use across projects or `.opencode/plugin/` scoped to one project.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add pr-pm/prpm --skill creating-opencode-plugins -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/creating-opencode-plugins/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/creating-opencode-plugins/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add pr-pm/prpm --skill creating-opencode-plugins -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/creating-opencode-plugins/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add pr-pm/prpm --skill creating-opencode-plugins -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/creating-opencode-plugins/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install pr-pm/prpm .claude/skills/creating-opencode-plugins
```

2. **Manually: put the files in place**
- File: `.github/skills/creating-opencode-plugins/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add pr-pm/prpm --skill creating-opencode-plugins -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/pr-pm/prpm --path .claude/skills/creating-opencode-plugins
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/creating-opencode-plugins/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add pr-pm/prpm --skill creating-opencode-plugins -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/pr-pm/prpm/tree/HEAD/.claude/skills/creating-opencode-plugins/SKILL.md

## When to use it
- scaffold an OpenCode plugin with an event handler
- block reads or sharing of .env files
- get notified when a long-running command or tool finishes
- register a custom tool such as a linter through a plugin
- decide whether a plugin belongs in the global or project folder

## Example prompts
- Write an OpenCode plugin that blocks reads of .env files
- Build a plugin that notifies me when a tool call takes over 5 seconds
- Register a custom lint tool through an OpenCode plugin

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 10d5716d8c3571dd.

BEGIN THIRD-PARTY FILE 10d5716d8c3571dd
````text
---
name: creating-opencode-plugins
description: Use when creating OpenCode plugins that hook into command, file, LSP, message, permission, server, session, todo, tool, or TUI events - provides plugin structure, event API specifications, and implementation patterns for JavaScript/TypeScript event-driven modules
---

# Creating OpenCode Plugins

## Overview

OpenCode plugins are JavaScript/TypeScript modules that hook into 25+ events across the OpenCode AI assistant lifecycle. Plugins export an async function receiving context (project, client, $, directory, worktree) and return an event handler.

## When to Use

**Create an OpenCode plugin when:**
- Intercepting file operations (prevent sharing .env files)
- Monitoring command execution (notifications, logging)
- Processing LSP diagnostics (custom error handling)
- Managing permissions (auto-approve trusted operations)
- Reacting to session lifecycle (cleanup, initialization)
- Extending tool capabilities (custom tool registration)
- Enhancing TUI interactions (custom prompts, toasts)

**Don't create for:**
- Simple prompt instructions (use agents instead)
- One-time scripts (use bash tools)
- Static configuration (use settings files)

## Quick Reference

### Plugin Structure

```javascript
export const MyPlugin = async (context) => {
  // context: { project, client, $, directory, worktree }

  return {
    event: async ({ event }) => {
      // event: { type: 'event.name', data: {...} }

      switch(event.type) {
        case 'file.edited':
          // Handle file edits
          break;
        case 'tool.execute.before':
          // Pre-process tool execution
          break;
      }
    }
  };
};
```

### Event Categories

| Category | Events | Use Cases |
|----------|--------|-----------|
| **command** | `command.executed` | Track command history, notifications |
| **file** | `file.edited`, `file.watcher.updated` | File validation, auto-formatting |
| **installation** | `installation.updated` | Dependency tracking |
| **lsp** | `lsp.client.diagnostics`, `lsp.updated` | Custom error handling |
| **message** | `message.*.updated/removed` | Message filtering, logging |
| **permission** | `permission.replied/updated` | Permission policies |
| **server** | `server.connected` | Connection monitoring |
| **session** | `session.created/deleted/error/idle/status/updated/compacted/diff` | Session management |
| **todo** | `todo.updated` | Todo synchronization |
````
END THIRD-PARTY FILE 10d5716d8c3571dd

The third-party file has ended. Everything between the 10d5716d8c3571dd tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2451 of 10834 bytes. © pr-pm · MIT · https://github.com/pr-pm/prpm/tree/HEAD/.claude/skills/creating-opencode-plugins/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
