> ## Documentation Index
> Fetch the complete documentation index at: https://docs.openhands.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Plugins

> Plugins bundle multiple agent components together—skills, hooks, MCP servers, agents, and commands—into reusable packages that extend OpenHands capabilities.

Plugins provide a way to package and distribute multiple agent components as a single unit. Instead of managing individual skills, hooks, and configurations separately, plugins bundle everything together for easier installation and distribution.

## What Are Plugins?

A plugin is a directory structure that can contain:

* **Skills**: Specialized knowledge and workflows
* **Hooks**: Event handlers for tool lifecycle
* **MCP Config**: External tool server configurations
* **Agents**: Specialized agent definitions
* **Commands**: Slash commands

<Info>
  The plugin format is compatible with the [Claude Code plugin structure](https://github.com/anthropics/claude-code/tree/main/plugins). Both `.plugin/` (OpenHands-native) and `.claude-plugin/` (Claude Code compatible) directory names are supported for the metadata directory.
</Info>

## Plugins vs Skills

Understanding the difference helps you choose the right approach:

<CardGroup cols={2}>
  <Card title="Skills" icon="book">
    **Specialized prompts for specific tasks**

    * One skill = one specific capability
    * Just a SKILL.md file (+ optional resources)
    * Lightweight and focused
    * Quick to create and share

    **When to use:**

    * Adding single capabilities
    * Simple workflows
    * Domain-specific knowledge
    * Quick solutions
  </Card>

  <Card title="Plugins" icon="plug">
    **Multi-component bundles**

    * Multiple skills + hooks + config
    * Complete feature ecosystems
    * Coordinated components
    * Professional distribution

    **When to use:**

    * Complete feature sets
    * Tool integrations
    * Team standards
    * Commercial distributions
  </Card>
</CardGroup>

### Comparison Table

| Aspect           | Skills            | Plugins                         |
| ---------------- | ----------------- | ------------------------------- |
| **Complexity**   | Simple            | Comprehensive                   |
| **Components**   | Knowledge only    | Skills + hooks + MCP + commands |
| **Use Case**     | Single capability | Complete feature set            |
| **Creation**     | Few minutes       | Planned development             |
| **Distribution** | Copy directory    | Structured package              |
| **Maintenance**  | Individual files  | Coordinated bundle              |

### When to Use Each

**Use a Skill when you need:**

* A single reusable prompt or workflow
* Domain-specific knowledge
* Simple automation
* Quick solutions

**Use a Plugin when you need:**

* Multiple related skills working together
* Event handlers (hooks) for tool actions
* External tool integrations (MCP)
* Complete platform integrations
* Team or organizational standards

**Example: Code Quality**

*As separate skills:*

```
.agents/skills/
├── python-linting/
├── code-review/
└── pre-commit-setup/
```

*As a plugin:*

```
code-quality-plugin/
├── .plugin/plugin.json          # or .claude-plugin/plugin.json
├── skills/
│   ├── linting/
│   ├── review/
│   └── setup/
├── hooks/hooks.json             # Post-edit linting
└── .mcp.json                    # Code analysis tools
```

The plugin version bundles all quality-related capabilities and automatically runs checks after file edits.

## Plugin Structure

A complete plugin follows this directory structure:

```
plugin-name/
├── .plugin/                     # or .claude-plugin/
│   └── plugin.json              # Required: Plugin metadata
├── skills/
│   └── skill-name/
│       └── SKILL.md             # Individual skills
├── hooks/
│   └── hooks.json               # Tool lifecycle hooks
├── agents/
│   └── agent-name.md            # Specialized agents
├── commands/
│   └── command-name.md          # Slash commands
├── .mcp.json                    # MCP server config
└── README.md                    # Documentation
```

### Required Components

Only one file is required:

* **`plugin-name/.plugin/plugin.json`** or **`plugin-name/.claude-plugin/plugin.json`**: Plugin metadata

All other components are optional—include only what your plugin needs.

### Plugin Metadata

The `plugin.json` file defines your plugin:

```json theme={null}
{
  "name": "code-quality",
  "version": "1.0.0",
  "description": "Code quality tools and workflows",
  "author": {
    "name": "Your Name",
    "email": "your@email.com"
  },
  "license": "MIT",
  "repository": "https://github.com/example/code-quality-plugin"
}
```

The `author` field can also be a simple string such as `"Your Name"`.

## Plugin Components Explained

<AccordionGroup>
  <Accordion title="Skills">
    Skills in plugins work identically to standalone skills. Each skill has its own directory with a SKILL.md file:

    ```
    skills/
    ├── linting/
    │   ├── SKILL.md
    │   └── scripts/
    └── testing/
        └── SKILL.md
    ```

    See [Skills Documentation](/overview/skills) for skill creation details.
  </Accordion>

  <Accordion title="Hooks">
    Hooks are event handlers that run during tool lifecycle events:

    ```json theme={null}
    {
      "hooks": {
        "PostToolUse": [
          {
            "matcher": "file_editor",
            "hooks": [
              {
                "type": "command",
                "command": "ruff check $OPENHANDS_PROJECT_DIR",
                "timeout": 10
              }
            ]
          }
        ]
      }
    }
    ```

    Hook commands have access to these environment variables:

    * `$OPENHANDS_PROJECT_DIR`: Path to the project directory
    * `$OPENHANDS_SESSION_ID`: Current session identifier
    * `$OPENHANDS_EVENT_TYPE`: The triggering event type
    * `$OPENHANDS_TOOL_NAME`: Name of the tool that triggered the hook

    **Common use cases:**

    * Run linters after file edits
    * Validate tool inputs
    * Log tool usage
    * Trigger dependent actions

    **Available hook events:**

    * `PreToolUse`: Before tool execution
    * `PostToolUse`: After tool execution
    * `UserPromptSubmit`: When the user submits a prompt
    * `SessionStart`: When the session starts
    * `SessionEnd`: When the session ends
    * `Stop`: When execution stops
  </Accordion>

  <Accordion title="MCP Configuration">
    MCP (Model Context Protocol) servers provide external tools and resources:

    ```json theme={null}
    {
      "mcpServers": {
        "fetch": {
          "command": "uvx",
          "args": ["mcp-server-fetch"]
        },
        "github": {
          "command": "uvx",
          "args": ["mcp-server-github"],
          "env": {
            "GITHUB_TOKEN": "${GITHUB_TOKEN}"
          }
        }
      }
    }
    ```

    **Use cases:**

    * Connect to external APIs
    * Add specialized tools
    * Integrate third-party services

    Learn more: [Model Context Protocol](/overview/model-context-protocol)
  </Accordion>

  <Accordion title="Agents">
    Specialized agent definitions for specific tasks:

    ```markdown theme={null}
    ---
    name: code-reviewer
    description: Specialized agent for code review tasks
    ---

    # Code Review Agent

    This agent specializes in reviewing code according to team standards...
    ```

    Agents in plugins can use the plugin's skills and hooks automatically.
  </Accordion>

  <Accordion title="Commands">
    Custom slash commands for plugin functionality:

    ```markdown theme={null}
    ---
    name: /lint
    description: Run linters on current file
    ---

    # Lint Command

    Run configured linters on the current file...
    ```

    Commands provide quick access to plugin features.
  </Accordion>
</AccordionGroup>

## Using Plugins

How you use plugins depends on your platform:

<Tabs>
  <Tab title="CLI">
    **Via configuration file:**

    Create `~/.openhands/config.toml`:

    ```toml theme={null}
    [plugins]
    sources = [
      "/path/to/local/plugin",
      "github:org/plugin-repo",
    ]
    ```

    **Via command line:**

    ```bash theme={null}
    openhands --plugin /path/to/plugin
    openhands --plugin github:org/plugin-repo
    ```

    Plugins are loaded when OpenHands starts.
  </Tab>

  <Tab title="SDK">
    Load plugins programmatically:

    ```python theme={null}
    from openhands.sdk import LLM, Agent, Conversation
    from openhands.sdk.plugin import PluginSource
    from pydantic import SecretStr

    llm = LLM(model="claude-sonnet-4-20250514", api_key=SecretStr("your-api-key"))
    agent = Agent(llm=llm)

    plugins = [
        PluginSource(source="/path/to/plugin"),
        PluginSource(source="github:org/repo", ref="v1.0.0"),
    ]

    conversation = Conversation(
        agent=agent,
        plugins=plugins,
    )
    ```

    See [SDK Plugins Guide](/sdk/guides/plugins) for details.
  </Tab>

  <Tab title="Local GUI">
    **Via UI:**

    1. Open Settings
    2. Navigate to Plugins section
    3. Add plugin path or GitHub URL
    4. Restart to load

    **Via file system:**
    Place plugins in `.openhands/plugins/` in your workspace.
  </Tab>

  <Tab title="OpenHands Cloud">
    **Via Cloud UI:**

    1. Navigate to Workspace Settings
    2. Select Plugins tab
    3. Browse plugin library or add custom plugin
    4. Click "Enable" to activate

    Organization admins can publish plugins for team-wide access.
  </Tab>
</Tabs>

## Installing Plugins

### From a Local Directory

1. **Verify plugin structure**:
   ```bash theme={null}
   ls plugin-dir/.plugin/plugin.json || ls plugin-dir/.claude-plugin/plugin.json
   ```

2. **Use the plugin path** in your configuration or command line

### From GitHub

Plugins can be loaded directly from GitHub repositories:

```
github:OpenHands/example-plugin
github:org/repo/path/to/plugin    # For monorepos
github:org/repo#branch-name        # Specific branch
github:org/repo#v1.0.0            # Specific tag
```

### Plugin Sources

<CardGroup cols={2}>
  <Card title="Official Registry" icon="github">
    [github.com/OpenHands/extensions](https://github.com/OpenHands/extensions)

    Community-maintained plugins
  </Card>

  <Card title="Custom Repositories" icon="code">
    Your own GitHub repositories

    Organization or private plugins
  </Card>
</CardGroup>

## Creating Plugins

To create your own plugin:

### 1. Plan Your Components

Determine what your plugin needs:

* Which skills?
* What hooks for automation?
* Any MCP integrations?
* Custom commands?

### 2. Create Directory Structure

```bash theme={null}
mkdir -p my-plugin/.plugin
mkdir -p my-plugin/skills
mkdir -p my-plugin/hooks
```

Use `.claude-plugin/` instead of `.plugin/` if you want Claude Code-compatible naming.

### 3. Create Plugin Metadata

Create `my-plugin/.plugin/plugin.json` (or `my-plugin/.claude-plugin/plugin.json`):

```json theme={null}
{
  "name": "my-plugin",
  "version": "0.1.0",
  "description": "My custom plugin",
  "author": {
    "name": "Your Name"
  }
}
```

### 4. Add Components

Add skills, hooks, and other components as needed:

```
my-plugin/
├── .plugin/plugin.json          # or .claude-plugin/plugin.json
├── skills/
│   └── my-skill/
│       └── SKILL.md
└── hooks/
    └── hooks.json
```

### 5. Test Locally

Load your plugin and verify all components work:

```bash theme={null}
openhands --plugin /path/to/my-plugin
```

### 6. Distribute

Options for distribution:

* **GitHub repository**: Push to GitHub and share URL
* **File sharing**: Zip and share directory
* **Package registry**: Submit to official registry

## Plugin Examples

<CardGroup cols={2}>
  <Card title="Code Quality Plugin" icon="check">
    **Contains:**

    * Python linting skill
    * JavaScript linting skill
    * Post-edit hooks for auto-linting
    * Pre-commit setup

    **Use case:** Enforce code standards
  </Card>

  <Card title="DevOps Plugin" icon="server">
    **Contains:**

    * Kubernetes deployment skill
    * Docker build skill
    * CI/CD workflow skill
    * kubectl MCP server

    **Use case:** Infrastructure management
  </Card>

  <Card title="API Integration Plugin" icon="link">
    **Contains:**

    * REST API client skill
    * Authentication skill
    * Rate limiting hooks
    * API MCP server

    **Use case:** External service integration
  </Card>

  <Card title="Testing Plugin" icon="flask">
    **Contains:**

    * Unit testing skill
    * Integration testing skill
    * Post-code hooks for test runs
    * Coverage commands

    **Use case:** Automated testing
  </Card>
</CardGroup>

## Plugin Development Best Practices

<Steps>
  <Step title="Start with Skills">
    Begin by creating the core skills your plugin needs. Test them individually before bundling.
  </Step>

  <Step title="Add Automation with Hooks">
    Identify repetitive tasks and automate them with hooks. Example: run linters after file edits.
  </Step>

  <Step title="Integrate External Tools">
    Add MCP servers for external tool integration. This provides your skills with additional capabilities.
  </Step>

  <Step title="Document Thoroughly">
    Include a comprehensive README explaining:

    * What the plugin does
    * How to install it
    * Configuration options
    * Example usage
  </Step>

  <Step title="Version Carefully">
    Use semantic versioning (major.minor.patch) and document breaking changes.
  </Step>
</Steps>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Plugin Not Loading">
    **Check:**

    * `.plugin/plugin.json` or `.claude-plugin/plugin.json` exists and is valid JSON
    * Plugin path is correct
    * All referenced files exist

    **Debug:**

    ```bash theme={null}
    # Verify structure
    ls -la plugin-name/.plugin/plugin.json || ls -la plugin-name/.claude-plugin/plugin.json

    # Check JSON syntax
    (cat plugin-name/.plugin/plugin.json 2>/dev/null || cat plugin-name/.claude-plugin/plugin.json) | python -m json.tool
    ```
  </Accordion>

  <Accordion title="Skills Not Triggering">
    **Check:**

    * Skills have valid SKILL.md files
    * Frontmatter includes `triggers`
    * Trigger keywords match your prompts

    **Test:**
    Use explicit trigger keywords from the skill's frontmatter.
  </Accordion>

  <Accordion title="Hooks Not Running">
    **Check:**

    * `hooks/hooks.json` syntax is valid
    * Hook matchers target the right tools
    * Commands are executable

    **Debug:**
    Check logs for hook execution errors.
  </Accordion>
</AccordionGroup>

## Next Steps

* **[Learn about Skills](/overview/skills)** - Understand the core component of plugins
* **[Explore MCP](/overview/model-context-protocol)** - Add external tool integrations
* **[SDK Plugins Guide](/sdk/guides/plugins)** - Programmatic plugin usage
* **[Browse Examples](https://github.com/OpenHands/software-agent-sdk/tree/main/examples/05_skills_and_plugins/02_loading_plugins/example_plugins)** - See complete plugin structures

## Further Reading

For SDK developers:

* **[SDK Plugins Documentation](/sdk/guides/plugins)** - Detailed SDK integration
* **[Hooks Guide](/sdk/guides/hooks)** - Event handler details
* **[MCP Integration](/sdk/guides/mcp)** - External tool servers