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
}

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

O caminho deve apontar para o diretório raiz do plugin (o diretório contendo .claude-plugin/plugin.json).

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:

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.

Se você instalou um plugin via CLI (por exemplo, /plugin install my-plugin@marketplace), você ainda pode usá-lo no SDK fornecendo seu caminho de instalação. Verifique ~/.claude/plugins/ para plugins instalados via CLI.

Exemplo completo

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

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:

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

Comandos não disponíveis

Se os comandos do plugin não funcionarem:

Use o namespace: Comandos de plugin requerem o formato plugin-name:command-name
Verifique a mensagem de inicialização: Verifique se o comando aparece em slash_commands com o namespace correto
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:

Verifique o 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
Referência de Plugins - Especificações técnicas
Comandos Slash - Usando comandos slash no SDK
Subagentes - Trabalhando com agentes especializados
Habilidades - Usando Agent Skills

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

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