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

The plugin format is compatible with the Claude Code plugin structure. Both .plugin/ (OpenHands-native) and .claude-plugin/ (Claude Code compatible) directory names are supported for the metadata directory.

OpenHands also loads packages published in the portable Agent Plugins format, which places plugin.json at the package root instead of in a metadata directory.

Plugins vs Skills

Understanding the difference helps you choose the right approach:

Skills

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

Plugins

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

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:

{
  "name": "code-quality",
  "version": "1.0.0",
  "description": "Code quality tools and workflows",
  "author": {
    "name": "Your Name",
    "email": "[e-mail]"
  },
  "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

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 for skill creation details.

Hooks

Hooks are event handlers that run during tool lifecycle events:

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

MCP Configuration

MCP (Model Context Protocol) servers provide external tools and resources:

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

Agents

Specialized agent definitions for specific tasks:

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

Commands

Custom slash commands for plugin functionality:

---
name: /lint
description: Run linters on current file
---

# Lint Command

Run configured linters on the current file...

Commands provide quick access to plugin features.

Using Plugins

How you use plugins depends on your platform:

CLI

Via configuration file:

Create ~/.openhands/config.toml:

[plugins]
sources = [
  "/path/to/local/plugin",
  "github:org/plugin-repo",
]

Via command line:

openhands --plugin /path/to/plugin
openhands --plugin github:org/plugin-repo

Plugins are loaded when OpenHands starts.

SDK

Load plugins programmatically:

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 for details.

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.

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.

Installing Plugins

From a Local Directory

1. Verify plugin structure:

   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

Official Registry

github.com/OpenHands/extensions

Community-maintained plugins

Custom Repositories

Your own GitHub repositories

Organization or private plugins

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

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

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

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

Code Quality Plugin

Contains:

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

Use case: Enforce code standards

DevOps Plugin

Contains:

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

Use case: Infrastructure management

API Integration Plugin

Contains:

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

Use case: External service integration

Testing Plugin

Contains:

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

Use case: Automated testing

Plugin Development Best Practices

1. Start with Skills

   Begin by creating the core skills your plugin needs. Test them individually before bundling.

2. Add Automation with Hooks

   Identify repetitive tasks and automate them with hooks. Example: run linters after file edits.

3. Integrate External Tools

   Add MCP servers for external tool integration. This provides your skills with additional capabilities.

4. Document Thoroughly

   Include a comprehensive README explaining:

   • What the plugin does
   • How to install it
   • Configuration options
   • Example usage
5. Version Carefully

   Use semantic versioning (major.minor.patch) and document breaking changes.

Troubleshooting

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:

# 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

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.

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.

Next Steps

• Learn about Skills - Understand the core component of plugins
• Explore MCP - Add external tool integrations
• SDK Plugins Guide - Programmatic plugin usage
• Browse Examples - See complete plugin structures

Further Reading

For SDK developers:

• SDK Plugins Documentation - Detailed SDK integration
• Hooks Guide - Event handler details
• MCP Integration - External tool servers