Plugins no SDK

Carregue plugins personalizados para estender Claude Code com comandos, agentes, skills e hooks através do Agent SDK

Plugins permitem que você estenda Claude Code com funcionalidade personalizada que pode ser compartilhada entre projetos. Através do Agent SDK, você pode carregar programaticamente plugins de diretórios locais para adicionar comandos slash personalizados, agentes, skills, hooks e servidores MCP às suas sessões de agente.

O que são plugins?

Plugins são pacotes de extensões Claude Code que podem incluir:

Skills: Capacidades invocadas pelo modelo que Claude usa autonomamente (também podem ser invocadas com /skill-name)
Agents: Subagentes especializados para tarefas específicas
Hooks: Manipuladores de eventos que respondem ao uso de ferramentas e outros eventos
MCP servers: Integrações de ferramentas externas via Model Context Protocol

Para informações completas sobre a estrutura de plugins e como criar plugins, consulte Plugins.

Carregando plugins

Carregue plugins fornecendo seus caminhos do sistema de arquivos local na configuração de opções. O campo type deve ser "local", o único valor que o SDK aceita. Para usar um plugin distribuído através de um marketplace ou repositório remoto, baixe-o primeiro e forneça o caminho do diretório local. O SDK suporta carregamento de múltiplos plugins de diferentes locais.

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

Especificações de caminho

Os caminhos de plugin podem ser:

Caminhos relativos: Resolvidos relativamente ao seu diretório de trabalho atual (por exemplo, "./plugins/my-plugin")
Caminhos absolutos: Caminhos completos do sistema de arquivos (por exemplo, "/home/user/plugins/my-plugin")

Verificando a instalação do plugin

Quando os plugins carregam com sucesso, eles aparecem na mensagem de inicialização do sistema. Você pode verificar que seus plugins estão disponíveis:

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: "./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, 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": "./my-plugin"}]

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


asyncio.run(main())

Usando skills de plugins

Skills de plugins são automaticamente nomeados com o nome do plugin para evitar conflitos. Quando invocados como comandos slash, o formato é plugin-name:skill-name.

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="/demo-plugin:greet",  # Use plugin skill with namespace
options=ClaudeAgentOptions(
plugins=[{"type": "local", "path": "./plugins/demo-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())

Exemplo completo

Aqui está um exemplo completo demonstrando carregamento e uso de plugins:

import { query } from "@anthropic-ai/claude-agent-sdk";
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.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,
SystemMessage,
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 isinstance(message, SystemMessage) 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)

Referência de estrutura de plugin

Um diretório de plugin deve conter um arquivo de manifesto .claude-plugin/plugin.json. Pode opcionalmente incluir:

my-plugin/
├── .claude-plugin/
│   └── plugin.json          # Required: plugin manifest
├── skills/                   # Agent Skills (invoked autonomously or via /skill-name)
│   └── my-skill/
│       └── SKILL.md
├── commands/                 # Legacy: use skills/ instead
│   └── custom-cmd.md
├── agents/                   # Custom agents
│   └── specialist.md
├── hooks/                    # Event handlers
│   └── hooks.json
└── .mcp.json                # MCP server definitions

Para informações detalhadas sobre como criar plugins, consulte:

Plugins - Guia completo de desenvolvimento de plugins
Plugins reference - Especificações técnicas e esquemas

Casos de uso comuns

Desenvolvimento e testes

Carregue plugins durante o desenvolvimento sem instalá-los globalmente:

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

Extensões específicas do projeto

Inclua plugins no seu repositório de projeto para consistência em toda a equipe:

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

Múltiplas fontes de plugin

Combine plugins de diferentes locais:

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

Troubleshooting

Plugin não carregando

Se seu plugin não aparecer na mensagem de inicialização:

Verifique o caminho: Certifique-se de que o caminho aponta para o diretório raiz do plugin (contendo .claude-plugin/)
Valide plugin.json: Certifique-se de que seu arquivo de manifesto tem sintaxe JSON válida
Verifique permissões de arquivo: Certifique-se de que o diretório do plugin é legível

Skills não aparecendo

Se skills de plugins não funcionarem:

Use o namespace: Skills de plugins requerem o formato plugin-name:skill-name quando invocados como comandos slash
Verifique mensagem de inicialização: Verifique se a skill aparece em slash_commands com o namespace correto
Valide arquivos de skill: Certifique-se de que cada skill tem um arquivo SKILL.md em seu próprio subdiretório sob skills/ (por exemplo, skills/my-skill/SKILL.md)

Problemas de resolução de caminho

Se caminhos relativos não funcionarem:

Verifique diretório de trabalho: Caminhos relativos são resolvidos a partir do seu diretório de trabalho atual
Use caminhos absolutos: Para confiabilidade, considere usar caminhos absolutos
Normalize caminhos: Use utilitários de caminho para construir caminhos corretamente

Veja também

Plugins - Guia completo de desenvolvimento de plugins
Plugins reference - Especificações técnicas
Slash Commands - Usando comandos slash no SDK
Subagents - Trabalhando com agentes especializados
Skills - Usando Agent Skills

agent-sdk/plugins.md +16 −10

46 46

47 ```python Python theme={null}47 ```python Python theme={null}

48 import asyncio48 import asyncio

~~49 from claude_agent_sdk import query~~49 from claude_agent_sdk import query, ClaudeAgentOptions

50 50

51 51

52 async def main():52 async def main():

53 async for message in query(53 async for message in query(

54 prompt="Hello",54 prompt="Hello",

~~55 options={~~55 options=ClaudeAgentOptions(

~~56 "plugins": [~~56 plugins=[

57 {"type": "local", "path": "./my-plugin"},57 {"type": "local", "path": "./my-plugin"},

58 {"type": "local", "path": "/absolute/path/to/another-plugin"},58 {"type": "local", "path": "/absolute/path/to/another-plugin"},

59 ]59 ]

~~60 },~~60 ),

61 ):61 ):

62 # Plugin commands, agents, and other features are now available62 # Plugin commands, agents, and other features are now available

63 pass63 pass

106 106

107 ```python Python theme={null}107 ```python Python theme={null}

108 import asyncio108 import asyncio

109 from claude_agent_sdk import query109 from claude_agent_sdk import query, ClaudeAgentOptions, SystemMessage

110 110

111 111

112 async def main():112 async def main():

113 async for message in query(113 async for message in query(

114 prompt="Hello", options={"plugins": [{"type": "local", "path": "./my-plugin"}]}114 prompt="Hello",

115 options=ClaudeAgentOptions(

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

117 ),

115 ):118 ):

116 if message.type == "system" and message.subtype == "init":119 if isinstance(message, SystemMessage) and message.subtype == "init":

117 # Check loaded plugins120 # Check loaded plugins

118 print("Plugins:", message.data.get("plugins"))121 print("Plugins:", message.data.get("plugins"))

119 # Example: [{"name": "my-plugin", "path": "./my-plugin"}]122 # Example: [{"name": "my-plugin", "path": "./my-plugin"}]

151 154

152 ```python Python theme={null}155 ```python Python theme={null}

153 import asyncio156 import asyncio

154 from claude_agent_sdk import query, AssistantMessage, TextBlock157 from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, TextBlock

155 158

156 159

157 async def main():160 async def main():

158 # Load a plugin with a custom /greet skill161 # Load a plugin with a custom /greet skill

159 async for message in query(162 async for message in query(

160 prompt="/demo-plugin:greet", # Use plugin skill with namespace163 prompt="/demo-plugin:greet", # Use plugin skill with namespace

161 options={"plugins": [{"type": "local", "path": "./plugins/demo-plugin"}]},164 options=ClaudeAgentOptions(

165 plugins=[{"type": "local", "path": "./plugins/demo-plugin"}]

166 ),

162 ):167 ):

163 # Claude executes the custom greeting skill from the plugin168 # Claude executes the custom greeting skill from the plugin

164 if isinstance(message, AssistantMessage):169 if isinstance(message, AssistantMessage):

219 from claude_agent_sdk import (224 from claude_agent_sdk import (

220 AssistantMessage,225 AssistantMessage,

221 ClaudeAgentOptions,226 ClaudeAgentOptions,

227 SystemMessage,

222 TextBlock,228 TextBlock,

223 query,229 query,

224 )230 )

238 async for message in query(244 async for message in query(

239 prompt="What custom commands do you have available?", options=options245 prompt="What custom commands do you have available?", options=options

240 ):246 ):

241 if message.type == "system" and message.subtype == "init":247 if isinstance(message, SystemMessage) and message.subtype == "init":

242 print(f"Loaded plugins: {message.data.get('plugins')}")248 print(f"Loaded plugins: {message.data.get('plugins')}")

243 print(f"Available commands: {message.data.get('slash_commands')}")249 print(f"Available commands: {message.data.get('slash_commands')}")

244 250

agent-sdk/plugins.md 2026-05-14 17:02 UTC to 2026-05-15 22:58 UTC

Plugins no SDK

O que são plugins?

Carregando plugins

Especificações de caminho

Verificando a instalação do plugin

Usando skills de plugins

Exemplo completo

Referência de estrutura de plugin

Casos de uso comuns

Desenvolvimento e testes

Extensões específicas do projeto

Múltiplas fontes de plugin

Troubleshooting

Plugin não carregando

Skills não aparecendo

Problemas de resolução de caminho

Veja também