Referência de plugins - Claude Code Docs

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

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

Referência de componentes de plugin

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

Comandos

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

Agentes

Os plugins podem fornecer subagentes especializados para tarefas específicas que Claude pode invocar automaticamente quando apropriado. Localização: diretório agents/ na raiz do plugin Formato de 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 Claude deve invocá-lo.

## Capacidades
- Tarefa específica em que o agente se destaca
- Outra capacidade especializada
- Quando usar este agente versus 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 com base no contexto da tarefa
Agentes podem ser invocados manualmente pelos usuários
Agentes de plugin funcionam ao lado dos agentes Claude integrados

Skills

Os plugins podem fornecer Agent Skills que estendem as capacidades do Claude. Skills são invocadas pelo modelo—Claude decide autonomamente quando usá-las com base no contexto da tarefa. Localização: diretório skills/ na raiz do plugin Formato de arquivo: Diretórios contendo arquivos SKILL.md com frontmatter Estrutura de Skill:

skills/
├── pdf-processor/
│   ├── SKILL.md
│   ├── reference.md (opcional)
│   └── scripts/ (opcional)
└── code-reviewer/
    └── SKILL.md

Comportamento de integração:

Plugin Skills são descobertos automaticamente quando o plugin é instalado
Claude invoca Skills autonomamente com base na correspondência do contexto da tarefa
Skills podem incluir arquivos de suporte ao lado de SKILL.md

Para formato SKILL.md e orientação completa de autoria de Skill, consulte:

Hooks

Os plugins podem fornecer manipuladores de eventos que respondem automaticamente aos eventos do Claude Code. 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 de Claude usar qualquer ferramenta
PostToolUse: Depois de Claude usar qualquer ferramenta
UserPromptSubmit: Quando o usuário envia um prompt
Notification: Quando Claude Code envia notificações
Stop: Quando 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 de conversa ser compactado

Tipos de hook:

command: Executar comandos shell ou scripts
validation: Validar conteúdo 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 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 kit de ferramentas do Claude
Capacidades do servidor se integram perfeitamente com as 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": "Brief plugin description",
  "author": {
    "name": "Author Name",
    "email": "[email protected]",
    "url": "https://github.com/author"
  },
  "homepage": "https://docs.example.com/plugin",
  "repository": "https://github.com/author/plugin",
  "license": "MIT",
  "keywords": ["keyword1", "keyword2"],
  "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	`"Deployment automation tools"`
`author`	object	Informações do autor	`{"name": "Dev Team", "email": "[email protected]"}`
`homepage`	string	URL de documentação	`"https://docs.example.com"`
`repository`	string	URL do código-fonte	`"https://github.com/user/plugin"`
`license`	string	Identificador de 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 configuração de hook ou configuração inline	`"./hooks.json"`
`mcpServers`	string\|object	Caminho de configuração MCP ou configuração inline	`"./mcp.json"`

Regras de comportamento de caminho

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

Se commands/ existe, é 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 namespacing
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 seu diretório de plugin. Use isso em hooks, servidores MCP e scripts para garantir caminhos corretos independentemente do local de instalação.

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

Estrutura de diretório de plugin

Layout de plugin padrão

Um plugin completo segue esta estrutura:

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

O diretório .claude-plugin/ contém o arquivo plugin.json. Todos os outros diretórios (commands/, agents/, skills/, 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 invertida
Agentes	`agents/`	Arquivos markdown de subagente
Skills	`skills/`	Agent Skills com arquivos SKILL.md
Hooks	`hooks/hooks.json`	Configuração de hook
Servidores MCP	`.mcp.json`	Definições de servidor MCP

Ferramentas de depuração e desenvolvimento

Comandos de depuração

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 errada	Garantir `commands/` na raiz, não em `.claude-plugin/`
Hooks não disparando	Script não executável	Executar `chmod +x script.sh`
Falha de servidor MCP	`${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/plugins) - Tutoriais e uso prático
- [Marketplaces de plugins](/pt/plugin-marketplaces) - Criando e gerenciando marketplaces
- [Comandos de barra invertida](/pt/slash-commands) - Detalhes de desenvolvimento de comando
- [Subagentes](/pt/sub-agents) - Configuração e capacidades de agente
- [Agent Skills](/pt/skills) - Estender as capacidades do Claude
- [Hooks](/pt/hooks) - Manipulação de eventos e automação
- [MCP](/pt/mcp) - Integração de ferramenta externa
- [Configurações](/pt/settings) - Opções de configuração para plugins

Referência

​Referência de componentes de plugin

​Comandos

​Agentes

​Skills

​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 de plugin padrão

​Referência de localizações de arquivo

​Ferramentas de depuração e desenvolvimento

​Comandos de depuração

​Problemas comuns

​Referência de distribuição e versionamento

​Gerenciamento de versão

Referência de componentes de plugin

Comandos

Agentes

Skills

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 de plugin padrão

Referência de localizações de arquivo

Ferramentas de depuração e desenvolvimento

Comandos de depuração

Problemas comuns

Referência de distribuição e versionamento

Gerenciamento de versão