Criar plugins - Claude Code Docs

Plugins permitem que você estenda Claude Code com funcionalidade personalizada que pode ser compartilhada entre projetos e equipes. Este guia cobre a criação de seus próprios plugins com skills, agents, hooks e MCP servers. Procurando instalar plugins existentes? Veja Descobrir e instalar plugins. Para especificações técnicas completas, veja Referência de plugins.

Quando usar plugins vs configuração independente

Claude Code suporta duas maneiras de adicionar skills, agents e hooks personalizados:

Abordagem	Nomes de skills	Melhor para
Independente (diretório `.claude/`)	`/hello`	Fluxos de trabalho pessoais, personalizações específicas do projeto, experimentos rápidos
Plugins (diretórios com `.claude-plugin/plugin.json`)	`/plugin-name:hello`	Compartilhamento com colegas de equipe, distribuição para a comunidade, lançamentos versionados, reutilizável em projetos

Use configuração independente quando:

Você está personalizando Claude Code para um único projeto
A configuração é pessoal e não precisa ser compartilhada
Você está experimentando com skills ou hooks antes de empacotá-los
Você quer nomes de skills curtos como /hello ou /deploy

Use plugins quando:

Você quer compartilhar funcionalidade com sua equipe ou comunidade
Você precisa dos mesmos skills/agents em múltiplos projetos
Você quer controle de versão e atualizações fáceis para suas extensões
Você está distribuindo através de um marketplace
Você está ok com skills com namespace como /my-plugin:hello (namespacing previne conflitos entre plugins)

Comece com configuração independente em .claude/ para iteração rápida, depois converta para um plugin quando estiver pronto para compartilhar.

Início rápido

Este início rápido o guia através da criação de um plugin com um skill personalizado. Você criará um manifesto (o arquivo de configuração que define seu plugin), adicionará um skill e o testará localmente usando a flag --plugin-dir.

Pré-requisitos

Claude Code instalado e autenticado

Se você não vir o comando /plugin, atualize Claude Code para a versão mais recente. Veja Troubleshooting para instruções de atualização.

Crie seu primeiro plugin

Crie o diretório do plugin

Cada plugin vive em seu próprio diretório contendo seus skills, agents ou hooks, opcionalmente ao lado de um manifesto .claude-plugin/plugin.json. Crie um agora:

mkdir my-first-plugin

Crie o manifesto do plugin

O arquivo de manifesto em .claude-plugin/plugin.json define a identidade do seu plugin: seu nome, descrição e versão. Claude Code usa esses metadados para exibir seu plugin no gerenciador de plugins.Crie o diretório .claude-plugin dentro da pasta do seu plugin:

mkdir my-first-plugin/.claude-plugin

Depois crie my-first-plugin/.claude-plugin/plugin.json com este conteúdo:

my-first-plugin/.claude-plugin/plugin.json

{
  "name": "my-first-plugin",
  "description": "A greeting plugin to learn the basics",
  "version": "1.0.0",
  "author": {
    "name": "Your Name"
  }
}

Campo	Propósito
`name`	Identificador único e namespace de skill. Skills são prefixados com isso (ex: `/my-first-plugin:hello`).
`description`	Mostrado no gerenciador de plugins ao navegar ou instalar plugins.
`version`	Opcional. Se definido, os usuários recebem atualizações apenas quando você incrementa este campo. Se omitido e seu plugin é distribuído via git, o SHA do commit é usado e cada commit conta como uma nova versão. Veja gerenciamento de versão.
`author`	Opcional. Útil para atribuição.

Para campos adicionais como homepage, repository e license, veja o esquema de manifesto completo.

Adicione um skill

Skills vivem no diretório skills/. Cada skill é uma pasta contendo um arquivo SKILL.md. O nome da pasta se torna o nome do skill, prefixado com o namespace do plugin (hello/ em um plugin nomeado my-first-plugin cria /my-first-plugin:hello).Crie um diretório de skill na pasta do seu plugin:

mkdir -p my-first-plugin/skills/hello

Depois crie my-first-plugin/skills/hello/SKILL.md com este conteúdo:

my-first-plugin/skills/hello/SKILL.md

---
description: Greet the user with a friendly message
disable-model-invocation: true
---

Greet the user warmly and ask how you can help them today.

Teste seu plugin

Execute Claude Code com a flag --plugin-dir para carregar seu plugin:

claude --plugin-dir ./my-first-plugin

Uma vez que Claude Code inicia, tente seu novo skill:

/my-first-plugin:hello

Você verá Claude responder com uma saudação. Execute /help para ver seu skill listado sob o namespace do plugin.

Por que namespacing? Plugin skills são sempre com namespace (como /my-first-plugin:hello) para prevenir conflitos quando múltiplos plugins têm skills com o mesmo nome.Para mudar o prefixo de namespace, atualize o campo name em plugin.json.

Adicione argumentos de skill

Torne seu skill dinâmico aceitando entrada do usuário. O placeholder $ARGUMENTS captura qualquer texto que o usuário fornece após o nome do skill.Atualize seu arquivo SKILL.md:

my-first-plugin/skills/hello/SKILL.md

---
description: Greet the user with a personalized message
---

# Hello Skill

Greet the user named "$ARGUMENTS" warmly and ask how you can help them today. Make the greeting personal and encouraging.

Execute /reload-plugins para pegar as mudanças, depois tente o skill com seu nome:

/my-first-plugin:hello Alex

Claude o saudará pelo nome. Para mais sobre passar argumentos para skills, veja Skills.

Você criou e testou com sucesso um plugin com estes componentes-chave:

Manifesto do plugin (.claude-plugin/plugin.json): descreve os metadados do seu plugin
Diretório de skills (skills/): contém seus skills personalizados
Argumentos de skill ($ARGUMENTS): captura entrada do usuário para comportamento dinâmico

A flag --plugin-dir é útil para desenvolvimento e testes. Quando estiver pronto para compartilhar seu plugin com outros, veja Criar e distribuir um marketplace de plugins.

Desenvolva um plugin em seu diretório de skills

Em vez de passar --plugin-dir em cada inicialização, você pode manter um plugin em seu diretório de skills e fazer com que Claude Code o carregue automaticamente. claude plugin init cria um:

claude plugin init my-tool

Isso cria ~/.claude/skills/my-tool/ com um manifesto .claude-plugin/plugin.json e um SKILL.md inicial. Na próxima sessão ele carrega como my-tool@skills-dir sem nenhuma etapa de marketplace ou instalação. Para as regras de carregamento automático, escopo pessoal vs. projeto, o requisito de confiança do workspace e como atualizar ou remover um, veja Plugins do diretório de skills.

Visão geral da estrutura do plugin

Você criou um plugin com um skill, mas plugins podem incluir muito mais: agents personalizados, hooks, MCP servers, LSP servers e monitores de background.

Erro comum: Não coloque commands/, agents/, skills/ ou hooks/ dentro do diretório .claude-plugin/. Apenas plugin.json vai dentro de .claude-plugin/. Todos os outros diretórios devem estar no nível raiz do plugin.

Diretório	Localização	Propósito
`.claude-plugin/`	Raiz do plugin	Contém manifesto `plugin.json` (opcional se componentes usam localizações padrão)
`skills/`	Raiz do plugin	Skills como diretórios `<name>/SKILL.md`
`commands/`	Raiz do plugin	Skills como arquivos Markdown simples. Use `skills/` para novos plugins
`agents/`	Raiz do plugin	Definições de agent personalizadas
`hooks/`	Raiz do plugin	Manipuladores de eventos em `hooks.json`
`.mcp.json`	Raiz do plugin	Configurações de MCP server
`.lsp.json`	Raiz do plugin	Configurações de LSP server para inteligência de código
`monitors/`	Raiz do plugin	Configurações de monitor de background em `monitors.json`
`bin/`	Raiz do plugin	Executáveis adicionados ao `PATH` da ferramenta Bash enquanto o plugin está habilitado
`settings.json`	Raiz do plugin	Configurações padrão aplicadas quando o plugin é habilitado

Um plugin que fornece exatamente um skill pode colocar SKILL.md diretamente na raiz do plugin em vez de criar um diretório skills/. Claude Code o carrega como um único skill e usa o campo name do frontmatter para o nome de invocação. Use o layout skills/ para plugins que podem crescer para mais de um skill.

Próximos passos: Pronto para adicionar mais recursos? Vá para Desenvolver plugins mais complexos para adicionar agents, hooks, MCP servers e LSP servers. Para especificações técnicas completas de todos os componentes do plugin, veja Referência de plugins.

Desenvolver plugins mais complexos

Uma vez que você está confortável com plugins básicos, você pode criar extensões mais sofisticadas.

Adicione Skills ao seu plugin

Plugins podem incluir Agent Skills para estender as capacidades do Claude. Skills são invocados por modelo: Claude os usa automaticamente com base no contexto da tarefa. Adicione um diretório skills/ na raiz do seu plugin com pastas de Skill contendo arquivos SKILL.md:

my-plugin/
├── .claude-plugin/
│   └── plugin.json
└── skills/
    └── code-review/
        └── SKILL.md

Cada SKILL.md contém frontmatter YAML e instruções. Inclua uma description para que Claude saiba quando usar o skill:

---
description: Reviews code for best practices and potential issues. Use when reviewing code, checking PRs, or analyzing code quality.
---

When reviewing code, check for:
1. Code organization and structure
2. Error handling
3. Security concerns
4. Test coverage

Após instalar o plugin, execute /reload-plugins para carregar os Skills. Para orientação completa de autoria de Skill incluindo divulgação progressiva e restrições de ferramentas, veja Agent Skills.

Adicione LSP servers ao seu plugin

Para linguagens comuns como TypeScript, Python e Rust, instale os plugins LSP pré-construídos do marketplace oficial. Crie plugins LSP personalizados apenas quando você precisar de suporte para linguagens não cobertas.

Plugins LSP (Language Server Protocol) dão ao Claude inteligência de código em tempo real. Se você precisar suportar uma linguagem que não tem um plugin LSP oficial, você pode criar um próprio adicionando um arquivo .lsp.json ao seu plugin:

.lsp.json

{
  "go": {
    "command": "gopls",
    "args": ["serve"],
    "extensionToLanguage": {
      ".go": "go"
    }
  }
}

Usuários instalando seu plugin devem ter o binário do language server instalado em sua máquina. Para opções de configuração LSP completas, veja LSP servers.

Adicione monitores de background ao seu plugin

Monitores de background permitem que seu plugin observe logs, arquivos ou status externo em background e notifique Claude conforme eventos chegam. Claude Code inicia cada monitor automaticamente quando o plugin está ativo, então você não precisa instruir Claude a iniciar a observação. Adicione um arquivo monitors/monitors.json na raiz do plugin com um array de entradas de monitor:

monitors/monitors.json

[
  {
    "name": "error-log",
    "command": "tail -F ./logs/error.log",
    "description": "Application error log"
  }
]

Cada linha de stdout do command é entregue ao Claude como uma notificação durante a sessão. Para o esquema completo, incluindo o trigger when e substituição de variáveis, veja Monitors.

Envie configurações padrão com seu plugin

Plugins podem incluir um arquivo settings.json na raiz do plugin para aplicar configuração padrão quando o plugin é habilitado. Atualmente, apenas as chaves agent e subagentStatusLine são suportadas. Definir agent ativa um dos agents personalizados do plugin como a thread principal, aplicando seu prompt de sistema, restrições de ferramentas e modelo. Isso permite que um plugin mude como Claude Code se comporta por padrão quando habilitado.

settings.json

{
  "agent": "security-reviewer"
}

Este exemplo ativa o agent security-reviewer definido no diretório agents/ do plugin. Configurações de settings.json têm prioridade sobre settings declarados em plugin.json. Chaves desconhecidas são silenciosamente ignoradas.

Organize plugins complexos

Para plugins com muitos componentes, organize sua estrutura de diretório por funcionalidade. Para layouts de diretório completos e padrões de organização, veja Estrutura de diretório do plugin.

Teste seus plugins localmente

Use a flag --plugin-dir para testar plugins durante o desenvolvimento. Isso carrega seu plugin diretamente sem exigir instalação.

claude --plugin-dir ./my-plugin

A flag também aceita um arquivo .zip do diretório do plugin, que requer Claude Code v2.1.128 ou posterior.

claude --plugin-dir ./my-plugin.zip

Quando um plugin --plugin-dir tem o mesmo nome que um plugin marketplace instalado, a cópia local tem precedência para essa sessão. Isso permite que você teste mudanças em um plugin que você já tem instalado sem desinstalá-lo primeiro. A exceção é plugins que configurações gerenciadas forçadamente habilitam ou desabilitam: --plugin-dir não pode substituir aqueles. Conforme você faz mudanças no seu plugin, execute /reload-plugins para pegar as atualizações sem reiniciar. Isso recarrega plugins, skills, agents, hooks, plugin MCP servers e plugin LSP servers. Teste seus componentes de plugin:

Tente seus skills com /plugin-name:skill-name
Verifique que agents aparecem em /agents
Verifique que hooks funcionam como esperado

Você pode carregar múltiplos plugins de uma vez especificando a flag múltiplas vezes:

claude --plugin-dir ./plugin-one --plugin-dir ./plugin-two

Para testar um plugin que já está empacotado como um arquivo .zip e hospedado em uma URL, como um artefato de compilação de CI, use --plugin-url em vez disso. Claude Code busca o arquivo no início e o carrega apenas para essa sessão. Se a busca falhar ou o arquivo for inválido, Claude Code relata um erro de carregamento de plugin e inicia sem ele. As mesmas considerações de confiança se aplicam como para qualquer fonte de plugin: apenas aponte esse flag para arquivos que você controla ou confia. Para carregar múltiplos plugins, repita a flag para cada URL:

claude --plugin-url https://example.com/my-plugin.zip --plugin-url https://example.com/other.zip

Ou passe URLs separadas por espaço como um argumento entre aspas:

claude --plugin-url "https://example.com/my-plugin.zip https://example.com/other.zip"

Depure problemas de plugin

Se seu plugin não está funcionando como esperado:

Verifique a estrutura: Certifique-se de que seus diretórios estão na raiz do plugin, não dentro de .claude-plugin/
Teste componentes individualmente: Verifique cada skill, agent e hook separadamente
Use ferramentas de validação e depuração: Veja Ferramentas de depuração e desenvolvimento para comandos CLI e técnicas de troubleshooting

Quando seu plugin estiver pronto para compartilhar:

Adicione documentação: Inclua um README.md com instruções de instalação e uso
Escolha uma estratégia de versionamento: Decida se deve definir uma version explícita ou confiar no SHA do commit git. Veja gerenciamento de versão
Crie ou use um marketplace: Distribua através de marketplaces de plugins para instalação
Teste com outros: Tenha membros da equipe testarem o plugin antes de distribuição mais ampla

Uma vez que seu plugin está em um marketplace, outros podem instalá-lo usando as instruções em Descobrir e instalar plugins. Para manter um plugin interno à sua equipe, hospede o marketplace em um repositório privado.

Envie seu plugin para o marketplace da comunidade

A Anthropic mantém dois marketplaces públicos para plugins do Claude Code:

claude-plugins-official: um conjunto curado de plugins mantidos pela Anthropic. Registrado automaticamente na primeira vez que você inicia Claude Code interativamente. Um script não-interativo que é executado antes desse primeiro lançamento deve adicioná-lo explicitamente com claude plugin marketplace add anthropics/claude-plugins-official.
claude-community: o marketplace público da comunidade onde envios de terceiros chegam após revisão. Os usuários o adicionam com /plugin marketplace add anthropics/claude-plugins-community e instalam a partir dele como @claude-community.

Para enviar seu plugin para revisão do marketplace da comunidade, use um dos formulários no aplicativo:

claude.ai: claude.ai/admin-settings/directory/submissions/plugins/new
Console: platform.claude.com/plugins/submit

O formulário claude.ai requer uma organização Team ou Enterprise e acesso ao gerenciamento de diretório; proprietários de organização têm esse acesso por padrão. Autores individuais que não fazem parte de uma organização Team ou Enterprise podem usar o formulário Console em vez disso. Execute claude plugin validate localmente antes de enviar. O pipeline de revisão executa a mesma verificação em cada envio, junto com triagem de segurança automatizada. Plugins aprovados são fixados a um SHA de commit específico no catálogo anthropics/claude-plugins-community, e CI aumenta o pino automaticamente conforme você envia novos commits para seu repositório. O catálogo público sincroniza todas as noites a partir do pipeline de revisão, então pode haver um atraso entre aprovação e seu plugin aparecer em marketplace.json. Para verificar se seu plugin já é instalável, procure por seu nome no catálogo da comunidade. O marketplace oficial, claude-plugins-official, é curado separadamente. A Anthropic decide quais plugins incluir a seu critério. Não há processo de aplicação, e o formulário de envio não adiciona plugins ao marketplace oficial. Se a Anthropic listar seu plugin no marketplace oficial, seu CLI pode solicitar aos usuários do Claude Code que o instalem. Veja Recomende seu plugin a partir de seu CLI.

Para especificações técnicas completas, técnicas de depuração e estratégias de distribuição, veja Referência de plugins.

Converta configurações existentes para plugins

Se você já tem skills ou hooks em seu diretório .claude/, você pode convertê-los em um plugin para compartilhamento e distribuição mais fáceis.

Passos de migração

Crie a estrutura do plugin

Crie um novo diretório de plugin:

mkdir -p my-plugin/.claude-plugin

Crie o arquivo de manifesto em my-plugin/.claude-plugin/plugin.json:

my-plugin/.claude-plugin/plugin.json

{
  "name": "my-plugin",
  "description": "Migrated from standalone configuration",
  "version": "1.0.0"
}

Copie seus arquivos existentes

Copie suas configurações existentes para o diretório do plugin:

# Copy commands
cp -r .claude/commands my-plugin/

# Copy agents (if any)
cp -r .claude/agents my-plugin/

# Copy skills (if any)
cp -r .claude/skills my-plugin/

Migre hooks

Se você tem hooks em suas configurações, crie um diretório de hooks:

mkdir my-plugin/hooks

Crie my-plugin/hooks/hooks.json com sua configuração de hooks. Copie o objeto hooks de seu .claude/settings.json ou settings.local.json, já que o formato é o mesmo. O comando recebe entrada de hook como JSON em stdin, então use jq para extrair o caminho do arquivo:

my-plugin/hooks/hooks.json

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [{ "type": "command", "command": "jq -r '.tool_input.file_path' | xargs npm run lint:fix" }]
      }
    ]
  }
}

Teste seu plugin migrado

Carregue seu plugin para verificar se tudo funciona:

claude --plugin-dir ./my-plugin

Teste cada componente: execute seus comandos, verifique que agents aparecem em /agents e verifique que hooks disparam corretamente.

O que muda ao migrar

Independente (`.claude/`)	Plugin
Disponível apenas em um projeto	Pode ser compartilhado via marketplaces
Arquivos em `.claude/commands/`	Arquivos em `plugin-name/commands/`
Hooks em `settings.json`	Hooks em `hooks/hooks.json`
Deve copiar manualmente para compartilhar	Instale com `/plugin install`

Após migrar, remova os arquivos originais de .claude/ para evitar duplicatas. As definições de agents em .claude/agents/ do projeto e do usuário substituem agents com o mesmo nome do plugin, portanto a versão do plugin só entra em vigor uma vez que os originais são removidos.

Próximos passos

Agora que você entende o sistema de plugins do Claude Code, aqui estão caminhos sugeridos para diferentes objetivos:

Para usuários de plugins

Descobrir e instalar plugins: navegue em marketplaces e instale plugins
Configurar marketplaces de equipe: configure plugins no nível do repositório para sua equipe

Para desenvolvedores de plugins

Criar e distribuir um marketplace: empacote e compartilhe seus plugins
Referência de plugins: especificações técnicas completas
Mergulhe mais fundo em componentes específicos do plugin:
- Skills: detalhes de desenvolvimento de skill
- Subagents: configuração e capacidades de agent
- Hooks: manipulação de eventos e automação
- MCP: integração de ferramentas externas

​Quando usar plugins vs configuração independente

​Início rápido

​Pré-requisitos

​Crie seu primeiro plugin

​Desenvolva um plugin em seu diretório de skills

​Visão geral da estrutura do plugin

​Desenvolver plugins mais complexos

​Adicione Skills ao seu plugin

​Adicione LSP servers ao seu plugin

​Adicione monitores de background ao seu plugin

​Envie configurações padrão com seu plugin

​Organize plugins complexos

​Teste seus plugins localmente

​Depure problemas de plugin

​Compartilhe seus plugins

​Envie seu plugin para o marketplace da comunidade

​Converta configurações existentes para plugins

​Passos de migração

​O que muda ao migrar

​Próximos passos

​Para usuários de plugins

​Para desenvolvedores de plugins

Quando usar plugins vs configuração independente

Início rápido

Pré-requisitos

Crie seu primeiro plugin

Desenvolva um plugin em seu diretório de skills

Visão geral da estrutura do plugin

Desenvolver plugins mais complexos

Adicione Skills ao seu plugin

Adicione LSP servers ao seu plugin

Adicione monitores de background ao seu plugin

Envie configurações padrão com seu plugin

Organize plugins complexos

Teste seus plugins localmente

Depure problemas de plugin

Compartilhe seus plugins

Envie seu plugin para o marketplace da comunidade

Converta configurações existentes para plugins

Passos de migração

O que muda ao migrar

Próximos passos

Para usuários de plugins

Para desenvolvedores de plugins