igorwarzocha/opencode-workflows/plugin-installer

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

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

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

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

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

</documenting_new_plugins>

<frontmatter_requirements>

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

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