Pular para o conteúdo principal
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
O diretório commands/ é um formato legado. Use skills/ para novos plugins. Claude Code continua suportando ambos os formatos para compatibilidade com versões anteriores.
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
}

​
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")
O caminho deve apontar para o diretório raiz do plugin: o diretório pai de skills/, agents/, hooks/, commands/ (legado), ou .claude-plugin/, não um subdiretório.

​
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"]
  }
}

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

​
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:

​
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:
  1. 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/
  2. Valide plugin.json: se seu plugin inclui um manifesto, certifique-se de que ele tem sintaxe JSON válida
  3. 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:
  1. Use o namespace: invoque skills de plugins como /plugin-name:skill-name
  2. Verifique mensagem de inicialização: verifique se a skill aparece na lista skills com o namespace correto
  3. 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:
  1. Verifique 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