name	plugin-installer
description	Help users find and install OpenCode plugins. Use when user asks "is there a plugin for X?", "how do I install Y plugin?", "what plugins are available?", or needs help configuring plugins in opencode.json.

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:

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.)

Installation Format

Add to plugin array in opencode.json:

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

Config locations:

Global: ~/.config/opencode/opencode.json
Project: .opencode/opencode.json

Version Pinning

// Pin version (recommended)
"plugin": ["package@1.2.3"]

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

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

Force update when stuck:

rm -rf ~/.cache/opencode/node_modules ~/.cache/opencode/bun.lock

Adding New Plugins to the Catalog

When you discover a new OpenCode plugin (from web search, GitHub, npm, user mention), 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

---
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:

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

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.

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

---
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"]
}
\`\`\`

...

plugin-installer

Install Skill

SKILL.md