Plugins in the SDK - Claude Code Docs
Documentation Index Fetch the complete documentation index at: /docs/llms.txt Use this file to discover all available pages before exploring further. Skip to main content Assistant Responses are generated using AI and may contain mistakes. Plugins let you 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 capabilities to your agent sessions.
A plugin can include: Skills : capabilities Claude invokes autonomously when relevant. You can also invoke a plugin skill directly with /plugin-name:skill-name . Agents : specialized subagents for specific tasks 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 type field must be "local" , the only value the SDK accepts. The SDK supports loading multiple plugins from different locations. To use a plugin distributed through a marketplace or remote repository, download it first and provide the local directory path. For the directory layout a plugin needs, see the Plugin structure reference below. import { query } from "@anthropic-ai/claude-agent-sdk" ; 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, ClaudeAgentOptions async def main (): async for message in query( prompt = "Hello" , options = ClaudeAgentOptions( 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 the cwd option (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 parent of skills/ , agents/ , hooks/ , commands/ , or .claude-plugin/ .
Reload plugins in a running session To apply a change to a plugin’s skills, commands, agents, or hooks without starting a new session, call reloadPlugins() on the TypeScript SDK’s Query object. The Python SDK doesn’t expose an equivalent method; send /reload-plugins as a prompt in the session instead. Add plugins to a running session In the TypeScript SDK, call reloadPlugins() on the Query object that query() returned, and list the plugin directory in that call’s addPlugins option.
Each addPlugins entry is a { type: "local", path } object with an absolute path . Requires TypeScript Agent SDK v0.3.301 or later. In this example, q is the Query object that query() returned. The example adds one plugin directory to the running session and, after reloadPlugins() returns, prints the path of every plugin in the session: const result = await q . reloadPlugins ({ addPlugins: [{ type: "local" , path: "/home/user/plugins/another-plugin" }] }); console . log ( result . plugins . map (( plugin ) => plugin . path )); If the plugin loaded, the printed list includes /home/user/plugins/another-plugin .
If that path is missing from the list, or reloadPlugins() rejects, see When reloadPlugins() doesn’t load the addPlugins folders for the causes. Verifying plugin installation When plugins load successfully, they appear in the system initialization message. You can verify that your plugins are available: import { query } from "@anthropic-ai/claude-agent-sdk" ; 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: "/absolute/path/to/my-plugin" }] // Plugin skills appear with the plugin name as a prefix console . log ( "Skills:" , message . skills ); // Example: ["my-plugin:greet"] // Plugin commands use the same prefix, and skills appear here too console . log ( "Commands:" , message . slash_commands ); // Example: ["compact", "context", "my-plugin:custom-command", "my-plugin:greet"] } } import asyncio from claude_agent_sdk import query, ClaudeAgentOptions, SystemMessage async def main (): async for message in query( prompt = "Hello" , options = ClaudeAgentOptions( plugins = [{ "type" : "local" , "path" : "./my-plugin" }] ), ): if isinstance (message, SystemMessage) and message.subtype == "init" : # Check loaded plugins print ( "Plugins:" , message.data.get( "plugins" )) # Example: [{"name": "my-plugin", "path": "/absolute/path/to/my-plugin"}] # Plugin skills appear with the plugin name as a prefix print ( "Skills:" , message.data.get( "skills" )) # Example: ["my-plugin:greet"] # Plugin commands use the same prefix, and skills appear here too print ( "Commands:" , message.data.get( "slash_commands" )) # Example: ["compact", "context", "my-plugin:custom-command", "my-plugin:greet"] asyncio.run(main()) Use plugin skills Skills from plugins are automatically namespaced with the plugin name to avoid conflicts.
To invoke one directly, send /plugin-name:skill-name as the prompt. import { query } from "@anthropic-ai/claude-agent-sdk" ; // Load a plugin with a custom /greet skill for await ( const message of query ({ prompt: "/my-plugin:greet" , // Use plugin skill with namespace options: { plugins: [{ type: "local" , path: "./my-plugin" }] } })) { // Claude executes the custom greeting skill from the plugin if ( message . type === "assistant" ) { console . log ( message . message . content ); } } import asyncio from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, TextBlock async def main (): # Load a plugin with a custom /greet skill async for message in query( prompt = "/my-plugin:greet" , # Use plugin skill with namespace options = ClaudeAgentOptions( plugins = [{ "type" : "local" , "path" : "./my-plugin" }] ), ): # Claude executes the custom greeting skill 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 { query } from "@anthropic-ai/claude-agent-sdk" ; import { fileURLToPath } from "node:url" ; async function runWithPlugin () { const pluginPath = fileURLToPath ( new URL ( "./plugins/my-plugin" , import . meta . url )); 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 skills:" , message . skills ); console . log ( "Available commands:" , message . slash_commands ); } if ( message . type === "assistant" ) { console . log ( "Assistant:" , message . message . content ); } } } runWithPlugin (). catch ( console . error ); #!/usr/bin/env python3 """Example demonstrating how to use plugins with the Agent SDK.""" import asyncio from pathlib import Path from claude_agent_sdk import ( AssistantMessage, ClaudeAgentOptions, SystemMessage, TextBlock, query, ) async def run_with_plugin (): """Example usin
The rest of this page is on the live site.