sync-plugins

name	sync-plugins
description	Synchronize and generate documentation for OpenCode plugins from opencode.json configuration. Use when the user wants to sync their plugins, generate plugin documentation, or view their configured plugins.
license	MIT
compatibility	Reads opencode.json from user's home directory.
metadata	{"author":"hadenlabs","version":"0.2.0"}

Synchronize plugins and generate documentation from opencode.json configuration.

Input: None required. The skill reads directly from ~/.config/opencode/opencode.json.

Steps

1. Read the opencode.json configuration

   Read the file at ~/.config/opencode/opencode.json and extract the plugin array. The plugins are stored as an array of strings with format name@version (e.g., ["opencode-pty@0.2.1", "@tarquinen/opencode-dcp@latest"]).

2. Parse each plugin entry

   For each plugin string in the format name@version:

   • Split on @ to get the plugin name and version
   • Handle special cases where the name itself contains @ (for scoped plugins like @tarquinen/opencode-dcp)
   • Handle file:// protocol URLs by extracting the module name from the path

3. Apply title rule for plugin documentation

   • Title rule: The plugin title must NOT contain version or @ symbol
   • Remove everything after @ (including the @)
   • If the plugin has a scope (starts with @), remove the @ prefix as well
   • Examples:
     • opencode-pty@0.2.1 → # opencode-pty
     • @tarquinen/opencode-dcp@latest → # tarquinen/opencode-dcp
     • @mohak34/opencode-notifier@latest → # mohak34/opencode-notifier
     • file://... → Extract name from path (see special handling below)

4. Handle special cases

   • file:// protocol: Extract the module name from the path
     • Pattern: file://.../node_modules/{scope}/{module} or file://.../{module}
     • Examples:
       • file:////Users/luchomayta/.config/opencode/node_modules/@architecture/infosis-opencode-slim → infosis-opencode-slim
       • file:////Users/.../node_modules/@some-org/plugin-name → some-org-plugin-name
     • Logic: Extract the last path segment after node_modules/, removing @scope/ prefix if present

5. Generate documentation for each plugin

   Use the following template for each plugin:

   ---
   title: {plugin_name}
   description: OpenCode plugin configured automatically
   ---
   
   # BEGIN AUTO-GENERATED PLUGIN DOC
   Plugin: {name}@{version}
   Generated: {YYYY-MM-DD}
   # END AUTO-GENERATED PLUGIN DOC
   
   # {plugin_title_without_version}
   
   ## Description
   
   This plugin is configured in `opencode.json` and synchronized automatically.
   
   ## Configuration
   
   Plugin name: `{name}@{version}`
   
   ## Usage
   
   Add to your `opencode.json` plugins array:
   
   ```json
   {{
     "plugin": ["{name}@{version}"]
   }}
   

   ---

   Auto-generated by sync-plugins skill

6. Write plugin files to disk

   For each plugin, write a markdown file to docs/opencode/plugins/:

   • Directory: docs/opencode/plugins/
   • Filename: {plugin_name}.md (without @version)
   • Filename rules:
     • Remove @ and version from name
     • For scoped plugins (@scope/name): use scope-name.md
     • For file:// plugins: extract name from path
   • Examples:
     • opencode-gemini-auth@latest → opencode-gemini-auth.md
     • @mohak34/opencode-notifier@latest → mohak34-opencode-notifier.md
     • file://.../@architecture/infosis-opencode-slim → infosis-opencode-slim.md

   Create the directory if it does not exist. The skill is idempotent - existing files are overwritten.

7. Generate and update README.md

   Regenerate docs/opencode/plugins/README.md with:

   • Title: "OpenCode Plugins"
   • List of all plugins with links to individual files
   • Generation timestamp

   Template:

   ---
   title: OpenCode Plugins
   description: Documentation for automatically configured OpenCode plugins
   ---
   
   # OpenCode Plugins
   
   Generated from: `~/.config/opencode/opencode.json`
   Total plugins: {count}
   Last updated: {YYYY-MM-DD HH:mm:ss}
   
   ---
   
   ## Plugins
   
   {list_of_plugins}
   
   ---
   *Auto-generated by sync-plugins skill*
   

   Where {list_of_plugins} is:

   - [{plugin_name}]({plugin_name}.md) - {name}@{version}
   

8. Output all generated documentation

   Display all plugin documentation blocks sequentially (stdout fallback for visibility).

Output

## OpenCode Plugins Documentation

Generated from: ~/.config/opencode/opencode.json
Total plugins: N
Files written: docs/opencode/plugins/{plugin}.md (N files)

---

[Generated documentation for each plugin...]

---
*Auto-generated by sync-plugins skill*

Guardrails

• If ~/.config/opencode/opencode.json does not exist, show an error message
• If the plugin array is empty or missing, show a message indicating no plugins are configured
• Handle edge cases where plugin strings might not match the expected format
• Always show the generation date in ISO format (YYYY-MM-DD)
• Create docs/opencode/plugins/ directory if it does not exist
• Overwrite existing files to ensure idempotency
• Handle file:// URLs by extracting module name from path

Title Rule Summary

Plugin	Title
opencode-pty@0.2.1	# opencode-pty
@tarquinen/opencode-dcp@latest	# tarquinen/opencode-dcp
some-plugin@1.0.0	# some-plugin
@mohak34/opencode-notifier@latest	# mohak34/opencode-notifier
file://.../@architecture/infosis-opencode-slim	infosis-opencode-slim

Filename Rule Summary

Plugin	Filename
opencode-gemini-auth@latest	opencode-gemini-auth.md
@mohak34/opencode-notifier@latest	mohak34-opencode-notifier.md
file://.../@architecture/infosis-opencode-slim	infosis-opencode-slim.md
@scope/some-plugin@1.0.0	scope-some-plugin.md