Como compartilhar skills do Claude Code com o time e manter todo mundo no mesmo padrão?

Todo mundo do time usa "a mesma skill", e mesmo assim o agente responde diferente em cada máquina

Isso acontece porque skill no Claude Code não é uma coisa só: ela pode viver em quatro locais distintos, e nada impede que a pessoa A tenha uma versão na pasta pessoal enquanto a pessoa B usa a versão que veio no repositório

Aí o combinado do time vira sorte: o mesmo pedido gera revisões diferentes, checklists diferentes, resultados diferentes

Neste post a gente monta uma referência única de skills compartilhadas em time e, mais importante, garante que todo mundo continue nela depois da segunda semana… que é onde essas coisas costumam desandar 🙂

Onde as skills moram e quem ganha quando há conflito

Antes de qualquer passo a passo, precisa entender o mapa

Segundo a documentação oficial de skills do Claude Code, uma skill pode estar em quatro lugares:

E quando duas skills têm o MESMO nome em níveis diferentes?

A documentação define a ordem: enterprise sobrepõe pessoal, e pessoal sobrepõe projeto

Se liga no detalhe que muda tudo: a cópia pessoal de alguém vence a cópia do repositório

Ou seja, o time pode achar que padronizou porque commitou a skill, enquanto na máquina de cada um a versão antiga continua mandando

Skills de plugin fogem dessa briga, porque usam o namespace plugin-name:skill-name, então elas não conflitam com os outros níveis

Formação Recomendada

Formação Vibe Coding

Do Prompt ao Produto: Crie Software Real com IA

• 474 aulas
• 20 projetos
• 39h 27min

Conhecer formação

O mínimo que um SKILL.md precisa ter:

O frontmatter exige só dois campos: name e description

• name: máximo de 64 caracteres, apenas letras minúsculas, números e hífens
• description: máximo de 1.024 caracteres, e não pode ser vazia

Os demais são opcionais, como disable-model-invocation e allowed-tools

Tome cuidado com uma pasta específica: synced é reservada nos locais enterprise, pessoal e projeto

Não use esse nome pra guardar skill manual do time, porque ele tem dono

Caminho 1: commitar a pasta de skills do projeto

Esse é o caminho mais simples, e resolve muito bem o time que vive dentro de um repositório só

1. Crie a pasta da skill dentro do projeto, uma pasta por skill:

mkdir -p .claude/skills/revisao-de-pr

2. Escreva o SKILL.md com o frontmatter válido:

---
name: revisao-de-pr
description: Revisa pull requests do time seguindo o checklist interno, cobrindo testes, migrations e mensagens de commit
---

# Revisão de PR

Siga esta ordem:

1. Rode a suíte de testes e reporte falhas antes de opinar sobre estilo
2. Confira se toda migration tem caminho de volta
3. Liste os pontos por severidade

O erro comum deste passo: estourar as regras do name

Maiúscula, espaço ou underline não entram, o campo aceita só minúsculas, números e hífens (e no máximo 64 caracteres)

3. Commite o diretório de skills no controle de versão:

git add .claude/skills
git commit -m "skills: checklist de revisão de PR do time"

Quem clonar o repositório passa a receber as mesmas skills, sem instalar nada

O erro comum deste passo: achar que acabou aqui

Se alguém do time já tem uma skill pessoal com o MESMO nome em ~/.claude/skills/, a cópia pessoal vence pela precedência

O repositório parece padronizado e não está

A saída é escolher um nome distinto pro padrão novo, ou combinar que cada um remova a cópia pessoal antiga

Caminho 2: usar symlink para uma fonte única fora do repositório

Às vezes a skill precisa valer em vários repositórios, mas ainda não compensa virar plugin

Pra esse meio de campo dá pra usar symlink: uma entrada nos locais enterprise, pessoal ou projeto pode ser um symlink apontando pra um diretório em outro lugar do disco, e o Claude Code segue o link e lê o SKILL.md do destino

1. Mantenha um diretório central com as skills do time, versionado num repositório próprio:

git clone [email protected]:sua-org/skills-do-time.git ~/skills-do-time

2. Crie a entrada como symlink no local pessoal:

ln -s ~/skills-do-time/revisao-de-pr ~/.claude/skills/revisao-de-pr

No Windows o equivalente é mklink /D no prompt como administrador

3. Repita pros projetos que precisarem da skill como skill de projeto, apontando pro mesmo destino:

ln -s ~/skills-do-time/revisao-de-pr .claude/skills/revisao-de-pr

Assim tu atualiza um lugar só e todos os projetos enxergam a mesma definição

Esse arranjo casa direto com a ideia de manter suas skills num repositório central e reusar em tudo

O erro comum deste passo: cada máquina apontar o symlink pra um caminho diferente, ou pra uma cópia local que ninguém atualiza há semanas

Aí tu volta exatamente pro problema original, versões divergentes, só que agora escondidas atrás de um link 😛

Combine o caminho do diretório central e deixe o git pull dele no ritual de quem trabalha no time

Caminho 3: empacotar as skills como plugin e publicar no marketplace do time

Quando o time cresce e os repositórios se multiplicam, copiar pasta deixa de escalar

Aí o formato certo é plugin

1. Crie o diretório skills/ dentro do plugin, com uma pasta por skill contendo o SKILL.md:

meu-plugin/
├── .claude-plugin/
│   └── plugin.json
└── skills/
    ├── revisao-de-pr/
    │   └── SKILL.md
    └── checklist-de-deploy/
        └── SKILL.md

O plugin também pode declarar caminhos customizados por tipo de componente: skills, commands, agents, hooks, mcpServers e lspServers

2. Crie o manifesto do marketplace no caminho fixo .claude-plugin/marketplace.json:

{
  "name": "my-team-tools",
  "owner": {
    "name": "Time de Plataforma",
    "email": "[email protected]"
  },
  "plugins": [
    {
      "name": "skills-do-time",
      "source": "./meu-plugin",
      "description": "Skills padrão de revisão, deploy e checklist do time"
    }
  ]
}

Obrigatórios no manifesto: name, owner (objeto com os dados do mantenedor) e plugins (array)

Cada entrada de plugin traz name, source e description, sendo version e author opcionais

O erro comum deste passo: escolher um nome reservado

Alguns nomes são de uso oficial da Anthropic, entre eles claude-code-marketplace, claude-code-plugins e claude-plugins-official

3. Valide antes de publicar:

claude plugin validate

A saída esperada é ✔ Validation passed, ou ✔ Validation passed with warnings quando existem avisos

Aviso não reprova a validação, e a flag --strict trata aviso como erro

4. Registre o catálogo no Claude Code:

/plugin marketplace add user-or-org/repo-name

O comando aceita os atalhos /plugin market e rm no lugar de remove

5. Instale pelo gerenciador:

/plugin

Ele abre com abas, incluindo a aba Discover, e na hora de instalar pede a escolha do escopo:

• User: pra você, em todos os projetos
• Project: pra todos os colaboradores do repositório
• Local: só pra você, apenas nesse repositório

O erro comum deste passo: marcar Local achando que está distribuindo pro time

Local é o escopo mais fechado que existe, fica só na tua máquina e só naquele repositório

Como fazer o time inteiro receber o mesmo catálogo ao clonar

Até aqui cada pessoa ainda precisa rodar comandos

Esse é o pedaço que realmente elimina o descompasso: deixar o catálogo declarado no repositório

1. Declare o marketplace do time em .claude/settings.json:

{
  "extraKnownMarketplaces": {
    "my-team-tools": {
      "source": {
        "source": "github",
        "repo": "your-org/claude-plugins"
      }
    }
  }
}

Quem clonar já recebe a mesma fonte, sem precisar decorar comando

2. Ligue os plugins com enabledPlugins, no formato "plugin-name@marketplace-name":

{
  "enabledPlugins": {
    "skills-do-time@my-team-tools": true
  }
}

O erro comum deste passo: registrar o marketplace e esquecer o enabledPlugins

O catálogo fica visível e a skill fica desligada, o que dá aquela sensação de "instalei e não acontece nada"

3. Escolha o escopo certo pro que tu está ligando:

• user: ~/.claude/settings.json
• project: .claude/settings.json, compartilhado com o time
• local: .claude/settings.local.json, que fica no gitignore
• managed: managed-settings.json

Plugin sem entrada em nenhum escopo cai no valor de defaultEnabled

Vale pensar com calma no que entra ligado por padrão, porque existe um limite prático de quantas skills ficam ativas ao mesmo tempo sem atrapalhar o modelo

4. Se forem pouquíssimos plugins, dá pra pular o repositório de marketplace usando source: 'settings'

Nesse formato os plugins listados precisam referenciar fontes externas (por exemplo GitHub ou npm) e ainda precisam ser habilitados um a um em enabledPlugins

Travas de administração: forçar o padrão e impedir catálogo paralelo

Settings de projeto é combinado, não é trava

Quem administra e precisa de garantia trabalha nas managed settings

1. Ligue a atualização automática em cada entrada de extraKnownMarketplaces nas managed settings:

{
  "extraKnownMarketplaces": {
    "my-team-tools": {
      "source": {
        "source": "github",
        "repo": "your-org/claude-plugins"
      },
      "autoUpdate": true
    }
  }
}

Assim ninguém precisa lembrar de atualizar na mão

2. Limite quais marketplaces podem entrar com strictKnownMarketplaces, também nas managed settings

A verificação roda ANTES de qualquer operação de rede ou de arquivo, e vale no marketplace add e também em install, update, refresh e auto-update

Ela aceita fontes do tipo repo (GitHub), url exata, hostPattern e pathPattern

3. Se a ideia é liberar (ou bloquear) uma organização inteira, use curinga de owner

Em 6 de agosto de 2026 o changelog registrou a chegada de entradas curinga de owner ("owner/*") em strictKnownMarketplaces e blockedMarketplaces nas managed settings, pra liberar ou bloquear todos os repositórios de marketplace de uma organização do GitHub

4. Opcional, mas salva a pele em time grande: fixe a entrada numa branch ou tag

Basta anexar @ref ao atalho do GitHub, ou #ref a uma URL git

O erro comum deste passo: tratar o settings de projeto como política

Qualquer um edita o .claude/settings.json do repositório, então a trava inviolável mora nas managed settings, não lá

O time atualizou a skill e nada mudou: por que acontece

Essa é a categoria de problema que mais gera treta no time, porque parece que a distribuição funcionou

Publiquei a skill nova e ninguém recebeu:

A causa costuma ser o campo version do plugin.json

Se tu declara "version": "1.0.0" e publica novos commits sem mudar essa string, quem já usa continua com a cópia em cache, porque o Claude Code enxerga a mesma versão

A recomendação é subir o campo a cada release, ou omitir o campo pra cair na versão resolvida

A dependência entre plugins mudou sozinha:

Por padrão a dependência acompanha a última versão disponível

Pra segurar numa faixa testada, use version constraints

E se liga: quando vários plugins instalados restringem a mesma dependência, o Claude Code faz a interseção das faixas e resolve pra maior versão que satisfaz todas

O nome do plugin ou do marketplace passou a ser recusado:

Em 4 de agosto de 2026 o changelog registrou avisos novos no claude plugin validate, disparados quando o nome de um marketplace ou plugin seria rejeitado pela sincronização de marketplace gerenciado do Claude Desktop

Somado a isso, alguns nomes são reservados (claude-code-marketplace, claude-code-plugins e claude-plugins-official), então rode a validação antes de publicar e não depois da bronca

Apareceu skill numa pasta chamada synced:

O Claude Code baixa as skills habilitadas no claude.ai pra ~/.claude/skills/synced/ quando a variável CLAUDE_CODE_SYNC_SKILLS está definida em modo não interativo

Então se surgiu conteúdo ali que ninguém do time colocou, a origem é essa, e não o repositório de vocês

Qual combinação escolher pelo tamanho e pela rotina do time

Não existe caminho único, existe caminho proporcional ao tamanho da bagunça

Tem ainda um recurso que ajuda muito quando o catálogo cresce: o bloco relevance na entrada do plugin no marketplace.json

Ele recebe um topic e um ou mais signals, que são padrões testados contra a sessão atual (como o diretório de trabalho ou arquivos lidos)

O administrador precisa incluir o nome do marketplace em pluginSuggestionMarketplaces nas managed settings

Com isso o plugin certo aparece fixado no topo da lista Discover, com anotação do tipo "suggested for this directory"

E antes que alguém pergunte: o casamento dos signals roda na máquina do usuário, não gera tráfego de rede e não reporta quais sinais casaram nem pra Anthropic nem pra quem opera o marketplace

Por que padronizar a skill muda o resultado na prática

Dá pra achar que isso tudo é firula de organização, mas o efeito aparece no resultado

No vídeo eu mostro o conjunto de skills que uso como ponto de partida em praticamente todo projeto novo, encadeando uma depois da outra na mesma sessão

Começo com uma skill de brainstorm, que em vez de sair codando faz uma sequência de perguntas até entender o escopo, e só então gera o plano

Depois peço a execução com subagents e TDD (teste primeiro, implementação depois), que é o formato que considero mais seguro quando o projeto tem regra de negócio maior

Esse plano fechou com 14 tarefas concluídas

E não é rápido: quando mostro a terceira tarefa em andamento, a execução já acumulava quase 10 minutos rodando

Gasta mais tempo e mais token que um prompt solto, sim, mas o caminho fica bem mais certeiro por seguir o planejamento anterior

Pra segurança eu preferi não instalar skill pronta de terceiro: pedi pro próprio Claude Code criar uma skill sob medida, descrevendo os itens que eu queria verificar com base nas tecnologias e nas regras daquele projeto

Exigi que a verificação fosse mecânica (rodar comandos reais e contar os problemas) e que a saída trouxesse nota, quebra por categoria e a lista dos problemas encontrados

O resultado: nota 75 no projeto, repetida na execução de teste e na oficial, com nenhum problema crítico, alguns achados de nível alto e alguns de nível baixo

Sacou o ponto? Nota que repete é sinal de definição estável

Se cada pessoa do time tem a sua cópia da skill, essa nota deixa de ser comparável entre a máquina de um e a de outro, e o número vira opinião

Um detalhe de bastidor que também aparece ali: criei a skill como skill de projeto (e não global), porque as tecnologias mudam de projeto pra projeto, e ela não apareceu na sessão em andamento

Só passou a ser reconhecida depois que reiniciei o Claude Code

E antes de confiar, li o arquivo gerado pra avaliar se o conteúdo estava correto mesmo

No vídeo tu vê as skills rodando num projeto real e a execução acompanhada tarefa a tarefa, incluindo a parte chata em que o app subiu com erro no cadastro e no login e eu fui colando o erro de volta até destravar

Conclusão

Skill compartilhada não é problema de ferramenta, é problema de combinado

Commitar a pasta, symlink, plugin no marketplace e managed settings são quatro níveis de compromisso diferentes, e a decisão vem de duas perguntas: quantos repositórios o time toca, e quanto controle a empresa precisa ter

Quanto mais repositório e mais gente, mais o pêndulo vai pro plugin com catálogo declarado no settings de projeto

Próximo passo que eu faria: elege UMA skill que hoje existe em três versões diferentes na equipe, escolhe um dos caminhos, roda o claude plugin validate se for pelo plugin, e só depois migra as outras

Migrar tudo de uma vez é o jeito mais rápido de descobrir que ninguém sabia qual era a versão certa haha

até o próximo post! 😀