Plugins no SDK
Carregue plugins personalizados para estender Claude Code com skills, agentes, hooks e servidores MCP 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 skills, agentes, 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") {
// Verificar plugins carregados
console.log("Plugins:", message.plugins);
// Exemplo: [{ name: "my-plugin", path: "./my-plugin" }]
// As skills do plugin aparecem com o nome do plugin como prefixo
console.log("Skills:", message.skills);
// Exemplo: ["my-plugin:greet"]
// Os comandos do plugin usam o mesmo prefixo, e as skills aparecem aqui também
console.log("Commands:", message.slash_commands);
// Exemplo: ["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":
# Verificar plugins carregados
print("Plugins:", message.data.get("plugins"))
# Exemplo: [{"name": "my-plugin", "path": "./my-plugin"}]
# As skills do plugin aparecem com o nome do plugin como prefixo
print("Skills:", message.data.get("skills"))
# Exemplo: ["my-plugin:greet"]
# Os comandos do plugin usam o mesmo prefixo, e as skills aparecem aqui também
print("Commands:", message.data.get("slash_commands"))
# Exemplo: ["compact", "context", "my-plugin:custom-command", "my-plugin:greet"]
asyncio.run(main())
Usando skills de plugins
Skills de plugins são automaticamente nomeados com o nome do plugin para evitar conflitos. Para invocar um diretamente, envie /plugin-name:skill-name como o 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="/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 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."""
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 skills: {message.data.get('skills')}")
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 normalmente contém um arquivo de manifesto .claude-plugin/plugin.json. O manifesto é opcional. Quando omitido, Claude Code descobre automaticamente componentes a partir do layout do diretório. O diretório pode incluir:
my-plugin/
├── .claude-plugin/
│ └── plugin.json # Manifesto de plugin (opcional, componentes descobertos automaticamente sem ele)
├── skills/ # Agent Skills (invocadas autonomamente ou via /skill-name)
│ └── my-skill/
│ └── SKILL.md
├── commands/ # Legado: use skills/ em vez disso
│ └── custom-cmd.md
├── agents/ # Agentes personalizados
│ └── specialist.md
├── hooks/ # Manipuladores de eventos
│ └── hooks.json
└── .mcp.json # Definições de servidor MCP
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, o pai de
skills/,agents/,hooks/,commands/(legado), ou.claude-plugin/ - Valide plugin.json: se seu plugin inclui um manifesto, certifique-se de que ele 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: invoque skills de plugins como
/plugin-name:skill-name - Verifique mensagem de inicialização: verifique se a skill aparece na lista
skillscom o namespace correto - Valide arquivos de skill: certifique-se de que cada skill tem um arquivo
SKILL.mdem seu próprio subdiretório sobskills/, por exemploskills/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
- Commands - Usando comandos no SDK
- Subagents - Trabalhando com agentes especializados
- Skills - Usando Agent Skills