Plugins

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.

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

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

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
SDK
Local GUI
OpenHands Cloud

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.

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.

Via UI:

Open Settings
Navigate to Plugins section
Add plugin path or GitHub URL
Restart to load

Via file system: Place plugins in .openhands/plugins/ in your workspace.

Installing Plugins

From a Local Directory

Verify plugin structure:

ls plugin-dir/.plugin/plugin.json || ls plugin-dir/.claude-plugin/plugin.json

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/extensionsCommunity-maintained plugins

Custom Repositories

Your own GitHub repositoriesOrganization 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

Start with Skills

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

Add Automation with Hooks

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

Integrate External Tools

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

Document Thoroughly

Include a comprehensive README explaining:

What the plugin does
How to install it
Configuration options
Example usage

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

​What Are Plugins?

​Plugins vs Skills

Skills

Plugins

​Comparison Table

​When to Use Each

​Plugin Structure

​Required Components

​Plugin Metadata

​Plugin Components Explained

​Using Plugins

​Installing Plugins

​From a Local Directory

​From GitHub

​Plugin Sources

Official Registry

Custom Repositories

​Creating Plugins

​1. Plan Your Components

​2. Create Directory Structure

​3. Create Plugin Metadata

​4. Add Components

​5. Test Locally

​6. Distribute

​Plugin Examples

Code Quality Plugin

DevOps Plugin

API Integration Plugin

Testing Plugin

​Plugin Development Best Practices

​Troubleshooting

​Next Steps

​Further Reading

What Are Plugins?

Plugins vs Skills

Comparison Table

When to Use Each

Plugin Structure

Required Components

Plugin Metadata

Plugin Components Explained

Using Plugins

Installing Plugins

From a Local Directory

From GitHub

Plugin Sources

Creating Plugins

1. Plan Your Components

2. Create Directory Structure

3. Create Plugin Metadata

4. Add Components

5. Test Locally

6. Distribute

Plugin Examples

Plugin Development Best Practices

Troubleshooting

Next Steps

Further Reading