SpyBara
Go Premium

plugins.md 2026-05-02 18:14 UTC to 2026-05-04 22:58 UTC

454 added, 0 removed.

2026
Sun 31 06:39 Sat 30 06:23 Fri 29 06:38 Thu 28 06:37 Wed 27 06:42 Tue 26 06:33 Sun 24 06:25 Sat 23 06:18 Fri 22 06:33 Thu 21 06:36 Wed 20 06:35 Tue 19 06:34 Mon 18 23:59 Sun 17 01:01 Fri 15 22:58 Thu 14 17:02 Wed 13 23:01 Tue 12 22:57 Mon 11 23:00 Sun 10 23:03 Sat 9 04:57 Fri 8 22:00 Thu 7 22:59 Tue 5 23:00 Mon 4 22:58 Sat 2 18:14 Fri 1 18:19

Criar plugins

Crie plugins personalizados para estender Claude Code com skills, agents, hooks e MCP servers.

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)

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

Crie seu primeiro plugin

1

Crie o diretório do plugin

Cada plugin vive em seu próprio diretório contendo um manifesto e seus skills, agents ou hooks. Crie um agora:

mkdir my-first-plugin
2

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:

{
"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.

3

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:

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

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

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.

5

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:

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

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.

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

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

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:

{
  "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:

[
  {
    "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.

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

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. Plugins marketplace forçadamente habilitados por configurações gerenciadas são a única exceção e não podem ser substituídos.

Conforme você faz mudanças no seu plugin, execute /reload-plugins para pegar as atualizações sem reiniciar. Isso recarrega plugins, skills, agents, hooks, MCP servers do plugin e LSP servers do plugin. 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

Depure problemas de plugin

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

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

Compartilhe seus plugins

Quando seu plugin estiver pronto para compartilhar:

  1. Adicione documentação: Inclua um README.md com instruções de instalação e uso
  2. 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
  3. Crie ou use um marketplace: Distribua através de marketplaces de plugins para instalação
  4. 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 oficial

Para enviar um plugin para o marketplace oficial da Anthropic, use um dos formulários de envio no aplicativo:

Uma vez que seu plugin está listado, você pode ter seu próprio CLI solicitar aos usuários do Claude Code que o instalem. Veja Recomende seu plugin a partir de seu CLI.

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

1

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:

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

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/
3

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:

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

Teste seu plugin migrado

Carregue seu plugin para verificar se tudo funciona:

claude --plugin-dir ./my-plugin

Teste cada componente: execute seus skills, 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

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

Para desenvolvedores de plugins