Referência de plugins

Para tutoriais práticos e uso prático, veja Plugins. Para gerenciamento de plugins em equipes e comunidades, veja Marketplaces de plugins.

Esta referência fornece especificações técnicas completas para o sistema de plugins do Claude Code, incluindo esquemas de componentes, comandos CLI e ferramentas de desenvolvimento.

Referência de componentes de plugins

Esta seção documenta os quatro tipos de componentes que os plugins podem fornecer.

Comandos

Os plugins adicionam comandos de barra personalizados que se integram perfeitamente com o sistema de comandos do Claude Code. Localização: diretório commands/ na raiz do plugin Formato do arquivo: arquivos Markdown com frontmatter Para detalhes completos sobre estrutura de comandos de plugin, padrões de invocação e recursos, veja Comandos de plugin.

Agentes

Os plugins podem fornecer subagentes especializados para tarefas específicas que o Claude pode invocar automaticamente quando apropriado. Localização: diretório agents/ na raiz do plugin Formato do arquivo: arquivos Markdown descrevendo capacidades do agente Estrutura do agente:

---
description: No que este agente se especializa
capabilities: ["tarefa1", "tarefa2", "tarefa3"]
---

# Nome do Agente

Descrição detalhada do papel do agente, expertise e quando o Claude deve invocá-lo.

## Capacidades
- Tarefa específica na qual o agente se destaca
- Outra capacidade especializada
- Quando usar este agente vs outros

## Contexto e exemplos
Forneça exemplos de quando este agente deve ser usado e que tipos de problemas ele resolve.

Pontos de integração:

Agentes aparecem na interface /agents
Claude pode invocar agentes automaticamente baseado no contexto da tarefa
Agentes podem ser invocados manualmente pelos usuários
Agentes de plugin funcionam junto com agentes integrados do Claude

Hooks

Os plugins podem fornecer manipuladores de eventos que respondem a eventos do Claude Code automaticamente. Localização: hooks/hooks.json na raiz do plugin, ou inline em plugin.json Formato: configuração JSON com correspondentes de eventos e ações Configuração de hook:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/format-code.sh"
          }
        ]
      }
    ]
  }
}

Eventos disponíveis:

PreToolUse: Antes do Claude usar qualquer ferramenta
PostToolUse: Depois do Claude usar qualquer ferramenta
UserPromptSubmit: Quando o usuário submete um prompt
Notification: Quando o Claude Code envia notificações
Stop: Quando o Claude tenta parar
SubagentStop: Quando um subagente tenta parar
SessionStart: No início das sessões
SessionEnd: No final das sessões
PreCompact: Antes do histórico da conversa ser compactado

Tipos de hook:

command: Executar comandos shell ou scripts
validation: Validar conteúdos de arquivo ou estado do projeto
notification: Enviar alertas ou atualizações de status

Servidores MCP

Os plugins podem agrupar servidores Model Context Protocol (MCP) para conectar o Claude Code com ferramentas e serviços externos. Localização: .mcp.json na raiz do plugin, ou inline em plugin.json Formato: configuração padrão de servidor MCP Configuração de servidor MCP:

{
  "mcpServers": {
    "plugin-database": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
      "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],
      "env": {
        "DB_PATH": "${CLAUDE_PLUGIN_ROOT}/data"
      }
    },
    "plugin-api-client": {
      "command": "npx",
      "args": ["@company/mcp-server", "--plugin-mode"],
      "cwd": "${CLAUDE_PLUGIN_ROOT}"
    }
  }
}

Comportamento de integração:

Servidores MCP de plugin iniciam automaticamente quando o plugin é habilitado
Servidores aparecem como ferramentas MCP padrão no toolkit do Claude
Capacidades do servidor se integram perfeitamente com ferramentas existentes do Claude
Servidores de plugin podem ser configurados independentemente dos servidores MCP do usuário

Esquema de manifesto de plugin

O arquivo plugin.json define os metadados e configuração do seu plugin. Esta seção documenta todos os campos e opções suportados.

Esquema completo

{
  "name": "plugin-name",
  "version": "1.2.0",
  "description": "Breve descrição do plugin",
  "author": {
    "name": "Nome do Autor",
    "email": "[email protected]",
    "url": "https://github.com/autor"
  },
  "homepage": "https://docs.exemplo.com/plugin",
  "repository": "https://github.com/autor/plugin",
  "license": "MIT",
  "keywords": ["palavra-chave1", "palavra-chave2"],
  "commands": ["./custom/commands/special.md"],
  "agents": "./custom/agents/",
  "hooks": "./config/hooks.json",
  "mcpServers": "./mcp-config.json"
}

Campos obrigatórios

Campo	Tipo	Descrição	Exemplo
`name`	string	Identificador único (kebab-case, sem espaços)	`"deployment-tools"`

Campos de metadados

Campo	Tipo	Descrição	Exemplo
`version`	string	Versão semântica	`"2.1.0"`
`description`	string	Breve explicação do propósito do plugin	`"Ferramentas de automação de deployment"`
`author`	object	Informações do autor	`{"name": "Equipe Dev", "email": "[email protected]"}`
`homepage`	string	URL da documentação	`"https://docs.exemplo.com"`
`repository`	string	URL do código fonte	`"https://github.com/usuario/plugin"`
`license`	string	Identificador da licença	`"MIT"`, `"Apache-2.0"`
`keywords`	array	Tags de descoberta	`["deployment", "ci-cd"]`

Campos de caminho de componente

Campo	Tipo	Descrição	Exemplo
`commands`	string\|array	Arquivos/diretórios de comando adicionais	`"./custom/cmd.md"` ou `["./cmd1.md"]`
`agents`	string\|array	Arquivos de agente adicionais	`"./custom/agents/"`
`hooks`	string\|object	Caminho de config de hook ou config inline	`"./hooks.json"`
`mcpServers`	string\|object	Caminho de config MCP ou config inline	`"./mcp.json"`

Regras de comportamento de caminho

Importante: Caminhos personalizados complementam diretórios padrão - eles não os substituem.

Se commands/ existir, é carregado além dos caminhos de comando personalizados
Todos os caminhos devem ser relativos à raiz do plugin e começar com ./
Comandos de caminhos personalizados usam as mesmas regras de nomenclatura e namespace
Múltiplos caminhos podem ser especificados como arrays para flexibilidade

Exemplos de caminho:

{
  "commands": [
    "./specialized/deploy.md",
    "./utilities/batch-process.md"
  ],
  "agents": [
    "./custom-agents/reviewer.md",
    "./custom-agents/tester.md"
  ]
}

Variáveis de ambiente

${CLAUDE_PLUGIN_ROOT}: Contém o caminho absoluto para o diretório do seu plugin. Use isso em hooks, servidores MCP e scripts para garantir caminhos corretos independentemente da localização de instalação.

{
  "hooks": {
    "PostToolUse": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/process.sh"
          }
        ]
      }
    ]
  }
}

Estrutura de diretório de plugin

Layout padrão de plugin

Um plugin completo segue esta estrutura:

enterprise-plugin/
├── .claude-plugin/           # Diretório de metadados
│   └── plugin.json          # Obrigatório: manifesto do plugin
├── commands/                 # Localização padrão de comando
│   ├── status.md
│   └──  logs.md
├── agents/                   # Localização padrão de agente
│   ├── security-reviewer.md
│   ├── performance-tester.md
│   └── compliance-checker.md
├── hooks/                    # Configurações de hook
│   ├── hooks.json           # Config principal de hook
│   └── security-hooks.json  # Hooks adicionais
├── .mcp.json                # Definições de servidor MCP
├── scripts/                 # Scripts de hook e utilitários
│   ├── security-scan.sh
│   ├── format-code.py
│   └── deploy.js
├── LICENSE                  # Arquivo de licença
└── CHANGELOG.md             # Histórico de versões

O diretório .claude-plugin/ contém o arquivo plugin.json. Todos os outros diretórios (commands/, agents/, hooks/) devem estar na raiz do plugin, não dentro de .claude-plugin/.

Referência de localizações de arquivo

Componente	Localização Padrão	Propósito
Manifesto	`.claude-plugin/plugin.json`	Arquivo de metadados obrigatório
Comandos	`commands/`	Arquivos markdown de comando de barra
Agentes	`agents/`	Arquivos markdown de subagente
Hooks	`hooks/hooks.json`	Configuração de hook
Servidores MCP	`.mcp.json`	Definições de servidor MCP

Ferramentas de debugging e desenvolvimento

Comandos de debugging

Use claude --debug para ver detalhes de carregamento de plugin:

claude --debug

Isso mostra:

Quais plugins estão sendo carregados
Quaisquer erros em manifestos de plugin
Registro de comando, agente e hook
Inicialização de servidor MCP

Problemas comuns

Problema	Causa	Solução
Plugin não carregando	`plugin.json` inválido	Validar sintaxe JSON
Comandos não aparecendo	Estrutura de diretório incorreta	Garantir `commands/` na raiz, não em `.claude-plugin/`
Hooks não disparando	Script não executável	Executar `chmod +x script.sh`
Servidor MCP falha	`${CLAUDE_PLUGIN_ROOT}` ausente	Usar variável para todos os caminhos de plugin
Erros de caminho	Caminhos absolutos usados	Todos os caminhos devem ser relativos e começar com `./`

Referência de distribuição e versionamento

Gerenciamento de versão

Siga versionamento semântico para lançamentos de plugin:


## Veja também

- [Plugins](/pt/docs/claude-code/plugins) - Tutoriais e uso prático
- [Marketplaces de plugins](/pt/docs/claude-code/plugin-marketplaces) - Criando e gerenciando marketplaces
- [Comandos de barra](/pt/docs/claude-code/slash-commands) - Detalhes de desenvolvimento de comando
- [Subagentes](/pt/docs/claude-code/sub-agents) - Configuração e capacidades de agente
- [Hooks](/pt/docs/claude-code/hooks) - Manipulação de eventos e automação
- [MCP](/pt/docs/claude-code/mcp) - Integração de ferramentas externas
- [Configurações](/pt/docs/claude-code/settings) - Opções de configuração para plugins

Começando

Construir com Claude Code

Claude Code SDK

Implantação

Administração

Configuração

Referência

Recursos

Referência de plugins

Referência de componentes de plugins

Comandos

Agentes

Hooks

Servidores MCP

Esquema de manifesto de plugin

Esquema completo

Campos obrigatórios

Campos de metadados

Campos de caminho de componente

Regras de comportamento de caminho

Variáveis de ambiente

Estrutura de diretório de plugin

Layout padrão de plugin

Referência de localizações de arquivo

Ferramentas de debugging e desenvolvimento

Comandos de debugging

Problemas comuns

Referência de distribuição e versionamento

Gerenciamento de versão

Começando

Construir com Claude Code

Claude Code SDK

Implantação

Administração

Configuração

Referência

Recursos

​Referência de componentes de plugins

​Comandos

​Agentes

​Hooks

​Servidores MCP

​Esquema de manifesto de plugin

​Esquema completo

​Campos obrigatórios

​Campos de metadados

​Campos de caminho de componente

​Regras de comportamento de caminho

​Variáveis de ambiente

​Estrutura de diretório de plugin

​Layout padrão de plugin

​Referência de localizações de arquivo

​Ferramentas de debugging e desenvolvimento

​Comandos de debugging

​Problemas comuns

​Referência de distribuição e versionamento

​Gerenciamento de versão

Referência de componentes de plugins

Comandos

Agentes

Hooks

Servidores MCP

Esquema de manifesto de plugin

Esquema completo

Campos obrigatórios

Campos de metadados

Campos de caminho de componente

Regras de comportamento de caminho

Variáveis de ambiente

Estrutura de diretório de plugin

Layout padrão de plugin

Referência de localizações de arquivo

Ferramentas de debugging e desenvolvimento

Comandos de debugging

Problemas comuns

Referência de distribuição e versionamento

Gerenciamento de versão