Como versionar e revisar as skills de decisão do time sem virar bagunça?

Versionar skills do Claude Code começa por tirar o critério do ~/.claude/skills/ pessoal e colocar em .claude/skills/ dentro do repositório, que é commitado e compartilhado com o time. Dali pra frente toda mudança no SKILL.md entra por pull request, é revisada por outra pessoa e validada com claude plugin validate .claude/skills (em CI, com --strict, warnings já derrubam a execução). Quando o critério vale pra vários repos, empacote como plugin: version no plugin.json mais push, e o time recebe rodando claude plugin update ou com auto-update ligado no marketplace.
Skill de decisão não é documentação bonita no repo, é a regra que o time usa pra decidir
Quando a skill define o que priorizar, quando aprovar e qual caminho seguir, cada edição solta na pasta pessoal de alguém vira um critério paralelo
E o pior tipo de bagunça é essa: todo mundo jura que está decidindo igual, e não está
O caminho é tratar skill como código de verdade: histórico de mudanças, revisão de outra pessoa antes de valer pra todos, e um jeito claro de avisar o time quando o critério muda
Bora ver na prática?
O que você precisa antes de começar
- Um repositório git com acesso do time, porque o mecanismo de revisão e de histórico vai ser o do próprio git, não um recurso mágico dentro da ferramenta
- Entender o formato: uma skill é uma pasta com um arquivo
SKILL.md, que tem frontmatter YAML mais corpo em markdown, e pode carregar arquivos de referência e scripts - Saber o mínimo obrigatório: a especificação Agent Skills exige só dois campos no frontmatter,
nameedescription, o resto é opcional - Claude Code atualizado, que você checa com
claude --versione atualiza comclaude update. Se você pretende usar evals de plugin (passo 6), o requisito é Claude Code v2.1.269 ou superior - Uma decisão de escopo tomada antes de mexer em arquivo: esse critério vale só pra este repositório, ou vale pro time em vários projetos? A resposta muda tudo do passo 7 em diante
Se a parte de organização de pastas e commits ainda te deixa em dúvida, vale passar antes pelo guia de versionar skills no Git e voltar pra cá

Black Week do Nexus
A formação de IA mais completa do Brasil
- 7 formações · 112 cursos · 26 mil alunos
Como versionar e revisar as skills de decisão passo a passo
- Tire a skill da sua máquina e coloque no repositório
Skills pessoais ficam em ~/.claude/skills/, e skills de projeto ficam em .claude/skills/, que é commitado no repositório e compartilhado com quem trabalha nele
Enquanto o critério mora só na sua home, ele não é do time, é seu
mkdir -p .claude/skills
mv ~/.claude/skills/decisao-de-prioridade .claude/skills/
git add .claude/skills/decisao-de-prioridade
git commit -m "move skill de decisao de prioridade para o repo"
O erro comum deste passo: copiar em vez de mover e deixar a versão pessoal viva. Aí a pasta do repo diz uma coisa, a sua diz outra, e você decide pela sua sem perceber
- Escreva a
descriptionpensando no acionamento
A seleção da skill é feita pela description: o Claude compara o pedido com as descrições disponíveis e ativa as que casam
Ou seja, description ruim não é detalhe de estilo, é skill que nunca liga
Os limites da spec pros campos obrigatórios:
| Campo | Limite | Regra |
|---|---|---|
name |
máximo de 64 caracteres | só letras minúsculas, números e hífens, sem hífen no começo ou no fim |
description |
máximo de 1024 caracteres | não pode ser vazia |
---
name: decisao-de-prioridade
description: Aplica o critério de priorização do time quando o pedido envolve escolher entre bugs, dívida técnica e feature nova, ou quando é preciso decidir o que entra na sprint
---
O erro comum deste passo: description genérica tipo "ajuda com decisões do time". Ou ela nunca ativa, ou ativa em tudo e atropela o resto
- Registre a versão do critério no lugar certo
Aqui tem uma pegadinha: version NÃO é campo da especificação do SKILL.md
Ele aparece apenas como sugestão de chave aninhada dentro do bloco opcional metadata
Os outros opcionais da spec são license, compatibility (máximo de 500 caracteres) e o experimental allowed-tools
---
name: decisao-de-prioridade
description: Aplica o critério de priorização do time quando o pedido envolve escolher entre bugs, dívida técnica e feature nova
metadata:
version: 1.3.0
dono: squad-plataforma
---
O erro comum deste passo: inventar um campo de topo (version: solto, category: solto) e quebrar o parse do frontmatter. Categoria, dono e changelog são convenção do time, então deixe dentro de metadata ou no corpo markdown
- Faça a mudança passar por outra pessoa
Como o arquivo está no repositório, mudança de critério entra por pull request como qualquer código
Não precisa de fluxo especial: precisa de alguém olhando o diff antes de o critério valer pra todos
E se liga nisso: o Claude Code carrega skills de projeto do diretório onde a sessão foi iniciada e de todos os diretórios pai até a raiz do repositório
Então uma skill dentro de apps/api/.claude/skills/ soma com a da raiz, ela não substitui
O erro comum deste passo: aprovar uma skill nova de subpasta sem olhar a da raiz e acabar com duas skills concorrendo, cada uma com um critério diferente pra mesma decisão
- Valide antes de mergear
Pra achar SKILL.md com frontmatter que não parseia, aponte o validate pra pasta de skills
claude plugin validate .claude/skills
claude plugin validate ~/.claude/skills
E no CI, quando o critério já está empacotado como plugin, use o modo estrito
claude plugin validate --strict ./seu-plugin
Com --strict a execução sai com exit code 1 também em warnings, como campo desconhecido no manifesto ou version ausente. Run limpo imprime a validação aprovada

VPS Hostinger para seu sistema
10% OFF extraVPS com SSD NVMe e backups semanais. O cupom MATHEUSHORADECODAR é aplicado automaticamente pelo link.
Ver planos com 10% OFF →O erro comum deste passo: rodar só na sua máquina, esquecer do CI e deixar frontmatter quebrado entrar na main. Skill que não carrega não avisa em voz alta, ela só não acontece
- Teste se o critério ainda decide igual
Validar diz que o arquivo está bem formado, não que o critério continua o mesmo
Pra isso existem os evals de plugin: o comando roda o plugin contra uma suíte de casos e pontua os resultados
Cada caso é um prompt realista mais um ou mais graders (regex na resposta, verificação de tool chamada, ou rubrica julgada por outro modelo)
A suíte vive num diretório evals/ dentro do plugin, com cada caso em um subdiretório com prompt.md, case.yaml ou ambos
claude plugin eval init
claude plugin eval .
claude plugin eval . --case priorizar-bug-critico --runs 1 --ablation none
Tome cuidado: cada execução de eval e cada grader do tipo judge é chamada real de modelo, cobrada no uso do plano ou na conta de API
O erro comum deste passo: pendurar a suíte inteira em todo commit e queimar uso sem necessidade. No dia a dia, isole o caso que mexeu com --case e --runs 1
- Empacote como plugin quando o critério vale pra mais de um repo
Skill no .claude/skills/ resolve um repositório
Quando o mesmo critério precisa valer em cinco, aí entra o plugin com manifesto
No plugin.json, o único campo obrigatório é name. version, description e author são opcionais, e a ausência gera warning na validação
Mas atenção: version é justamente o que define a versão entregue aos usuários, então tratar ele como opcional aqui é dar um tiro no pé
{
"name": "skills-de-decisao",
"version": "1.3.0",
"description": "Critérios de decisão do time: priorizacao, aprovacao de PR e escolha de caminho tecnico"
}
- Publique o catálogo
Um marketplace de plugins é um diretório ou repositório com um arquivo .claude-plugin/marketplace.json que lista os plugins e de onde buscar cada um
Pra cada pessoa do time passar a receber esse catálogo, ela registra o marketplace pelo shell
claude plugin marketplace add sua-org/skills-de-decisao
Também funciona com a URL do repositório no lugar de <owner>/<repo>
- Escolha o escopo na instalação
Na hora de instalar, dá pra escolher entre dois escopos: user, que habilita pra você em todos os projetos da máquina, e project, que habilita pra todo mundo do repositório via .claude/settings.json commitado
Critério de time é project, sem choro
O erro comum deste passo: instalar no escopo user, ver funcionando bonito na sua sessão e achar que o time recebeu. Não recebeu 🙂
- Avise o time que o critério mudou
Não existe changelog nativo de skill nem notificação automática caindo no Slack de ninguém, então o aviso é a própria distribuição
Publicando por marketplace próprio, o fluxo é: incrementa o version do plugin.json e dá push
Quem roda o update, ou está com auto-update ligado, recebe a nova versão
claude plugin update skills-de-decisao@sua-org
Pela sessão o caminho é /plugin, aba Installed, e escolher Update now
O auto-update é por marketplace, e liga ou desliga em /plugin, aba Marketplaces, com Enable/Disable auto-update. Com ele ligado, depois que a sessão inicia o Claude Code atualiza as cópias locais dos plugins instalados dali
O erro comum deste passo: subir o critério novo sem tocar no version. O arquivo mudou no repo do catálogo e ninguém foi atualizado
Quando a bagunça aparece: sintomas e como resolver
A skill existe, está commitada, e simplesmente não aciona
Causa: a seleção é feita pela description, então uma descrição fraca ou vaga não casa com o pedido real de quem está na sessão
Solução: reescreva a description com os gatilhos de verdade (as palavras que o time usa quando pede aquela decisão), respeitando o limite de 1024 caracteres
Como prevenir: trate a description como parte revisável do PR, não como comentário. Se o revisor não consegue imaginar o pedido que dispara aquela skill, ela ainda não está pronta
O CI falha e a mensagem não é óbvia
Causa: frontmatter que não parseia, campo desconhecido no manifesto, ou version ausente. Com --strict, warnings também derrubam a execução com exit code 1
Solução: rode claude plugin validate .claude/skills na sua máquina e claude plugin validate --strict ./seu-plugin igual o CI roda, aí você vê o mesmo erro antes de abrir o PR

Crie sistemas com IA para vender
Prompts, modelos e checklists para criar e publicar seu sistema com IA e preparar a oferta para o primeiro cliente.
Quero o e-book gratuito Receba o livro e os bônus no seu e-mail.Como prevenir: validate como job obrigatório no pipeline, do mesmo jeito que lint de código. Esse é o tipo de padronização que evita discussão boba na revisão, e vale o mesmo raciocínio de padronizar PR entre Claude Code e Codex quando o time usa mais de uma ferramenta
Metade do time continua decidindo pelo critério antigo
Causa: auto-update do marketplace desligado, ou plugin instalado em escopo user na máquina de cada um em vez de project no repositório
Solução: peça o claude plugin update <plugin>@<marketplace>, ou ligue o auto-update em /plugin, aba Marketplaces. Pra critério que é do repositório, instale no escopo project e commite o .claude/settings.json
Como prevenir: todo bump de version do critério vem com o comando de update no corpo do PR, escrito, pronto pra copiar
A dependência de outro plugin não sobe
Causa: um plugin pode declarar dependências de outros plugins com restrição de versão em semver, tipo ^2.0 ou ~2.1.0, no plugin.json ou na entrada do marketplace. Quando vários plugins restringem a mesma dependência, o Claude Code intersecta as faixas e resolve pra maior versão que satisfaz todas
Solução: se nenhuma tag satisfaz a interseção, o auto-update pula a dependência e registra o motivo. Esse skip fica listado na aba Errors do /plugin, nomeando o plugin que está restringindo. Abra ali, veja o culpado e afrouxe a faixa dele
Como prevenir: faixa larga demais deixa entrar mudança de critério não testada, faixa estreita demais travá o time. Escolha a faixa depois de rodar os evals, não antes
Três formas de organizar as skills de decisão do time
| Forma | Onde o critério vive | Quem recebe | Quando usar |
|---|---|---|---|
| Só no repositório | .claude/skills/ commitado |
quem trabalha naquele repo | critério de um produto, um time, um contexto |
| Plugin + marketplace interno | plugin.json mais .claude-plugin/marketplace.json |
quem registrou o marketplace e instalou | mesmo critério valendo em vários repositórios |
| Governança central | managed settings da organização | todo mundo, por cima da config local | quando "cada um instala o que quer" não é aceitável |
Quando ficar só no repositório
Se o critério é de um produto e ninguém fora dele precisa daquilo, .claude/skills/ resolve e ponto
Histórico, blame, revisão e rollback? É o git, o mesmo que você já usa há anos
Simples é bom aqui, não subestime
Quando empacotar em plugin e marketplace interno
A hora de empacotar é quando você se pega copiando a mesma pasta de skill pro terceiro repositório
Com plugin você ganha o version como canal de aviso: bump mais push, e quem roda claude plugin update ou tem auto-update ligado passa a decidir pelo critério novo
E ganha também a suíte de evals viajando junto com o critério, o que é bem massa pra não descobrir regressão de decisão pelo chute
Quando a governança precisa ser central
Por managed settings, a organização pode permitir ou bloquear marketplaces, forçar a instalação de plugins e desligar o carregamento só de sessão
São três alavancas: a allowlist strictKnownMarketplaces, a blocklist blockedMarketplaces e o enabledPlugins gerenciado
E managed settings sobrepõem as configurações locais, então não é sugestão, é regra
As listas de marketplaces permitidos e bloqueados são aplicadas em dois momentos: antes de qualquer download (ao adicionar marketplace e em cada install, update, refresh e auto-update) e de novo no início da sessão, pros plugins já instalados
No plano Enterprise ainda existe um endpoint de analytics, o GET /v1/organizations/analytics/plugins, que retorna contagens diárias de instalações e invocações por plugin em Claude Code e Cowork
Dá pra descobrir ali aquela skill de decisão que ninguém nunca invoca 😛
Fechando a ideia: skills seguem o padrão aberto Agent Skills, que funciona em outras ferramentas, e o Claude Code estende esse padrão com controle de invocação, execução em subagente e injeção dinâmica de contexto
Quer dizer que o critério que você versionar hoje não fica preso num formato proprietário
Vídeo: automações e agentes no dia a dia
Pra começar do zero na parte de agentes e automação, este vídeo do canal mostra prompts virando automações no Antigravity 2.0, com scheduled tasks fazendo o trabalho rodar sozinho
Conclusão
Critério de decisão versionado é critério auditável
Enquanto a skill mora na home de cada um, ninguém consegue responder a pergunta mais básica do time: quando foi que a gente passou a decidir assim, e quem aprovou isso?
Com o arquivo no repositório, a resposta é um git log
Próximo passo, hoje mesmo: escolha UMA skill de decisão que vive em ~/.claude/skills/, mova pra .claude/skills/ do repo, rode o claude plugin validate .claude/skills e abra o primeiro pull request de revisão de critério
Uma skill, um PR, um revisor
O resto vem depois…
até o próximo post!
Perguntas frequentes
Skill pessoal em ~/.claude/skills/ conta como critério oficial do time?
Não, skill pessoal fica só na sua máquina, em ~/.claude/skills/, e não é compartilhada com ninguém. O critério só vira do time quando mora em .claude/skills/ dentro do repositório, commitado e versionado no git
Dá pra colocar version direto no frontmatter do SKILL.md?
Não, version não é campo da especificação Agent Skills. Ele só aparece como sugestão de chave dentro do bloco opcional metadata, tipo metadata: version: 1.3.0, e não como campo solto no topo do frontmatter
Skill dentro de uma subpasta do projeto substitui a skill da raiz do repositório?
Não, o Claude Code carrega em cascata: soma as skills de .claude/skills/ do diretório onde a sessão iniciou com as de todos os diretórios pai até a raiz do repo. Por isso uma skill em apps/api/.claude/skills/ se soma à da raiz, ela não a substitui, e isso pode gerar dois critérios concorrendo pra mesma decisão
Como evitar que um SKILL.md com frontmatter quebrado passe direto pro CI?
Rode claude plugin validate .claude/skills antes de abrir o PR pra achar erro de parse localmente. No CI, use claude plugin validate --strict apontando pro plugin, porque o modo estrito falha com exit code 1 também em warnings, como campo desconhecido ou version ausente
Rodar eval de plugin no Claude Code tem algum custo?
Sim, cada execução de eval e cada grader do tipo judge é uma chamada real de modelo, então consome uso do seu plano ou gera custo na conta de API. Vale rodar caso isolado com claude plugin eval . --case <nome> --runs 1 --ablation none antes de rodar a suíte inteira
Preciso atualizar o Claude Code pra usar evals de plugin nas skills de decisão?
Sim, evals de plugin exigem Claude Code v2.1.269 ou superior. Confira sua versão com claude --version e, se estiver defasada, atualize com claude update antes de montar a suíte em evals/
Formações
Formação Vibe Coding
Do Prompt ao Produto: Crie Software Real com IA
- 474 aulas
- 20 projetos
- 39h 30min
Blog | Mais populares
Como compartilhar skills do Claude Code com o time e manter todo mundo no mesmo padrão?
Skills compartilhadas em time podem virar bagunça: cada um com sua cópia. Veja 4 formas de manter o mesmo padrão no Claude Code, do repo ao marketplace.
Como funcionam as skills do Claude Code por dentro (e o que faz o modelo decidir carregar uma)
Entenda como funcionam as skills do Claude Code: a estrutura SKILL.md, o frontmatter YAML e o que faz o modelo decidir carregar cada skill automaticamente.
Como versionar suas skills do Claude Code no Git sem bagunçar o repositório
Aprenda a versionar skills do Claude Code no Git sem bagunçar o projeto: diferença entre skill de projeto e pessoal, .gitignore e settings.json certos.
