Um plugin do Claude Code não te dá poder nenhum. Ele te dá o resto do time.

A documentação da Anthropic coloca plugin e pasta .claude/ lado a lado numa tabela só, e a leitura honesta dela incomoda quem esperava um superpoder novo: plugin não libera nada que uma pasta solta de skills, agents e hooks já não faça. As duas colunas não são "fraco" e "forte". São "serve melhor pra". Pasta solta serve pro seu fluxo pessoal e pra experimentar rápido. Plugin serve pra dividir com o time, versionar entrega e reaproveitar entre projetos.

Ou seja: a decisão não é de capacidade. É de empacotamento — e ela cobra um preço que você paga com os próprios dedos, todo dia.

O preço é o nome dos seus comandos

Uma skill na sua pasta .claude/ é /hello. A mesmíssima skill dentro de um plugin chamado my-first-plugin vira /my-first-plugin:hello. As skills de plugin são sempre namespaced, de propósito, pra que dois plugins possam trazer um review cada um sem um atropelar o outro. Dá pra mudar o prefixo mudando o name do manifesto. Não dá pra desligar.

A troca inteira cabe nessa linha: você abre mão do nome curto que digita vinte vezes por dia pra que alguém que nunca te viu consiga instalar aquilo em segurança. Se ninguém mais vai instalar, você pagou pedágio numa estrada em que só você anda.

O que um plugin é, de fato, em disco

Menos do que parece. Uma pasta com um manifesto em .claude-plugin/plugin.json:

{
  "name": "my-plugin",
  "description": "O que aparece pra quem encontrar o plugin no gerenciador",
  "version": "1.0.0",
  "author": { "name": "Seu Nome" }
}

E os componentes, todos na raiz do plugin:

my-plugin/
├── .claude-plugin/
│   └── plugin.json       ← só este arquivo mora aqui
├── skills/<nome>/SKILL.md
├── agents/
├── hooks/hooks.json
├── .mcp.json             ← servidores MCP
├── .lsp.json             ← language servers
└── bin/                  ← executáveis que entram no PATH do Bash quando ativo

Converter o que você já tem é quase só cp. A única coisa que muda de lugar de verdade são os hooks: eles saem do settings.json e vão pro hooks/hooks.json — mesmo objeto, endereço novo. Pra testar sem instalar nada:

claude --plugin-dir ./my-plugin

A flag também aceita um .zip, e você pode repetir ela várias vezes. Se preferir nem usar flag, o claude plugin init my-tool cria um plugin dentro de ~/.claude/skills/ que carrega sozinho na próxima sessão, sem marketplace e sem instalação.

Preencha o version, ou todo commit vira release

O version é opcional no manifesto, e a documentação é direta sobre o que acontece se você deixar em branco: com distribuição por git, o SHA do commit entra no lugar, e cada commit conta como uma versão nova. Você corrige uma vírgula no README e o Claude Code de todo mundo enxerga uma atualização.

Preenchendo o campo, as pessoas só recebem update quando você sobe o número. Num plugin pessoal, tanto faz. Num plugin do qual dez pessoas dependem, esse campinho é a diferença entre entregar release e abrir uma mangueira de bombeiro.

O marketplace é um arquivo JSON

Essa é a parte que todo mundo acha que é infraestrutura. Não é. Um marketplace é um repositório git, um repositório no GitHub ou uma URL segurando um .claude-plugin/marketplace.json:

{
  "name": "company-tools",
  "owner": { "name": "DevTools Team", "email": "devtools@example.com" },
  "plugins": [
    {
      "name": "code-formatter",
      "source": "./plugins/formatter",
      "description": "Automatic code formatting on save",
      "version": "2.1.0"
    },
    {
      "name": "deployment-tools",
      "source": { "source": "github", "repo": "company/deploy-plugin" },
      "description": "Deployment automation tools"
    }
  ]
}

O source é ou um caminho relativo dentro do próprio repositório do marketplace, ou um ponteiro pra fora — github, npm, git-subdir, url. Caminho relativo resolve a partir da raiz do marketplace (a pasta que contém o .claude-plugin/), e num marketplace privado de time é essa a opção que você quer: as pastas dos plugins viajam dentro de um repositório ao qual o time já tem acesso, então ninguém precisa de uma segunda permissão.

Publicar e consumir, de ponta a ponta:

/plugin marketplace add ./my-marketplace         # teste local primeiro
/plugin marketplace add your-org/claude-plugins  # depois o de verdade
/plugin install code-formatter@company-tools

Antes de publicar, rode claude plugin validate ./your-plugin. É a mesma checagem que a esteira de revisão do marketplace da comunidade roda em toda submissão, e o --strict transforma aviso em erro. E lembra que nome de marketplace é global: claude-plugins-official, claude-community e mais uma dúzia de nomes da Anthropic são reservados e voltam rejeitados.

A parte que é decisão de EM, não de dev

É aqui que vale a sua tarde, se você lidera um time. Joga isto no .claude/settings.json do próprio repositório:

{
  "extraKnownMarketplaces": {
    "company-tools": {
      "source": { "source": "github", "repo": "your-org/claude-plugins" }
    }
  },
  "enabledPlugins": { "code-formatter@company-tools": true }
}

Pronto: o repositório passa a carregar a própria ferramenta. Quando alguém do time marca a pasta do projeto como confiável, o Claude Code oferece instalar o marketplace e os plugins que aquele projeto espera. Instalar em escopo de projeto grava nesse mesmo .claude/settings.json compartilhado; escopo de usuário é você em todo lugar, escopo local é você só naquele repositório.

A Anthropic abre o anúncio com exatamente esse caso — "Engineering leaders can maintain consistency across their team by using plugins to ensure specific hooks run for code reviews or testing workflows". É verdade, mas subestima o problema real. Na maioria dos times não falta ferramenta. O que sobra é pilha: cada pessoa mantém em silêncio três comandos que ninguém mais viu, e seis meses depois existem seis /review sutilmente diferentes, sendo que o bom mora num notebook que está prestes a sair de licença. Um marketplace não adiciona capacidade nenhuma a esse time. Ele torna a versão boa encontrável e as ruins obsoletas.

E poda também. A aba Installed do /plugin agrupa em "Not used recently" tudo que você não usa há duas semanas ao longo de pelo menos dez sessões, com uma linha Last used por plugin. Plugin instalado e esquecido continua custando tempo de inicialização e token de contexto em todo turno.

A regra: quando o plugin ganha da skill avulsa

Uma pergunta resolve — quem mais precisa disso, e como essa pessoa recebe a próxima versão?

• Só você, só neste repositório. Deixa em .claude/. Fica com o nome curto. É o caso da maioria das coisas.
• Seu time, em mais de um repositório. Plugin + um repositório de marketplace privado, plugado no .claude/settings.json pro repositório se instalar sozinho.
• Gente que você não conhece. Plugin + marketplace público, version explícito e claude plugin validate --strict antes de mandar o link pra alguém.

Faça isto hoje

Pega o único comando da sua pasta .claude/ que te daria raiva perder. Copia pra uma pasta de plugin, escreve um plugin.json de quatro linhas com um version de verdade e roda claude --plugin-dir ./essa-pasta. Dois minutos.

Agora digita o nome com o prefixo. Se soar normal, você achou a primeira coisa que vale publicar. Se te irritar toda vez, aquele comando sempre foi pessoal — e o lugar dele é exatamente onde ele já está.

Fontes

• Claude Code docs — Create plugins
• Claude Code docs — Create and distribute a plugin marketplace
• Claude Code docs — Discover and install prebuilt plugins
• Anthropic — Customize Claude Code with plugins