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.)
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.
</guidelines> <rules>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"]
}
\`\`\`
...