Plugins ↗

anthropic-platform guide intermediate agents plugins

Editorial Notes

Plugins extend the Agent SDK’s core behavior by hooking into the agent lifecycle at well-defined extension points, enabling cross-cutting concerns like logging, rate limiting, and custom authentication without modifying agent logic directly. Focus on the plugin interface and the ordering guarantees for plugin execution — multiple plugins can compose, but execution order matters for plugins that modify requests or responses. A common mistake is putting business logic inside plugins rather than skills, which makes agents harder to test and reason about. Read this after understanding skills to appreciate the boundary between agent capabilities and infrastructure concerns.

Original Documentation

Load custom plugins to extend Claude Code with commands, agents, skills, and hooks through the Agent SDK

Plugins allow you to extend Claude Code with custom functionality that can be shared across projects. Through the Agent SDK, you can programmatically load plugins from local directories to add custom slash commands, agents, skills, hooks, and MCP servers to your agent sessions.

What are plugins?#

Plugins are packages of Claude Code extensions that can include:

Commands: Custom slash commands
Agents: Specialized subagents for specific tasks
Skills: Model-invoked capabilities that Claude uses autonomously
Hooks: Event handlers that respond to tool use and other events
MCP servers: External tool integrations via Model Context Protocol

For complete information on plugin structure and how to create plugins, see Plugins.

Loading plugins#

Load plugins by providing their local file system paths in your options configuration. The SDK supports loading multiple plugins from different locations.


for await (const message of query({
  prompt: "Hello",
  options: {
    plugins: [
      { type: "local", path: "./my-plugin" },
      { type: "local", path: "/absolute/path/to/another-plugin" }
    ]
  }
})) {
  // Plugin commands, agents, and other features are now available
}

import asyncio
from claude_agent_sdk import query


async def main():
    async for message in query(
        prompt="Hello",
        options={
            "plugins": [
                {"type": "local", "path": "./my-plugin"},
                {"type": "local", "path": "/absolute/path/to/another-plugin"},
            ]
        },
    ):
        # Plugin commands, agents, and other features are now available
        pass


asyncio.run(main())

Path specifications#

Plugin paths can be:

Relative paths: Resolved relative to your current working directory (for example, "./plugins/my-plugin")
Absolute paths: Full file system paths (for example, "/home/user/plugins/my-plugin")

The path should point to the plugin’s root directory (the directory containing .claude-plugin/plugin.json).

Verifying plugin installation#

When plugins load successfully, they appear in the system initialization message. You can verify that your plugins are available:


for await (const message of query({
  prompt: "Hello",
  options: {
    plugins: [{ type: "local", path: "./my-plugin" }]
  }
})) {
  if (message.type === "system" && message.subtype === "init") {
    // Check loaded plugins
    console.log("Plugins:", message.plugins);
    // Example: [{ name: "my-plugin", path: "./my-plugin" }]

    // Check available commands from plugins
    console.log("Commands:", message.slash_commands);
    // Example: ["/help", "/compact", "my-plugin:custom-command"]
  }
}

import asyncio
from claude_agent_sdk import query


async def main():
    async for message in query(
        prompt="Hello", options={"plugins": [{"type": "local", "path": "./my-plugin"}]}
    ):
        if message.type == "system" and message.subtype == "init":
            # Check loaded plugins
            print("Plugins:", message.data.get("plugins"))
            # Example: [{"name": "my-plugin", "path": "./my-plugin"}]

            # Check available commands from plugins
            print("Commands:", message.data.get("slash_commands"))
            # Example: ["/help", "/compact", "my-plugin:custom-command"]


asyncio.run(main())

Using plugin commands#

Commands from plugins are automatically namespaced with the plugin name to avoid conflicts. The format is plugin-name:command-name.


// Load a plugin with a custom /greet command
for await (const message of query({
  prompt: "/my-plugin:greet", // Use plugin command with namespace
  options: {
    plugins: [{ type: "local", path: "./my-plugin" }]
  }
})) {
  // Claude executes the custom greeting command from the plugin
  if (message.type === "assistant") {
    console.log(message.content);
  }
}

import asyncio
from claude_agent_sdk import query, AssistantMessage, TextBlock


async def main():
    # Load a plugin with a custom /greet command
    async for message in query(
        prompt="/demo-plugin:greet",  # Use plugin command with namespace
        options={"plugins": [{"type": "local", "path": "./plugins/demo-plugin"}]},
    ):
        # Claude executes the custom greeting command from the plugin
        if isinstance(message, AssistantMessage):
            for block in message.content:
                if isinstance(block, TextBlock):
                    print(f"Claude: {block.text}")


asyncio.run(main())

If you installed a plugin via the CLI (for example, /plugin install my-plugin@marketplace), you can still use it in the SDK by providing its installation path. Check ~/.claude/plugins/ for CLI-installed plugins.

Complete example#

Here’s a full example demonstrating plugin loading and usage:


import * as path from "path";

async function runWithPlugin() {
  const pluginPath = path.join(__dirname, "plugins", "my-plugin");

  console.log("Loading plugin from:", pluginPath);

  for await (const message of query({
    prompt: "What custom commands do you have available?",
    options: {
      plugins: [{ type: "local", path: pluginPath }],
      maxTurns: 3
    }
  })) {
    if (message.type === "system" && message.subtype === "init") {
      console.log("Loaded plugins:", message.plugins);
      console.log("Available commands:", message.slash_commands);
    }

    if (message.type === "assistant") {
      console.log("Assistant:", message.content);
    }
  }
}

runWithPlugin().catch(console.error);

#!/usr/bin/env python3
"""Example demonstrating how to use plugins with the Agent SDK."""

from pathlib import Path
import anyio
from claude_agent_sdk import (
    AssistantMessage,
    ClaudeAgentOptions,
    TextBlock,
    query,
)


async def run_with_plugin():
    """Example using a custom plugin."""
    plugin_path = Path(__file__).parent / "plugins" / "demo-plugin"

    print(f"Loading plugin from: {plugin_path}")

    options = ClaudeAgentOptions(
        plugins=[{"type": "local", "path": str(plugin_path)}],
        max_turns=3,
    )

    async for message in query(
        prompt="What custom commands do you have available?", options=options
    ):
        if message.type == "system" and message.subtype == "init":
            print(f"Loaded plugins: {message.data.get('plugins')}")
            print(f"Available commands: {message.data.get('slash_commands')}")

        if isinstance(message, AssistantMessage):
            for block in message.content:
                if isinstance(block, TextBlock):
                    print(f"Assistant: {block.text}")


if __name__ == "__main__":
    anyio.run(run_with_plugin)

Plugin structure reference#

A plugin directory must contain a .claude-plugin/plugin.json manifest file. It can optionally include:

my-plugin/
├── .claude-plugin/
│   └── plugin.json          # Required: plugin manifest
├── commands/                 # Custom slash commands
│   └── custom-cmd.md
├── agents/                   # Custom agents
│   └── specialist.md
├── skills/                   # Agent Skills
│   └── my-skill/
│       └── SKILL.md
├── hooks/                    # Event handlers
│   └── hooks.json
└── .mcp.json                # MCP server definitions

For detailed information on creating plugins, see:

Plugins - Complete plugin development guide
Plugins reference - Technical specifications and schemas

Common use cases#

Development and testing#

Load plugins during development without installing them globally:

plugins: [{ type: "local", path: "./dev-plugins/my-plugin" }];

Project-specific extensions#

Include plugins in your project repository for team-wide consistency:

plugins: [{ type: "local", path: "./project-plugins/team-workflows" }];

Multiple plugin sources#

Combine plugins from different locations:

plugins: [
  { type: "local", path: "./local-plugin" },
  { type: "local", path: "~/.claude/custom-plugins/shared-plugin" }
];

Troubleshooting#

Plugin not loading#

If your plugin doesn’t appear in the init message:

Check the path: Ensure the path points to the plugin root directory (containing .claude-plugin/)
Validate plugin.json: Ensure your manifest file has valid JSON syntax
Check file permissions: Ensure the plugin directory is readable

Commands not available#

If plugin commands don’t work:

Use the namespace: Plugin commands require the plugin-name:command-name format
Check init message: Verify the command appears in slash_commands with the correct namespace
Validate command files: Ensure command markdown files are in the commands/ directory

Path resolution issues#

If relative paths don’t work:

Check working directory: Relative paths are resolved from your current working directory
Use absolute paths: For reliability, consider using absolute paths
Normalize paths: Use path utilities to construct paths correctly