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

/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:

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

Then inside Claude Code:

/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:

/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:

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:

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/.

{
  "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:

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:

.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:

{
  "$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:

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:

{
  "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

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

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

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:

pi install npm:pi-mcp-adapter

{
  "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:

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

Managing Packages

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:

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:

export HF_TOKEN="hf_xxxxx"
export GITHUB_TOKEN="ghp_xxxxx"

Set environment variables in your shell:

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:

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:

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

Ensure skills directory exists:

ls -la ./my-plugin/skills/

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

Check if plugin is in marketplace and properly formatted:

cat ~/.agents/plugins/marketplace.json

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

{
  "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:

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:

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:

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:

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:

cat ./.mcp.json

Inside Pi, use:

/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.