context-course/pr_2/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 /
/plugin install @

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

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

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.

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.

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.

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.

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