Skip to main content
Plugins provide a way to package and distribute multiple agent components together. A single plugin can include:
  • 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.

​
Plugin Structure

See the example_plugins directory for a complete working plugin structure.
A plugin follows this directory structure:
plugin-name
.plugin
plugin.json
skills
hooks
hooks.json
agents
agent-name.md
commands
command-name.md
.mcp.json
README.md
Note that the plugin metadata, i.e., plugin-name/.plugin/plugin.json, is required.

​
Plugin Manifest

The manifest file plugin-name/.plugin/plugin.json defines plugin metadata: 
{
  "name": "code-quality",
  "version": "1.0.0",
  "description": "Code quality tools and workflows",
  "author": "openhands",
  "license": "MIT",
  "repository": "https://github.com/example/code-quality-plugin"
}

​
Skills

Skills are defined in markdown files with YAML frontmatter: 
---
name: python-linting
description: Instructions for linting Python code
trigger:
  type: keyword
  keywords:
    - lint
    - linting
    - code quality
---

# Python Linting Skill

Run ruff to check for issues:

\`\`\`bash
ruff check .
\`\`\`

​
Hooks

Hooks are defined in hooks/hooks.json: 
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "file_editor",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'File edited: $OPENHANDS_TOOL_NAME'",
            "timeout": 5
          }
        ]
      }
    ]
  }
}

​
MCP Configuration

MCP servers are configured in .mcp.json: 
{
  "mcpServers": {
    "fetch": {
      "command": "uvx",
      "args": ["mcp-server-fetch"]
    }
  }
}

​
Using Plugin Components

The ready-to-run example is available here!
Brief explanation on how to use a plugin with an agent.
1

​
Loading a Plugin

First, load the desired plugins.
from openhands.sdk.plugin import Plugin

# Load a single plugin
plugin = Plugin.load("/path/to/plugin")

# Load all plugins from a directory
plugins = Plugin.load_all("/path/to/plugins")
2

​
Accessing Components

You can access the different plugin components to see which ones are available.
# Skills
for skill in plugin.skills:
    print(f"Skill: {skill.name}")

# Hooks configuration
if plugin.hooks:
    print(f"Hooks configured: {plugin.hooks}")

# MCP servers
if plugin.mcp_config:
    servers = plugin.mcp_config.get("mcpServers", {})
    print(f"MCP servers: {list(servers.keys())}")
3

​
Using with an Agent

You can now feed your agent with your preferred plugin.
# Create agent context with plugin skills
agent_context = AgentContext(
    skills=plugin.skills,
)

# Create agent with plugin MCP config
agent = Agent(
    llm=llm,
    tools=tools,
    mcp_config=plugin.mcp_config or {},
    agent_context=agent_context,
)

# Create conversation with plugin hooks
conversation = Conversation(
    agent=agent,
    hook_config=plugin.hooks,
)

​
Ready-to-run Example

This example is available on GitHub: examples/05_skills_and_plugins/02_loading_plugins/main.py
examples/05_skills_and_plugins/02_loading_plugins/main.py
"""Example: Loading Plugins via Conversation

Demonstrates the recommended way to load plugins using the `plugins` parameter
on Conversation. Plugins bundle skills, hooks, and MCP config together.

For full documentation, see: https://docs.all-hands.dev/sdk/guides/plugins
"""

import os
import sys
import tempfile
from pathlib import Path

from pydantic import SecretStr

from openhands.sdk import LLM, Agent, Conversation
from openhands.sdk.plugin import PluginSource
from openhands.sdk.tool import Tool
from openhands.tools.file_editor import FileEditorTool
from openhands.tools.terminal import TerminalTool


# Locate example plugin directory
script_dir = Path(__file__).parent
plugin_path = script_dir / "example_plugins" / "code-quality"

# Define plugins to load
# Supported sources: local path, "github:owner/repo", or git URL
# Optional: ref (branch/tag/commit), repo_path (for monorepos)
plugins = [
    PluginSource(source=str(plugin_path)),
    # PluginSource(source="github:org/security-plugin", ref="v2.0.0"),
    # PluginSource(source="github:org/monorepo", repo_path="plugins/logging"),
]

# Check for API key
api_key = os.getenv("LLM_API_KEY")
if not api_key:
    print("Set LLM_API_KEY to run this example")
    print("EXAMPLE_COST: 0")
    sys.exit(0)

# Configure LLM and Agent
model = os.getenv("LLM_MODEL", "anthropic/claude-sonnet-4-5-20250929")
llm = LLM(
    usage_id="plugin-demo",
    model=model,
    api_key=SecretStr(api_key),
    base_url=os.getenv("LLM_BASE_URL"),
)
agent = Agent(
    llm=llm, tools=[Tool(name=TerminalTool.name), Tool(name=FileEditorTool.name)]
)

# Create conversation with plugins - skills, MCP config, and hooks are merged
# Note: Plugins are loaded lazily on first send_message() or run() call
with tempfile.TemporaryDirectory() as tmpdir:
    conversation = Conversation(
        agent=agent,
        workspace=tmpdir,
        plugins=plugins,
    )

    # Test: The "lint" keyword triggers the python-linting skill
    # This first send_message() call triggers lazy plugin loading
    conversation.send_message("How do I lint Python code? Brief answer please.")

    # Verify skills were loaded from the plugin (after lazy loading)
    skills = (
        conversation.agent.agent_context.skills
        if conversation.agent.agent_context
        else []
    )
    print(f"Loaded {len(skills)} skill(s) from plugins")

    conversation.run()

    print(f"EXAMPLE_COST: {llm.metrics.accumulated_cost:.4f}")
You can run the example code as-is.
The model name should follow the LiteLLM convention: provider/model_name (e.g., anthropic/claude-sonnet-4-5-20250929, openai/gpt-4o). The LLM_API_KEY should be the API key for your chosen provider.
ChatGPT Plus/Pro subscribers: You can use LLM.subscription_login() to authenticate with your ChatGPT account and access Codex models without consuming API credits. See the LLM Subscriptions guide for details.

​
Next Steps

  • Skills - Learn more about skills and triggers
  • Hooks - Understand hook event types
  • MCP Integration - Configure external tool servers