Como manter suas skills do Claude em um repositório e reusar em todos os projetos?

Skill boa presa em um projeto só é skill jogada fora

Fala aí, beleza? Se tu já brincou de criar skills pro Claude Code, aposto que a situação é essa: tem duas em ~/.claude/skills/, mais três espalhadas no .claude/skills/ de projetos diferentes, e nenhuma delas está versionada

Aí tu troca de máquina, ou entra num projeto novo, e começa o ritual: abrir a pasta antiga, copiar o arquivo, colar, torcer

O pior nem é o copia e cola, é perder o rastro do que existe

Neste post a gente resolve isso de vez: centralizar tudo num repositório git, versionar as mudanças e distribuir pras suas outras máquinas (ou pro time inteiro) sem ninguém arrastar arquivo na mão

Bora?

O que você precisa antes de começar

Pouca coisa, se liga:

• Claude Code instalado e rodando
• git configurado na máquina, com acesso já funcionando
• um repositório git pra guardar as skills (pode ser local no começo, dá pra testar tudo com caminho ./)
• pelo menos uma skill que já funciona hoje

Sobre o git: tu não precisa configurar credencial nova pro Claude Code

Os comandos /plugin marketplace add, /plugin install, /plugin update e /plugin marketplace update usam os credential helpers que o git já tem na máquina

Ou seja: acesso HTTPS via gh auth login, Keychain do macOS ou git-credential-store funciona exatamente igual funciona no terminal

Onde as suas skills moram hoje:

Antes de mudar de lugar, vale entender os dois endereços possíveis

Skills pessoais: ficam em ~/.claude/skills/ e valem em todos os seus projetos

Skills de projeto: ficam em .claude/skills/ na raiz do projeto, e só valem ali dentro

A sacada do repositório central é essa: em vez de manter cópia da mesma skill nesses dois lugares em N máquinas, tu mantém UMA fonte da verdade versionada e distribui a partir dela

Pré-inscrição Formação Claude Code

Domine o Claude Code do básico ao avançado

Você vai aprender a criar sistemas completos com Claude Code, sem precisar ser programador. Inscreva-se para ter acesso a um desconto de lançamento e bônus especiais!

Quero minha vaga

Passo a passo: como organizar suas skills em um repositório versionado

1. Crie o repositório com uma pasta por skill, tudo dentro de skills/

Cada skill autocontida na própria pasta, sem dependência de arquivo que mora fora dela

Esse é o mesmo padrão que a Anthropic usa no repositório público de Agent Skills: cada skill na sua pasta, com um SKILL.md carregando instruções e metadados

E por que já colocar tudo debaixo de uma pasta skills/ na raiz? Porque é dali que as skills de um plugin carregam por padrão

Ou seja: tu monta a árvore assim agora e depois não precisa mexer nada pra virar plugin

minhas-skills/
  skills/
    revisao-de-pr/
      SKILL.md
    spec-driven/
      SKILL.md
    seguranca/
      SKILL.md

Se tu já tem uma skill de spec-driven development rodando bem, ela é a candidata perfeita pra inaugurar o repositório

2. Escreva o SKILL.md com as duas partes

Toda skill precisa de um SKILL.md, e ele tem duas partes bem separadas: o frontmatter YAML entre os marcadores ---, que indica quando usar a skill, e o conteúdo markdown embaixo, com as instruções que o Claude vai seguir

---
name: Revisão de PR
description: Revisa um pull request procurando bug de lógica, teste faltando e mudança de contrato de API
---

# Revisão de PR

## Quando usar

Use quando o usuário pedir revisão de um diff ou de um PR aberto

## Como revisar

1. Leia o diff completo antes de comentar qualquer coisa
2. Separe achado de correção obrigatória de sugestão de estilo
3. Aponte arquivo e linha em cada achado

3. Preencha o frontmatter com o que importa

Os campos disponíveis são name, description, disable-model-invocation e allowed-tools

Todos são opcionais, e o recomendado é o description: é ele que faz o Claude saber quando acionar a skill

Então capricha na descrição, escreve o gatilho real ("quando o usuário pedir X"), não uma frase bonita e vaga

O erro comum deste passo: achar que o campo name define o comando da skill

Não define! Em skill pessoal ou de projeto, o name é só o rótulo de exibição nas listagens

O comando continua vindo do NOME DA PASTA

Já me ferrei com isso: renomeia o name no frontmatter, roda, e nada muda… porque a pasta continua a mesma 😛

4. Commite e versione

A partir daqui cada ajuste de prompt da skill vira commit, com histórico e diff

Quebrou uma skill que funcionava? git log e tu descobre exatamente o que mudou

Só isso já paga o trabalho

Como transformar o repositório em um marketplace de plugin

Repositório versionado resolve o histórico, mas ainda não resolve a distribuição

Pra outra máquina instalar isso com um comando, o repo precisa virar um catálogo

1. Crie o arquivo de catálogo na raiz

É o .claude-plugin/marketplace.json, com o nome do marketplace, os dados do dono e a lista de plugins com seus sources

{
  "name": "skills-do-time",
  "owner": {
    "name": "Matheus Battisti"
  },
  "plugins": [
    {
      "name": "minhas-skills",
      "source": "./"
    }
  ]
}

Repara no source: aqui a raiz do repositório é o próprio source do plugin

2. Crie o manifesto do plugin (opcional)

O manifesto vive em .claude-plugin/plugin.json, com name, description e version

{
  "name": "minhas-skills",
  "description": "Skills que eu uso em todos os projetos",
  "version": "0.1.0"
}

E se tu omitir? O Claude Code descobre os componentes nos locais padrão e deriva o nome do plugin pelo nome do diretório

Ou seja: dá pra começar sem manifesto e adicionar depois, quando quiser controlar versão de verdade

3. Confira que as skills estão em skills/ dentro do source do plugin

Esse é o diretório padrão de carregamento das skills de um plugin

Se tu montou a árvore como no Passo 1, com o skills/ na raiz do repositório e o source apontando pra raiz, já está tudo no lugar: carrega sem configuração extra

Agora, se as tuas pastas de skill estão soltas na raiz do repo, esse é o momento de mover elas pra dentro de skills/

O erro comum deste passo: assumir que listar caminhos no campo skills do manifesto substitui o diretório padrão

Não substitui: em skills, os caminhos listados SOMAM ao scan padrão

Isso é diferente de commands, agents e outputStyles, que substituem o diretório padrão

E atenção no formato: todos os caminhos são relativos à raiz do plugin e começam com ./

Como instalar e atualizar as skills em outra máquina

Agora vem a parte massa, que é a hora que o copia e cola morre

1. Registre o marketplace

O /plugin marketplace add aceita repositório do GitHub, URL git, URL remota ou caminho local

Testa local primeiro, é o jeito mais rápido de ver se o JSON está certo:

/plugin marketplace add ./caminho/para/marketplace

2. Fixe uma versão quando quiser estabilidade

Dá pra apontar pra uma branch ou tag específica em vez de sempre pegar o topo

No atalho owner/repo do GitHub tu usa o sufixo @ref, e na URL git tu usa #ref

Útil quando o time não pode acordar com a skill mudando embaixo do pé

3. Use as opções de escopo e de checkout parcial

O --scope <user|project|local> define onde o marketplace vai ser declarado

O --sparse <paths...> limita o checkout a diretórios específicos, via git sparse-checkout

Em repositório grandão isso faz diferença: tu baixa só a pasta das skills, não o mundo

4. Instale o plugin

A sintaxe é plugin arroba marketplace:

/plugin install minhas-skills@skills-do-time

5. Atualize depois de publicar mudança

O fluxo é redondo: tu (autor) dá push das mudanças no repositório, e quem usa roda o update pra atualizar a cópia local

/plugin marketplace update

O erro comum deste passo: digitar o host sem esquema na hora de adicionar o marketplace

A partir do Claude Code v2.1.196, host sem esquema é rejeitado como atalho owner/repo inválido

O próprio erro te orienta: adiciona https:// na frente, ou usa ./ se for caminho local

Como distribuir as skills para o time sem ninguém copiar arquivo

Pra ti sozinho, os passos acima já resolvem

Pro time, dá pra ir além e deixar o convite de instalação dentro do próprio projeto

1. Entenda os escopos de settings

São quatro lugares diferentes, e cada um tem um papel:

2. Declare o marketplace no settings do projeto

A chave é extraKnownMarketplaces, com source do tipo github e o repo no formato owner/repositorio

O efeito é bem legal: quem confia na pasta do projeto é automaticamente solicitado a instalar o marketplace

Ninguém precisa lembrar de rodar comando nenhum

3. Diga o que já vem habilitado

A chave enabledPlugins usa o formato "plugin@marketplace": true/false

{
  "extraKnownMarketplaces": {
    "skills-do-time": {
      "source": {
        "source": "github",
        "repo": "owner/repositorio"
      }
    }
  },
  "enabledPlugins": {
    "minhas-skills@skills-do-time": true
  }
}

E plugin que não tem entrada em nenhum escopo? Ele cai no defaultEnabled dele

É aqui que padrão de time vira coisa real e não recado no Slack: se todo mundo precisa seguir o mesmo jeito de revisar código ou de manter o padrão das notas do projeto, isso vira skill, a skill vira plugin, e o plugin chega habilitado na máquina de cada um

4. Automatize fora da sessão

Existem os subcomandos claude plugin marketplace, equivalentes aos comandos /plugin marketplace da sessão interativa

Serve pra script, pra setup de máquina nova, pra onboarding

O erro comum deste passo: habilitar um plugin que depende de outro que não está instalado

A habilitação resolve as dependências transitivamente no mesmo escopo, e falha se faltar alguma

O caminho inverso também trava: desabilitar falha se outro plugin habilitado depender do alvo

Problemas comuns ao centralizar skills (e como prevenir)

O plugin instalou mas não aparece no /plugin list:

Sintoma: tu instalou, a skill funciona, mas o /plugin list dentro da sessão não mostra ela

Causa: plugins carregados a partir de diretórios de skills aparecem na interface /plugin e no claude plugin list, mas não na saída inline de /plugin list dentro da sessão

A saída inline cobre apenas plugins instalados por marketplace

Solução: confere pela interface /plugin ou pelo claude plugin list

Como prevenir: se tu quer o plugin visível em todas as listagens, distribui ele por marketplace mesmo, não por diretório de skills solto

Não sei o que cada plugin está carregando nem quanto custa:

Sintoma: três plugins instalados e zero ideia do que cada um injeta na sessão

Causa: o plugin pode contribuir com várias coisas ao mesmo tempo, não só skill

Solução: usa a operação de inventário do gerenciador de plugins

Ela lista os componentes que o plugin contribui, agrupados em Skills, Agents, Hooks, MCP servers e LSP servers, com estimativa de quantos tokens ele adiciona a cada sessão

Detalhe importante: o grupo Skills inclui tanto as entradas de skills/ quanto as de commands/

Como prevenir: olha o inventário ANTES de habilitar pro time inteiro, não depois que todo mundo reclamar que a sessão ficou pesada

Falha ao desabilitar um plugin:

Sintoma: tu manda desabilitar e o comando falha

Causa: outro plugin habilitado depende dele

Solução: audita o que está ligado com /plugin list, que aceita --enabled, --disabled e tem o atalho ls, e desabilita primeiro quem depende

Como prevenir: mantém o mapa de dependências curto

E se tu curte interface gráfica, no VS Code dá pra digitar /plugins na caixa de prompt pra abrir o Manage plugins da extensão

As skills que eu uso em todos os projetos (e por que centralizar mudou o jogo)

No vídeo abaixo eu mostro o conjunto fixo de skills que eu uso em praticamente todo projeto novo, encadeadas em sequência no MESMO projeto, justamente pra ver o efeito combinado

Comecei de uma pasta vazia no VS Code e usei uma skill de brainstorm pra planejar antes de escrever código: um app de controle de despesas pessoais, com cadastro por categoria, dashboard mensal e gráfico por categoria

O planejamento devolveu 14 tarefas e um arquivo de plano de execução

Depois pedi a execução do plano com subagents e TDD (teste primeiro, implementação depois), porque em regra de negócio maior isso aumenta a chance de funcionar de primeira

Dica de bastidor: mesmo com o plano já no contexto, eu prefiro referenciar o arquivo do plano explicitamente, pra ter certeza de que ele vai executar o documento certo

Ah, e prepara o dedo: apareceu MUITO pedido de aceite de criação de arquivo na fase de setup, vale pular esses aceites

Subiu com erro, viu? Ao criar conta eu fui jogado pra tela de login e o login falhou

Colei o erro de volta no Claude pedindo análise e correção, e depois disso consegui entrar e cadastrar uma despesa de R$ 1.000 em alimentação pra validar que estava funcionando de ponta a ponta

A interface saiu genérica, sem identidade nenhuma, então usei uma skill de design de frontend pra refazer o visual e os elementos ficaram bem mais consistentes

Só que olha, resultado de skill de design não é garantido, depende MUITO do prompt: boa parte da reclamação de "resultado ruim com IA" nasce de prompt fraco

A parte que mais interessa pro tema deste post é a skill que eu criei sob medida

Eu prefiro criar skill dentro do projeto a instalar uma genérica de terceiro, porque quero ela alinhada às tecnologias e às regras daquele projeto

Pedi ao Claude uma skill de segurança que dá nota de 0 a 100 e faz verificação mecânica (rodar comandos reais e contar os problemas encontrados), listando no prompt o que eu queria coberto: secrets, inputs, autenticação, dependências e headers

Depois que ela foi gerada eu abri o markdown dela pra avaliar se estava correto antes de sair usando (faz isso, sério)

Rodei no projeto e veio relatório com nota 75, sem problemas críticos, com itens de nível alto e baixo, e uma oferta no final de implementar as correções

O que me deixou mais tranquilo foi a nota da execução oficial bater com a do teste anterior: sinal de skill consistente, não de sorteio

Mesmo assim, skill feita por você não passou pelo volume de teste de uma skill de fornecedor, então ela vive em melhoria contínua

Foi por isso que eu joguei um fluxo de auto research em cima dela, com 5 iterações definidas em vez de deixar o loop rodando sem fim

Essa skill de segurança eu deixei como skill de projeto, mas ela poderia muito bem ser global

E é exatamente aí que o repositório entra: skill de planejamento, de execução com subagents e de revisão de segurança não têm motivo nenhum pra viver presas a um projeto só

Nada disso é bala de prata, beleza? É o que funciona na minha rotina

Quando vale ter um repositório de skills (e quando não vale)

Nem toda skill precisa virar plugin, então bora separar os cenários

Dev solo com várias máquinas: vale muito

Aquela skill pessoal que hoje mora em ~/.claude/skills/ e some quando tu formata a máquina passa a ser instalada por plugin, igual em todo lugar

Time que precisa do mesmo padrão: vale

Mesmo padrão de revisão, de deploy, de documentação, com o marketplace declarado no .claude/settings.json do projeto e o pessoal sendo convidado a instalar ao confiar na pasta

Skill específica de um único repositório: não vale centralizar

Se ela só faz sentido com as regras e a stack daquele projeto, deixa em .claude/skills/ local mesmo, é mais simples e mais honesto

Organização que precisa impor política: vale, e o caminho é o managed-settings.json

Monorepo grandão: vale, com o --sparse limitando o checkout aos diretórios que interessam, em vez de arrastar o repositório inteiro

Conclusão

Skill boa é ativo reutilizável, e um repositório de skills do Claude Code é o que transforma arquivo solto em distribuição de verdade: com histórico, com versão fixável e com um comando de update no fim

O próximo passo é pequeno, faz hoje: cria o repositório com UMA skill só dentro de skills/, monta o .claude-plugin/marketplace.json, testa local com /plugin marketplace add ./caminho/para/marketplace e instala com /plugin install

Funcionou? Sobe pro GitHub, declara no .claude/settings.json do projeto e chama o time

Se bater dúvida de como organizar as pastas, o repositório anthropics/skills é uma boa régua visual: cada skill autocontida, com seu SKILL.md do lado

Depois me conta como ficou o teu, tô curioso pra ver os arranjos que vocês vão inventar… 🙂

até o próximo post!