Como criar um marketplace de plugins do Claude Code: da skill ao catálogo publicado

Se você usa Claude Code todo dia, já viu ele agir sozinho: resolver uma etapa do trabalho sem você digitar nenhum comando, porque encontrou uma instrução salva em algum lugar que batia com o pedido. Mas provavelmente nunca parou para estruturar essa instrução de um jeito que sobrevive fora daquele projeto, versiona e se instala com um comando só. Foi estruturando o claude-vue-marketplace, meu catálogo de plugins para Vue, Nuxt e Quasar, que aprendi cada peça deste mecanismo na prática.

Neste artigo vamos abrir esse mecanismo por dentro: o que é um marketplace, por que criar um, e como skill e plugin se encaixam nele. Depois, montamos um mini-marketplace juntos, arquivo por arquivo, até deixá-lo pronto para testar e publicar.

O que é um marketplace, e por que criar um

Um marketplace de plugins do Claude Code é um catálogo: um arquivo que lista onde cada plugin está, para o Claude Code saber de onde buscar cada um no momento em que você roda o comando de instalação. Por trás desse catálogo existem duas peças menores:

1. Skill: o arquivo que o Claude carrega sozinho

Uma skill é uma instrução escrita em linguagem natural, guardada num arquivo SKILL.md. O Claude Code lê uma descrição curta dentro desse arquivo e decide sozinho quando aplicar a instrução, sem esperar um comando explícito.

2. Plugin: a mesma skill, empacotada

Um plugin é uma pasta com formato fixo, contendo uma ou mais skills e, quando precisar, também agentes, hooks e servidores MCP. Essa estrutura permite que sejam organizadas regras de execução como acionar uma regra interna, chamar um agente e até mesmo dividir o trabalho realizado em etapas (como rodar uma skill de pesquisa, outra de escrita e outra de revisão ). É o pacote que dá versão e nome de instalação a um conjunto de skills.

O Marketplace é um catálogo centralizado que aponta pra varios plugins

Por que montar um marketplace

A primeira razão é parar de repetir configuração entre repositórios. Toda convenção que hoje vive solta em .claude/commands ou .claude/skills de um projeto fica presa àquele projeto. Outro repositório da mesma pessoa, ou um colega no mesmo time, só herda essas regras copiando arquivo por arquivo. Empacotado como plugin e distribuído por marketplace, o mesmo conjunto de regras passa a se instalar com um comando e a atualizar com outro, sem fazer a cópia manual a cada projeto novo.

A segunda razão é versionamento. Cada entrada de plugin pode fixar uma versão; quando ela muda, quem instalou recebe a atualização na próxima sincronização, e quem não quer a mudança ainda pode ficar na versão anterior. Esse controle não existe para arquivos soltos dentro de .claude/, que só têm o histórico do git do próprio projeto.

O que é uma skill, por dentro

Uma skill de verdade se parece com isto:

---
description: Revisa o diff atual em busca de bugs óbvios, tratamento de erro ausente e nomes que não dizem o que fazem. Use antes de abrir um commit ou um PR.
---

Leia o diff das mudanças ainda não commitadas e aponte, por arquivo e linha:
1. Erros de lógica ou casos de borda esquecidos
2. Tratamento de erro ausente ou silencioso
3. Nomes de variável ou função que exigem ler o corpo para entender
4. Qualquer coisa que pareça código morto ou comentado

Seja direto: liste o achado, o arquivo, a linha e a correção sugerida.

O bloco entre ---, chamado frontmatter e escrito no formato YAML, é a parte de acionamento automatico. O description ali dentro descreve quando essa instrução se aplica, e é esse texto que o Claude Code lê para decidir sozinho quando carregar a skill, sem esperar você digitar nenhum comando. Quanto mais específico esse texto, menor a chance de a skill disparar fora de contexto ou de nunca disparar. Um frontmatter com disable-model-invocation: true desliga esse gatilho automático e deixa a skill só acessível por comando explícito, opção útil para instruções que você prefere chamar por vontade própria em vez de deixar o Claude decidir o momento. O resto do arquivo, abaixo do frontmatter, é a instrução em si, em texto simples: é isso que o Claude segue quando a skill carrega.

Onde esse arquivo mora muda o alcance dele:

# solto no projeto (configuração standalone tradicional)
meu-projeto/
└── .claude/
    └── skills/
        └── revisar-pr/
            └── SKILL.md      # chamada como /revisar-pr

# empacotado num plugin
meu-marketplace/
└── plugins/
    └── revisor/
        └── skills/
            └── revisar-pr/
                └── SKILL.md  # chamada como /revisor:revisar-pr

Solto em .claude/, o arquivo só existe naquele projeto: a documentação chama isso de configuração standalone, boa para experimento rápido ou ajuste pessoal. Empacotado dentro de um plugin, o mesmo arquivo ganha versão, instalação e atualização, e o pacote inteiro fica pronto para instalar em outro projeto ou repassar a um colega. Repare que o conteúdo do SKILL.md, o mesmo mostrado acima, é idêntico nos dois casos: o que muda é só a arquitetura em volta dele.

A anatomia do marketplace.json

Todo marketplace tem um único arquivo obrigatório: .claude-plugin/marketplace.json, na raiz do repositório. É um arquivo JSON comum, lido pelo Claude Code para saber três coisas: o nome do catálogo, quem mantém ele, e a lista de plugins disponíveis.

{
  "name": "meu-marketplace",
  "owner": {
    "name": "Seu Nome"
  },
  "description": "Plugins que uso nos meus projetos",
  "plugins": [
    {
      "name": "revisor",
      "source": "./plugins/revisor",
      "description": "Skill de revisão de diff antes do commit"
    }
  ]
}

• name: identificador público do catálogo, sempre em letras minúsculas separadas por hífen. É esse texto que aparece depois do arroba na instalação, como em /plugin install revisor@meu-marketplace.
• owner: objeto simples, só precisa do campo name dizendo quem mantém aquilo.
• plugins: a lista de entradas do catálogo. Cada entrada, no mínimo, também tem um name e um source dizendo onde o Claude Code vai buscar aquele plugin.

Esse source é o campo que muda mais entre um marketplace e outro, porque aceita sete formatos diferentes. O exemplo acima já usa o mais simples, um caminho relativo ("./plugins/revisor", sempre começando com ./), que serve quando o plugin mora dentro do próprio repositório do catálogo; a referência é sempre a pasta que contém .claude-plugin/, e o conteúdo dessa pasta em si nunca entra na conta. Quando o plugin mora em outro lugar, o source vira um objeto:

{ "source": { "source": "github", "repo": "sua-conta/revisor-plugin" } }

{ "source": { "source": "url", "url": "https://gitlab.com/sua-conta/revisor-plugin.git" } }

{ "source": { "source": "git-subdir", "url": "https://github.com/sua-conta/monorepo.git", "path": "tools/revisor" } }

{ "source": { "source": "npm", "package": "@sua-conta/revisor-plugin" } }

{ "source": { "source": "archive", "url": "https://artefatos.example.com/revisor-1.0.0.zip" } }

{ "source": { "source": "command", "command": "meu-cli caminho-do-plugin" } }

• github: busca de outro repositório GitHub e aceita ref e sha opcionais, para fixar uma branch, tag ou commit específico.
• url: faz o mesmo para qualquer repositório git acessível por HTTPS ou SSH, com os mesmos dois campos opcionais.
• git-subdir: aponta para uma subpasta dentro de um repositório git maior, com path como campo obrigatório além de url. Existe para quando vários plugins vivem dentro de um monorepo só.
• npm: instala o plugin como um pacote do registro npm, com version e registry opcionais.
• archive: baixa um .zip hospedado em qualquer servidor HTTPS, com sha256 opcional para conferir se o arquivo baixado é exatamente o esperado.
• command: gera o diretório do plugin rodando um comando local que precisa imprimir o caminho do resultado. Pensado para ferramentas que exportam configuração dinamicamente.

Um detalhe evita um erro só descoberto depois de publicado: marketplace adicionado por uma URL que aponta direto para o arquivo marketplace.json, sem repositório git por trás, baixa só aquele arquivo. Uma entrada com caminho relativo falha nesse formato de instalação, porque os arquivos do plugin em si nunca chegam a ser baixados; cada source precisa ser github, url, git-subdir ou outro tipo remoto.

Existe também uma lista curta de nomes bloqueados: claude-code-marketplace, claude-plugins-official, claude-community, anthropic-plugins, entre alguns outros, ficam reservados ao uso oficial da Anthropic, junto com qualquer variação que imite esses nomes. A checagem roda toda vez que o marketplace carrega, então escolher um nome parecido com um nome oficial é o tipo de erro que só aparece depois de publicado.

A anatomia de um plugin

Cada entrada de plugins no marketplace.json aponta para uma pasta com este formato:

revisor/
├── .claude-plugin/
│   └── plugin.json
├── skills/
│   └── revisar-pr/
│       └── SKILL.md
├── agents/
├── hooks/
│   └── hooks.json
└── .mcp.json

.claude-plugin/plugin.json é o manifesto do plugin: um arquivo JSON pequeno, que descreve a identidade dele, e o único arquivo que fica dentro dessa pasta com ponto na frente. Todo o resto do plugin mora solto na raiz, ao lado de .claude-plugin/, e essa vizinhança é a regra que mais se erra: colocar skills/, agents/ ou hooks/ dentro de .claude-plugin/ é o erro de estrutura mais comum de quem monta o primeiro plugin.

{
  "name": "revisor",
  "description": "Skill de revisão de diff antes do commit",
  "version": "1.0.0",
  "author": {
    "name": "Seu Nome"
  }
}

• name: o identificador do plugin, que também vira o prefixo de cada skill dele.
• description: o texto que aparece no gerenciador de plugins.
• version: opcional, mas necessário se você quiser controlar quando cada pessoa recebe atualização.
• author: opcional, identifica quem mantém o plugin.

skills/ é onde mora o comportamento que o Claude carrega sozinho, o mesmo mecanismo do SKILL.md mostrado no começo deste artigo. Cada subpasta dentro de skills/ vira uma skill, nomeada como o nome da pasta e prefixada pelo name do plugin: a pasta revisar-pr dentro do plugin revisor fica disponível como /revisor:revisar-pr, exatamente o comando que apareceu na árvore de pastas mais acima. O prefixo existe para dois plugins diferentes poderem ter uma skill chamada do mesmo jeito sem conflito.

As demais pastas completam o plugin conforme a necessidade de cada um, e nenhuma delas é obrigatória:

• commands/: formato anterior de skill, um arquivo .md solto sem subpasta própria. O Claude Code ainda o lê, mas a documentação recomenda skills/ para todo plugin novo.
• agents/: guarda definições de agente customizado, cada arquivo virando um agente disponível dentro do plugin.
• hooks/hooks.json: liga eventos do Claude Code, como a gravação de um arquivo, a comandos de shell que rodam sozinhos quando aquele evento acontece.
• .mcp.json: na raiz do plugin, declara servidores MCP que o plugin já traz configurados, poupando cada pessoa que instala de montar a integração à mão.

Montando o mini-marketplace

Com a anatomia registrada, o resto é criar cada peça na ordem certa.

1. Criar as pastas

mkdir -p meu-marketplace/.claude-plugin
mkdir -p meu-marketplace/plugins/revisor/.claude-plugin
mkdir -p meu-marketplace/plugins/revisor/skills/revisar-pr

2. Criar a skill

Dentro de meu-marketplace/plugins/revisor/skills/revisar-pr/, crie SKILL.md com o mesmo conteúdo mostrado no início deste artigo:

---
description: Revisa o diff atual em busca de bugs óbvios, tratamento de erro ausente e nomes que não dizem o que fazem. Use antes de abrir um commit ou um PR.
---

Leia o diff das mudanças ainda não commitadas e aponte, por arquivo e linha:
1. Erros de lógica ou casos de borda esquecidos
2. Tratamento de erro ausente ou silencioso
3. Nomes de variável ou função que exigem ler o corpo para entender
4. Qualquer coisa que pareça código morto ou comentado

Seja direto: liste o achado, o arquivo, a linha e a correção sugerida.

3. Criar o manifesto do plugin

Dentro de meu-marketplace/plugins/revisor/.claude-plugin/, crie plugin.json:

{
  "name": "revisor",
  "description": "Skill de revisão de diff antes do commit",
  "version": "1.0.0",
  "author": {
    "name": "Seu Nome"
  }
}

4. Criar o catálogo

Na raiz do repositório, crie meu-marketplace/.claude-plugin/marketplace.json, apontando source para ./plugins/revisor:

{
  "name": "meu-marketplace",
  "owner": {
    "name": "Seu Nome"
  },
  "description": "Plugins que uso nos meus projetos",
  "plugins": [
    {
      "name": "revisor",
      "source": "./plugins/revisor",
      "description": "Skill de revisão de diff antes do commit"
    }
  ]
}

5. Conferir a estrutura final

Com os quatro arquivos no lugar, o mini-marketplace fica assim:

meu-marketplace/
├── .claude-plugin/
│   └── marketplace.json
└── plugins/
    └── revisor/
        ├── .claude-plugin/
        │   └── plugin.json
        └── skills/
            └── revisar-pr/
                └── SKILL.md

Esse é o marketplace inteiro: um marketplace.json, um plugin.json, um SKILL.md, e as pastas que os organizam. Cada plugin novo que você quiser somar repete apenas os passos dois a quatro dentro de plugins/, mais uma linha nova no array plugins do catálogo.

Testando localmente

Antes de publicar qualquer coisa, teste o plugin isolado com claude --plugin-dir ./meu-marketplace/plugins/revisor. Essa flag carrega o plugin direto da pasta, sem precisar de marketplace nenhum ainda, e também aceita um .zip do plugin quando o teste precisar simular a distribuição por arquivo. Dentro da sessão que abrir, rode a skill como /revisor:revisar-pr e confirme que ela responde do jeito que o SKILL.md descreve.

Depois de confirmar o plugin isolado, teste o caminho completo, o mesmo que qualquer outra pessoa vai seguir para instalar o seu: registre o catálogo local e instale o plugin a partir dele.

/plugin marketplace add ./meu-marketplace
/plugin install revisor@meu-marketplace

Se o resumo da instalação disser para rodar /reload-plugins, rode: esse comando recarrega plugins, skills, agentes, hooks e servidores MCP sem reiniciar a sessão inteira, e é o mesmo comando que você vai usar toda vez que editar um SKILL.md de um plugin já instalado.

Publicando e instalando

Publicar é subir o repositório para um host git, GitHub incluído, porque é o caminho mais direto: quem quiser o seu marketplace roda /plugin marketplace add sua-conta/meu-marketplace, e o Claude Code resolve o resto sozinho. Antes de subir, rode claude plugin validate . na raiz do marketplace: esse comando confere a sintaxe do marketplace.json, nomes de plugin duplicados e caminhos que tentem escapar da raiz do catálogo. Rodado dentro da pasta de um plugin específico, o mesmo comando valida o plugin.json daquele plugin e o frontmatter de cada skill, agente, comando e hook.

Um dos erros mais comuns que essa validação pega é Duplicate plugin name (dois plugins com o mesmo name dentro do mesmo marketplace.json), e o conserto é sempre o mesmo: renomear um deles para um identificador único.

Antes de instalar um marketplace que não é seu

Fica um aviso, e ele vem direto da anatomia que abrimos aqui. Um plugin não é só texto: junto das skills, ele pode trazer hooks, que rodam comandos de shell na sua máquina quando um evento acontece, e um .mcp.json, que conecta servidores externos à sua sessão. Some a isso o fato de a skill entrar sozinha no contexto, sem você pedir, e fica claro que instalar um marketplace desconhecido é dar a alguém um canal aberto para influenciar o que o Claude faz no seu projeto, com suas credenciais e seus arquivos.

Não existem só pessoas bem intencionadas publicando catálogo, e um repositório com README caprichado não prova nada sobre o que está nas pastas. A única procedência que já vem com alguma garantia é a oficial, os plugins e marketplaces mantidos pela própria Anthropic, e essa garantia é sobre a origem: o que aquele plugin faz na sua máquina você ainda precisa conferir. Fora dessa lista, a confiança é caso a caso, e você é quem decide. Antes de rodar /plugin marketplace add em algo de terceiros, abra o repositório e leia: o que tem em hooks/, o que o .mcp.json conecta, e o que as skills mandam o Claude fazer. Se não der para revisar, prefira não instalar. O mesmo cuidado se aplica a uma atualização: um plugin que você revisou uma vez pode mudar na versão seguinte, então fixar ref ou sha no source de uma fonte de terceiros é uma proteção barata.

Boas práticas

Um marketplace real, com vários plugins, ganha em legibilidade quando cada plugin documenta a própria função numa tabela no README, mais fácil de escanear do que um parágrafo solto por plugin: uma linha por plugin, dizendo o que ele entrega e qual condição faz o Claude carregá-lo sozinho. Marcar um deles como base obrigatória, quando os outros dependem das convenções dele, poupa a pergunta de por onde começar.

Outro padrão que compensa é uma pasta templates/ no catálogo, com pontos de partida de CLAUDE.md, um por variação de projeto, cada um com marcadores como [FILL] para o que só existe naquele repositório específico: comando de build, porta, alias. Assim o plugin carrega a convenção que vale para todo mundo, e o template cuida do que muda de projeto para projeto.

O campo strict de cada entrada do marketplace.json decide quem manda na definição de um plugin. Com o valor padrão, true, o plugin.json do próprio plugin é a autoridade sobre skills, agentes e hooks, e o marketplace só pode somar componentes extras por cima. Com strict: false, a entrada do marketplace vira a definição inteira, e o plugin sequer precisa de plugin.json próprio; use esse modo quando o catálogo quiser reorganizar ou curar os componentes de um repositório de terceiros de um jeito diferente do que o autor original pretendia.

Versão pede uma disciplina simples: se você declarar version no plugin.json, precisa incrementá-la a cada mudança publicada, porque é essa string que sinaliza atualização para quem já instalou. Omitir o campo também é válido; nesse caso, o Claude Code usa o commit resolvido da fonte como sinal de versão, o que funciona bem para um plugin em desenvolvimento ativo dentro de um time só seu.

Onde cada arquivo mora

O marketplace que ficou pronto neste artigo instala com dois comandos e cresce a cada plugin novo somado ao array plugins. A partir daqui, o trabalho que falta é sempre o mesmo, para qualquer plugin que você queira empacotar: escrever a descrição de cada skill específica o bastante para disparar na hora certa, e testar cada uma isolada, com --plugin-dir, antes de somá-la ao catálogo.

Leituras relacionadas

• Plugin marketplaces, documentação oficial do Claude Code
• Create plugins, documentação oficial do Claude Code