Plugins no 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, habilidades, 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:

• Comandos: Comandos slash personalizados
• Agentes: Subagentes especializados para tarefas específicas
• Habilidades: Capacidades invocadas pelo modelo que Claude usa autonomamente
• Hooks: Manipuladores de eventos que respondem ao uso de ferramentas e outros eventos
• Servidores MCP: 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 SDK suporta o 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

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

Especificações de caminho

Os caminhos de plugin podem ser:

• Caminhos relativos: Resolvidos em relação 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 se 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"]
  }
}

Usando comandos de plugin

Comandos de plugins são automaticamente nomeados com o nome do plugin para evitar conflitos. O formato é plugin-name:command-name.

import { query } from "@anthropic-ai/claude-agent-sdk";

// 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);
  }
}

Exemplo completo

Aqui está um exemplo completo demonstrando o 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.content);
    }
  }
}

runWithPlugin().catch(console.error);

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
├── 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

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

• Plugins - Guia completo de desenvolvimento de plugins
• Referência de Plugins - 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" }
]

Solução de problemas

Plugin não carregando

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

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

Comandos não disponíveis

Se os comandos do plugin não funcionarem:

1. Use o namespace: Comandos de plugin requerem o formato plugin-name:command-name
2. Verifique a mensagem de inicialização: Verifique se o comando aparece em slash_commands com o namespace correto
3. Valide arquivos de comando: Certifique-se de que os arquivos de markdown de comando estão no diretório commands/

Problemas de resolução de caminho

Se caminhos relativos não funcionarem:

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

Veja também

• Plugins - Guia completo de desenvolvimento de plugins
• Referência de Plugins - Especificações técnicas
• Comandos Slash - Usando comandos slash no SDK
• Subagentes - Trabalhando com agentes especializados
• Habilidades - Usando Agent Skills