plugin-installer

What this skill does

# OpenCode Plugin Installer

Help users discover, evaluate, and install OpenCode plugins from the community catalog.

<workflow>

## 1. List Available Plugins

Run the catalog script to see what's available:

```bash
python3 ~/.config/opencode/skill/plugin-installer/scripts/list_plugins.py
```

Output shows `name: description` with path to detailed file.

## 2. Read Plugin Details

For relevant matches, read the full plugin file:

```
references/plugins/<filename>.md
```

Each file contains:
- Installation config (copy-paste JSON)
- Setup steps
- Features and caveats
- Links to docs

## 3. Recommend and Install

Show the user:
- What the plugin does
- Install snippet for `opencode.json`
- Any setup steps (OAuth, config files, etc.)

</workflow>

<question_tool>

**Batching:** Use the `question` tool for 2+ related questions. Single questions → plain text.

**Syntax:** `header` ≤12 chars, `label` 1-5 words, add "(Recommended)" to default.

When to ask: Multiple plugins match the need, or plugin has complex setup.

</question_tool>

<installation>

## Installation Format

Add to `plugin` array in opencode.json:

```jsonc
{
  "plugin": [
    "package-name@version"
  ]
}
```

**Config locations:**
- Global: `~/.config/opencode/opencode.json`
- Project: `.opencode/opencode.json`

## Version Pinning

```jsonc
// Pin version (RECOMMENDED)
"plugin": ["[email protected]"]

// Auto-update on restart
"plugin": ["package@latest"]

// Locked to first install (never updates)
"plugin": ["package"]
```

Force update when stuck:
```bash
rm -rf ~/.cache/opencode/node_modules ~/.cache/opencode/bun.lock
```

</installation>

<documenting_new_plugins>

## Adding New Plugins to the Catalog

When you discover a new OpenCode plugin (from web search, GitHub, npm, user mention), you MUST document it for future reference.

### Step 1: Gather Plugin Information

Before creating the doc, collect:

| Info | Where to Find |
|------|---------------|
| Package name | npm registry, GitHub repo name |
| Description | README, package.json description |
| Install syntax | Check if scoped (`@org/pkg`) or plain (`pkg`) |
| Version strategy | Does it recommend `@latest` or pinned? |
| Setup steps | OAuth flows, config files, env vars |
| Provider/model requirements | Does it only work with specific providers? |
| Known issues | GitHub issues, compatibility notes |

### Step 2: Create the Plugin File

**Location:** `~/.config/opencode/skill/plugin-installer/references/plugins/<name>.md`

**Naming convention:** Use the npm package name with `/` replaced by `-` for scoped packages:
- `opencode-foo` → `opencode-foo.md`
- `@org/opencode-bar` → `org-opencode-bar.md`

### Step 3: Use This Template

```markdown
---
name: package-name-or-@scope/package-name
description: One-line description for catalog listing (max ~80 chars)
---
# Plugin Display Name

Brief description of what this plugin does and why someone would use it.

## Installation

\`\`\`jsonc
{
  "plugin": ["package-name@latest"]
}
\`\`\`

## Setup

### Prerequisites
- List any requirements (accounts, API keys, other tools)

### Configuration
Step-by-step setup instructions.

## Features
- Key feature 1
- Key feature 2

## Caveats
- Known limitations
- Compatibility notes

## Links
- [GitHub](https://github.com/...)
- [npm](https://www.npmjs.com/package/...)
```

### Step 4: Verify the Catalog

After creating, run the listing script to confirm it appears:

```bash
python3 ~/.config/opencode/skill/plugin-installer/scripts/list_plugins.py
```

</documenting_new_plugins>

<frontmatter_requirements>

| Field | Required | Purpose |
|-------|----------|---------|
| `name` | Yes | Package name exactly as used in `"plugin": []` |
| `description` | Yes | One-liner shown in catalog listings |

**Important:** The `name` MUST match the npm package name exactly (including scope if any). This is what users will copy into their `opencode.json`.

</frontmatter_requirements>

<example>

## Documenting a New Plugin

Say you found `@cooldev/opencode-metrics` on npm. Create:

**File:** `~/.config/opencode/skill/plugin-installer/references/plugins/cooldev-opencode-metrics.md`

```markdown
---
name: @cooldev/opencode-metrics
description: Track AI usage metrics and export to dashboards
---
# OpenCode Metrics

Export your OpenCode usage data to external dashboards...

## Installation

\`\`\`jsonc
{
  "plugin": ["@cooldev/opencode-metrics@latest"]
}
\`\`\`

...
```

</example>