| # Installing OpenDesign for OpenCode |
|
|
| ## Prerequisites |
|
|
| - [OpenCode.ai](https://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): |
|
|
| ```json |
| { |
| "$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`: |
|
|
| ```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: |
|
|
| ```json |
| { |
| "plugin": ["opendesign@git+https://github.com/manalkaff/opendesign.git#v0.1.0"] |
| } |
| ``` |
|
|
| ## Troubleshooting |
|
|
| ### Plugin not loading |
|
|
| 1. 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"` |
|
|
| 2. 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). |
|
|
| 3. Make sure you are running a recent version of OpenCode. |
|
|
| 4. 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 |
|
|
| 1. Use `skill` tool to list what is discovered. |
| 2. Confirm the plugin loaded (see log check above). |
| 3. 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: |
|
|
| ```bash |
| 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: |
|
|
| ```bash |
| 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 |
|
|
