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

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, name e description, o resto é opcional
• Claude Code atualizado, que você checa com claude --version e atualiza com claude 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á

Formação Recomendada

Formação Claude Code

Domine Claude Code do absoluto zero até o avançado

• 120 aulas
• 4 projetos
• 9h 45min

Conhecer formação

Como versionar e revisar as skills de decisão passo a passo

1. 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

2. Escreva a description pensando 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:

---
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

3. 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

4. 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

5. 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

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

6. 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

7. 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"
}

8. 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>

9. 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 🙂

10. 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

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

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!