# opencode-skill-scope Installation Guide

> This guide is designed for LLM agents to follow step-by-step. Each step includes expected outcomes for verification.

## What is opencode-skill-scope?

An OpenCode TUI plugin that displays active skills in the sidebar with a braille spinner animation. Skills appear when the Skill tool is invoked and disappear when the AI response completes.

## Prerequisites

- [OpenCode](https://opencode.ai) installed and working
- Plugin support (`@opencode-ai/plugin` >= 1.4.3)

## Step 1: Install the plugin

Run the following command in the terminal:

```bash
opencode plugin opencode-skill-scope
```

This automatically:
- Installs the `opencode-skill-scope` npm package
- Adds the TUI plugin to `tui.json`

## Step 2: Restart OpenCode

The plugin loads at startup. Restart OpenCode to activate.

## Manual Setup (alternative)

If `opencode plugin` is not available, configure the TUI config file manually.

Edit `~/.config/opencode/tui.json`. Create the file if it doesn't exist.

Add `["opencode-skill-scope", { "enabled": true }]` to the `plugin` array:

```json
{
  "$schema": "https://opencode.ai/tui.json",
  "plugin": [
    ["opencode-skill-scope", { "enabled": true }]
  ]
}
```

**If the file already exists with other plugins**, append to the existing array. Do not replace existing entries:

```json
{
  "$schema": "https://opencode.ai/tui.json",
  "plugin": [
    ["existing-plugin", { "enabled": true }],
    ["opencode-skill-scope", { "enabled": true }]
  ]
}
```

Restart OpenCode after updating the config file.

## Verification

After restart, the sidebar should show a collapsible "▼ Skill Scope" section. When no skills are active:

```
▼ Skill Scope
  No active skills
```

When a skill is invoked, it appears with a spinning braille animation:

```
▼ Skill Scope
 ⠹ api-error-design
 ⠹ git-master
```

Skills disappear automatically when the session goes idle.

## Local Development

For local development, point directly to the source file:

```json
{
  "plugin": [
    ["/path/to/opencode-skill-scope/src/tui.tsx", { "enabled": true }]
  ]
}
```

Note: OpenCode loads single-file plugins only. All source is inlined in `src/tui.tsx`.

## Troubleshooting

- **Plugin not showing**: Ensure `tui.json` is valid JSON. The options object `{ "enabled": true }` is required — `["opencode-skill-scope"]` alone will cause `ConfigInvalidError`.
- **Skills not appearing**: The plugin detects skills via the Skill tool only. Skills injected via system prompts or hooks (without the Skill tool) will not be detected.
- **Other plugins broken after adding**: Check for trailing commas or missing options objects in `tui.json`.

## Uninstall

1. Remove `["opencode-skill-scope", { "enabled": true }]` from `~/.config/opencode/tui.json` plugin array
2. Restart OpenCode