Installing OpenDesign for OpenCode

Prerequisites

OpenCode.ai installed

Installation

Project-level (recommended)

Add opendesign to .opencode/opencode.json in your project root (create the file if it does not exist):

{
  "$schema": "../opencode-schema.json",
  "plugin": [
    "opendesign@git+https://github.com/manalkaff/opendesign.git"
  ]
}

Note: Current OpenCode reads project-level config from .opencode/opencode.json, not from opencode.json or .opencode.json at the repo root. If you added the plugin to one of those locations and it is not loading, move it here.

Restart OpenCode. The first install fetches the package from GitHub and may take 10–30 seconds while dependencies are reified — wait for it before assuming something failed.

Global (all projects)

Add opendesign to your global config at ~/.config/opencode/opencode.json or ~/.opencode/opencode.json:

{
  "plugin": [
    "opendesign@git+https://github.com/manalkaff/opendesign.git"
  ]
}

Restart OpenCode.

Verifying install

After restarting, verify by asking: "What design skills do you have?"

You should see opendesign skills listed. If skill count did not increase, check the logs (see Troubleshooting below).

Usage

Use OpenCode's native skill tool:

use skill tool to list skills
use skill tool to load opendesign

Updating

OpenDesign updates automatically when you restart OpenCode.

If OpenCode still shows older skill content after restart, see Troubleshooting -> Stale cached plugin content below. In some cases OpenCode continues using an older cached package until that cache entry is removed.

To pin a specific version:

{
  "plugin": ["opendesign@git+https://github.com/manalkaff/opendesign.git#v0.1.0"]
}

Troubleshooting

Plugin not loading

Check logs for these key lines:

project config loaded from .opencode/opencode.json   ← confirms correct config path
project .opencode reify                              ← npm install in progress
loading plugin                                       ← plugin being initialized

Run: opencode run --print-logs "hello" 2>&1 | grep -iE "opendesign|reify|project config|plugin"

Make sure the plugin entry is in .opencode/opencode.json (not opencode.json or .opencode.json at the repo root — those may be ignored by current OpenCode builds for project-level plugin loading).
Make sure you are running a recent version of OpenCode.
If you just added the plugin for the first time, wait 30 seconds on the next restart — the git package download and npm reify take time.

Skills not found

Use skill tool to list what is discovered.
Confirm the plugin loaded (see log check above).
Confirm skill count increased after restart.

Stale cached plugin content

If OpenCode loads the plugin but the skill text still looks outdated after you updated or reinstalled opendesign, OpenCode may be using a stale cached package copy under ~/.cache/opencode/packages/.

Symptoms include:

the plugin appears installed, but skill content still reflects an older revision
reinstalling in ~/.config/opencode/ or ~/.opencode/ does not change the loaded skill text
the cached package under ~/.cache/opencode/packages/ contains an older opendesign version than the one you expect

Check the cached copy directly:

grep -n "design-systems" ~/.cache/opencode/packages/opendesign@git+https:/github.com/manalkaff/opendesign.git/node_modules/opendesign/skills/opendesign/SKILL.md

If that cached package is stale, remove it and restart OpenCode so it can fetch the current plugin again:

rm -rf ~/.cache/opencode/packages/opendesign@git+https:/github.com/manalkaff/opendesign.git

Then fully restart OpenCode and start a fresh session.

Tool mapping

When skills reference Claude Code tools:

TodoWrite → todowrite
Task with subagents → @mention syntax
Skill tool → OpenCode's native skill tool
File operations → your native tools

Getting help

Report issues: https://github.com/manalkaff/opendesign/issues
Repo: https://github.com/manalkaff/opendesign