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

Question Tool Usage

Batching: Use the question tool for 2+ related questions. Single questions use plain text.

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

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

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

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

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

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

1. List Available Plugins