context-course/pr_7/en/unit3/using-plugins.md

# Using Plugins

Now that you've built a plugin, let's learn how to install and use them, both your own and plugins from others. The process differs slightly across platforms, but the core idea is identical: **discover → install → configure → use**.

## Installing Plugins

### Installing Plugins in Claude Code

Claude Code installs plugins through marketplaces and the in-session `/plugin` command.

#### From a marketplace

```text
/plugin marketplace add <owner>/<repo>
/plugin install <plugin-name>@<marketplace-name>
```

`/plugin` opens the plugin browser, where you can enable, disable, and uninstall plugins interactively.

#### From a local directory

For local development, point `/plugin` at a `marketplace.json` file that references your plugin directory:

```json
{
  "name": "local-example-plugins",
  "owner": { "name": "you" },
  "plugins": [
    {
      "name": "text-processor-plugin",
      "source": "./text-processor-plugin",
      "description": "Text analysis skills"
    }
  ]
}
```

Then inside Claude Code:

```text
/plugin marketplace add /absolute/path/to/marketplace.json
/plugin install text-processor-plugin@local-example-plugins
```

Claude Code reads `.claude-plugin/plugin.json`, loads skills from `skills/`, and starts MCP servers from `.mcp.json`.

### Using Plugin Skills

Once loaded, skills are available conversationally or via explicit syntax:

```
Analyze the reading level of this paragraph
```

Or invoke with namespace:

```bash
/text-processor-plugin:check-reading-level
```

### Managing Installed Plugins

Use `/plugin` to review installed plugins, enable or disable them, and uninstall them. After editing a local plugin, disable and re-enable it from `/plugin` to reload it.

### Configuring Plugins

Set environment variables required by plugins:

```bash
export HF_TOKEN="hf_xxxxx"
```

Claude Code reads these from your shell environment when the plugin loads.

### Installing Plugins in Codex

Codex plugins are installed either from the built-in plugin browser or from marketplace configuration files for local and unpublished plugins.

#### From the Plugin Browser

Open the plugin directory in the CLI:

```
/plugins
```

Search or browse, install the plugin, then start a new thread to use it.

#### From the Personal Marketplace

Copy the plugin into your personal plugin directory:

```bash
mkdir -p ~/.codex/plugins
cp -R /local/path/to/text-processor-plugin ~/.codex/plugins/text-processor-plugin
```

Then edit or create `~/.agents/plugins/marketplace.json`:

Because `source.path` is resolved relative to `~/.agents/plugins/marketplace.json`, the path needs to walk up from `~/.agents/plugins/` before pointing at `~/.codex/plugins/`.

```json
{
  "name": "local-example-plugins",
  "interface": {
    "displayName": "Local Example Plugins"
  },
  "plugins": [
    {
      "name": "text-processor-plugin",
      "source": {
        "source": "local",
        "path": "../../.codex/plugins/text-processor-plugin"
      },
      "policy": {
        "installation": "AVAILABLE",
        "authentication": "ON_INSTALL"
      },
      "category": "Productivity"
    }
  ]
}
```

Codex:
1. Reads `.codex-plugin/plugin.json`
2. Loads skills from the `skills/` directory
3. Sets up optional MCP servers from `.mcp.json`
4. Caches plugin to `~/.codex/plugins/cache/$MARKETPLACE/$PLUGIN/$VERSION/`

#### From a Repo Marketplace

Create `$REPO_ROOT/.agents/plugins/marketplace.json` in the repo that should expose the plugin list, keep the plugin folders at repo-relative paths such as `./plugins/text-processor-plugin`, then restart Codex and open `/plugins` in that repo.

### Using Plugins in Codex

#### Conversational Invocation

Ask Codex naturally. It routes your request to the right plugin:

```
What's the reading level of this README?
```

Codex:
1. Recognizes this is a text analysis task
2. Looks up the text-processor plugin's skills
3. Invokes the appropriate skill with parameters
4. Returns results

#### Using Plugin Skills

Codex plugins include skills for specific workflows. Type `@` to choose a plugin or bundled skill explicitly:

```
@text-processor-plugin
```

Or conversationally:

```
Extract the top keywords from this document
```

### Managing Plugins

Open the plugin browser to inspect installed plugins:

```
/plugins
```

If you edit `~/.agents/plugins/marketplace.json`, update the local plugin directory, or change a plugin's `enabled` flag in `~/.codex/config.toml`, restart Codex before testing again.

### Configuring Codex Plugins

Set environment variables in your shell:

```bash
export HF_TOKEN="hf_xxxxx"
```

Codex reads environment variables when loading plugins. Optional MCP servers are started if `.mcp.json` includes `mcpServers` entries.

### Installing Plugins in OpenCode

OpenCode plugins are JavaScript/TypeScript modules loaded at startup. Skills and MCP configuration are related extension surfaces, but they are not the plugin itself.

#### From Local Files

Place `.js` or `.ts` plugin files in one of the documented plugin directories:

```text
.opencode/plugins/              # project-level plugins
~/.config/opencode/plugins/     # global plugins
```

Files in those directories are loaded automatically when OpenCode starts.

#### From npm

Add plugin package names to `opencode.json`:

```json
{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["@your-org/text-processor-plugin"]
}
```

OpenCode installs npm plugins with Bun at startup.

#### What Stays Separate

If you also want reusable skills or the Unit 2 Python MCP server, configure those separately:

```bash
mkdir -p .opencode/skills/analyze-text
# Add SKILL.md to the directory
```

OpenCode discovers skills automatically from `.opencode/skills/`, `.claude/skills/`, and `.agents/skills/`.

Configure MCP servers separately in `opencode.json`:

```json
{
  "mcp": {
    "text-processor": {
      "type": "remote",
      "url": "https://YOUR-USERNAME-text-processor-mcp.hf.space/gradio_api/mcp/"
    }
  }
}
```

#### Using Plugin Behavior

Once OpenCode starts, the plugin's hooks or custom tools are available:

```
Summarize this file and note any text-analysis follow-up that would help.
```

If the plugin adds hooks, they run as those events fire. If it adds custom tools, OpenCode can call them alongside built-in tools.

#### Managing Plugins

```bash
rm .opencode/plugins/text-processor-plugin.ts
```

Or remove the package name from the `plugin` array in `opencode.json`. Restart OpenCode after editing plugin files or the `plugin` list so startup picks up the new state.

### Installing Packages in Pi

Pi's closest equivalent to a plugin is a Pi package: a local folder, git repo, or npm package that bundles skills, extensions, prompts, and themes.

#### From a local directory

```bash
pi install /local/path/to/text-processor-plugin -l
```

`-l` writes the package into `.pi/settings.json` for the current project.

#### From npm or git

```bash
pi install npm:@your-org/text-processor-plugin
pi install git:github.com/your-org/text-processor-plugin
```

#### Pairing with MCP

If the package's skills depend on the Unit 2 MCP server, install the adapter once and add the server to `.mcp.json`:

```bash
pi install npm:pi-mcp-adapter
```

```json
{
  "mcpServers": {
    "text-processor": {
      "url": "https://YOUR-USERNAME-text-processor-mcp.hf.space/gradio_api/mcp/"
    }
  }
}
```

#### Using Package Behavior

Once loaded, use the skill conversationally or explicitly:

```text
What's the reading level of this README?
/skill:check-reading-level What's the reading level of this README?
```

#### Managing Packages

```bash
pi list
pi config
pi remove /local/path/to/text-processor-plugin
```

Use `/reload` inside Pi after editing local package files or `.mcp.json`.

## Common Plugin Tasks

### Configuring API Keys

All platforms need API keys for plugins that call external services.

Set environment variables in your shell before running Claude Code:

```bash
export HF_TOKEN="hf_xxxxx"
export OPENAI_API_KEY="sk_xxxxx"
```

Claude Code reads these when plugins load. No in-app configuration needed.
  

Set environment variables in your shell:

```bash
export HF_TOKEN="hf_xxxxx"
export GITHUB_TOKEN="ghp_xxxxx"
```

Set environment variables in your shell:

```bash
export HF_TOKEN="hf_xxxxx"
export GITHUB_TOKEN="ghp_xxxxx"
```

Or configure them directly in `opencode.json` under each MCP server's `environment` block.

Set environment variables in your shell:

```bash
export HF_TOKEN="hf_xxxxx"
```

Pi reads shell environment variables directly, and `pi-mcp-adapter` can interpolate them from `.mcp.json` server entries.

### Troubleshooting Plugin Issues

**Plugin not loading?**

Check if `.claude-plugin/plugin.json` exists and is valid:

```bash
cat ./my-plugin/.claude-plugin/plugin.json
```

Ensure skills directory exists:

```bash
ls -la ./my-plugin/skills/
```

Re-enable the plugin from `/plugin` to reload it.

Check if plugin is in marketplace and properly formatted:

```bash
cat ~/.agents/plugins/marketplace.json
```

Verify `.codex-plugin/plugin.json` has correct `skills` and `mcpServers` paths:

```json
{
  "skills": "./skills/",
  "mcpServers": "./.mcp.json"
}
```

Open the plugin browser:

```
/plugins
```

If you changed marketplace or config files, restart Codex before checking again.

Check that the plugin file is in a supported directory:

```bash
ls -la .opencode/plugins/
```

If you use npm-installed plugins, verify the `plugin` array in `opencode.json`. If the plugin imports external packages, make sure `.opencode/package.json` contains those dependencies. Then restart OpenCode so startup reloads the plugin.

Then inspect the installed package list:

```bash
pi list
```

Use `/reload` after fixing the local files so Pi refreshes the package in the current session.

**Bundled or adjacent MCP server not starting?**

Verify `.mcp.json` has valid JSON with `mcpServers` key:

```bash
cat ./.mcp.json
```

Re-enable the plugin from `/plugin` after editing the config.

MCP servers are optional in Codex plugins. If they aren't starting, check:
- `.codex-plugin/plugin.json` points `mcpServers` at `./.mcp.json`
- `.mcp.json` contains a valid `mcpServers` object
- the marketplace entry points to the right plugin directory

Plugins and MCP servers are separate in OpenCode. If the separately configured server isn't starting, debug the MCP config:

```bash
opencode mcp debug text-processor
```

Check that `opencode.json` is valid JSON and MCP server commands point to existing files.

Pi packages and MCP are separate. If the package loads but the adapter does not see the server:

```bash
cat ./.mcp.json
```

Inside Pi, use:

```text
/mcp
/mcp reconnect text-processor
/mcp tools
```

Check that `pi-mcp-adapter` is installed and the server entry uses a valid `command`/`args` or `url`.

## Key Takeaways

In Claude Code, use `/plugin marketplace add` and `/plugin install`, with `/plugin` as the browser. In Codex, use `/plugins` plus repo or personal marketplace files, and restart after changes. In OpenCode, native plugins are JS/TS modules in `.opencode/plugins/` or npm packages listed in `opencode.json`; skills and MCP servers remain separate extension points. In Pi, install packages with `pi install`, keep plugin-equivalent resources in `package.json` plus `skills/` or `extensions/`, and pair them with `pi-mcp-adapter` when you need MCP tools.

Next up: a quiz on plugin distribution and best practices.