Como escrever uma skill do Claude Code para uma stack específica sem quebrar em outro projeto

Fala aí, beleza? Toda skill boa nasce num projeto só, e é exatamente aí que mora o problema

Você escreve uma skill pra revisar componente React, ela fica afiada, salva sua semana

Aí você abre o repositório seguinte, chama a mesma skill e ela começa a mandar criar arquivo numa pasta que não existe, seguindo uma convenção de nomes que era do time antigo…

O motivo quase sempre é o mesmo: a skill misturou regra da stack (o jeito que React, Django ou Rails funcionam) com detalhe daquele repositório (nome de pasta, comando de build, combinado interno do time)

Regra de stack viaja. Detalhe de repo não viaja, e quando ele vai junto de carona vira instrução errada no projeto novo

Neste post eu te mostro o critério pra separar as duas coisas linha a linha, a anatomia mínima de uma skill do Claude Code, o passo a passo pra escrever uma que sobrevive à troca de projeto, e o que fazer com o que sobrou: o específico do repositório tem casa própria, o CLAUDE.md

Regra da stack ou regra do repositório: como classificar cada instrução

Antes de escrever qualquer coisa, roda um teste mental em cada linha que você ia colocar na skill

O teste de portabilidade é uma pergunta só: essa instrução continua verdadeira em OUTRO projeto que usa a mesma stack?

Se continua, é regra da stack e pode ir pro SKILL.md

Se só é verdade por causa deste repositório, é memória de projeto e vai pro ./CLAUDE.md

Formação Recomendada

Formação Claude Code

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

• 114 aulas
• 4 projetos
• 9h 18min

Conhecer formação

Repara que a última linha entra em outro assunto: grau de liberdade

As boas práticas oficiais de autoria falam disso de forma direta. Quando várias abordagens são válidas, você escreve instrução em texto e deixa liberdade alta, porque o Claude escolhe o caminho conforme o caso

Quando a operação é frágil e um passo errado é catastrófico, você reduz a liberdade ao mínimo: script exato, passo fixo, sem espaço pra criatividade

O erro clássico é inverter os dois. Gente que engessa em script o que aceitava variação, e gente que deixa em texto solto justo o procedimento que não podia dar errado

O que você precisa saber antes de criar a skill

A anatomia mínima:

Skill no Claude Code é baseada em arquivo, e a estrutura é bem enxuta

Uma skill é uma pasta, e o nome dessa pasta vira o identificador da skill

Dentro dela, obrigatoriamente, um arquivo SKILL.md

Só isso já é uma skill válida

Além do SKILL.md, existem três pastas opcionais de recursos:

• scripts/ para código executável
• references/ para documentação carregada sob demanda
• assets/ para templates e arquivos usados na saída

Onde a skill fica:

São dois lugares, e a escolha entre eles JÁ é metade da decisão de portabilidade:

• ~/.claude/skills/ para skills pessoais, que valem em qualquer projeto seu
• .claude/skills/ dentro do repositório, para skills daquele projeto

O frontmatter:

O SKILL.md começa com frontmatter YAML entre marcadores ---

Apenas dois campos são obrigatórios: name e description

O name tem limite de 64 caracteres e aceita só letras minúsculas, números e hifens

O description tem limite de 1024 caracteres e não pode ficar vazio

E tem dois campos opcionais que valem conhecer desde já: allowed-tools, que restringe quais ferramentas a skill pode acessar, e disable-model-invocation, cuja função documentada é impedir que o Claude acione a skill por conta própria

Por que a description é tão importante?

Aqui entra o mecanismo de divulgação progressiva

No início da sessão, só o name e a description de cada skill entram no contexto

O corpo do SKILL.md só é lido quando a skill é de fato usada

Ou seja: a description é o único material que o Claude tem pra decidir se aquela skill serve ou não pro pedido atual

Por isso a recomendação oficial de autoria é que ela diga as duas coisas: o que a skill faz e quando o Claude deve usá-la

Se você quiser ver estrutura pronta antes de escrever a sua, a Anthropic mantém um repositório público oficial de Agent Skills, que inclui a skill skill-creator como referência

Passo a passo: escrever uma skill de stack que viaja entre projetos

Bora ver na prática?

Vou usar uma skill de migrations de Django como exemplo, mas o raciocínio é o mesmo pra qualquer stack

1. Delimite o escopo à stack, não ao repo

Antes de abrir editor, escreva numa linha o que a skill faz, e leia em voz alta trocando o nome do projeto

"Revisar componente React seguindo o padrão de hooks" viaja

"Revisar componente do painel admin do sistema X" não viaja

O erro comum deste passo: definir o escopo olhando pro problema de hoje. Você acaba descrevendo uma tarefa daquele repositório, não uma competência da stack

2. Escolha o local certo

Se a skill descreve procedimento de framework e você quer reusar em tudo, ela vai pra ~/.claude/skills/

Se ela só faz sentido dentro daquele repositório (e tudo bem existir skill assim), ela vai pra .claude/skills/ e é versionada junto com o código

O erro comum deste passo: jogar tudo em .claude/skills/ por comodidade e depois copiar a pasta na unha pra cada projeto novo, criando cinco versões que já divergiram entre si

3. Crie a pasta e o SKILL.md com frontmatter

O nome da pasta vira o identificador, então escolhe um nome que descreva a competência:

   mkdir -p ~/.claude/skills/django-migrations

E o arquivo:

   ---
   name: django-migrations
   description: Cria e revisa migrations do Django seguindo o procedimento padrão do framework. Use quando o pedido envolver criar, alterar ou revisar migration de banco em um projeto Django.
   ---

O erro comum deste passo: estourar as regras do name. Nada de maiúscula, nada de espaço, nada de underline: só minúsculas, números e hifens, dentro dos 64 caracteres

4. Escreva a description dizendo o que faz E quando usar

Essa é a parte que mais gente faz correndo, e é justamente a que decide se a skill é acionada na hora certa

Descrição ruim: Ajuda com migrations

Descrição boa é a do passo anterior: diz a competência e diz o gatilho

O erro comum deste passo: citar nome de repositório ou de empresa na description. Aquilo entra no contexto de toda sessão e amarra uma skill que devia ser genérica a um projeto só

5. Escreva o corpo com o procedimento da stack

Corpo é onde entra o passo a passo do framework, o que checar, o que nunca fazer

   ## Procedimento

   1. Verifique se o model já tem a alteração pretendida
   2. Gere a migration e LEIA o arquivo gerado antes de aplicar
   3. Confirme se a operação é reversível e o que acontece com os dados existentes

   ## Nunca faça

   - Editar uma migration que já foi aplicada em ambiente compartilhado

A boa prática oficial recomenda manter o corpo do SKILL.md abaixo de 500 linhas, e quebrar o excedente em arquivos separados dentro de references/

Faz sentido: o corpo é carregado quando a skill é usada, então quanto mais enxuto ele for, melhor. O detalhe longo fica em references/ e é lido sob demanda

O erro comum deste passo: transformar o SKILL.md num manual completo do framework. Skill não é documentação, é procedimento

6. Decida o grau de liberdade de cada trecho

Trecho que aceita variação fica em texto

Trecho frágil, onde um passo errado destrói dado ou ambiente, vira script em scripts/ e o corpo aponta pra ele

   django-migrations/
     SKILL.md
     scripts/
     references/

O erro comum deste passo: escrever script pra tudo. Script fixo engessa e envelhece rápido, use onde o custo do erro justifica

7. Parametrize o que é do projeto, em vez de fixar

No corpo da skill, fale em "a pasta de migrations do app", não em apps/faturamento/migrations

Fale em "o comando de teste do projeto", não no comando exato daquele repo

O caminho real, o comando real e a convenção do time vão pro sistema de memória, que é separado das skills: memória de projeto em ./CLAUDE.md e memória de usuário em ~/.claude/CLAUDE.md, com a memória mais específica tendo precedência sobre a mais ampla

Vale saber como esses arquivos carregam: os CLAUDE.md que estão na hierarquia acima do diretório de trabalho são carregados no início da sessão, e os que estão em subdiretórios só carregam quando o Claude lê arquivos daquele subdiretório

Esse é o mesmo cuidado de quando você senta pra escrever uma especificação clara: separar o que é procedimento do que é contexto

O erro comum deste passo: mover o caminho pro CLAUDE.md e esquecer de tirar da skill. Aí você fica com a informação duplicada e desatualizando em dois lugares

8. Empacote como plugin pra distribuir

Copiar pasta no Slack não é distribuição, é gambiarra com data de validade 😅

Pra distribuir skills entre projetos e times, o Claude Code usa plugins. O plugin é um diretório com manifesto em .claude-plugin/plugin.json e uma pasta opcional skills/ com as skills dentro:

   meu-plugin/
     .claude-plugin/
       plugin.json
     skills/
       django-migrations/
         SKILL.md

A distribuição acontece por marketplace, que é um repositório com o arquivo de registro .claude-plugin/marketplace.json, lido pelo Claude Code na hora de adicionar a marketplace

Do lado de quem instala, são duas etapas:

   /plugin marketplace add owner/repo
   /plugin install nome@marketplace

O erro comum deste passo: empacotar skill que ainda tem caminho de repositório fixo no corpo. Você acabou de distribuir o seu problema pro time inteiro, e agora ele volta multiplicado

Por que a skill quebra em outro projeto (e como corrigir)

Se a sua já está dando problema, vale checar por que a skill não funciona também

Aqui vão os casos que mais aparecem

A skill assume a estrutura de pastas do repo antigo

Sintoma: o Claude cria ou procura arquivo num caminho que não existe no projeto novo, e insiste mesmo você corrigindo

Causa: caminho literal escrito dentro do SKILL.md. Pro modelo aquilo é instrução, não sugestão

Solução: troque o caminho literal por descrição de papel ("o diretório de testes do projeto") e registre o caminho real no ./CLAUDE.md daquele repositório

Como prevenir: faça uma busca no corpo da skill por / antes de salvar. Todo caminho encontrado precisa passar no teste de portabilidade

A description é genérica demais e a skill dispara fora de hora

Sintoma: você pede uma coisa e o Claude puxa uma skill que não tem nada a ver

Causa: lembra que só name e description entram no contexto no início da sessão? Se a description diz só o que faz e não diz quando usar, sobra ambiguidade e o modelo chuta

Solução: reescreva incluindo o gatilho explícito, no formato "faz X. Use quando Y". É exatamente a recomendação oficial de autoria

Como prevenir: quando a skill for perigosa ou você quiser acionamento manual, existe o campo opcional disable-model-invocation no frontmatter, cuja função documentada é impedir que o Claude acione a skill por conta própria

O corpo inchou e virou um monstro de manter

Sintoma: ninguém mais mexe naquele SKILL.md, e ele já contradiz a si mesmo em dois pontos

Causa: o arquivo virou depósito. Procedimento, referência de API, exemplo longo, tudo no mesmo lugar

Solução: a boa prática oficial é manter o corpo abaixo de 500 linhas e, passando disso, quebrar o conteúdo em arquivos separados. O material longo vai pra references/, que é carregado sob demanda

Como prevenir: trate o SKILL.md como índice de procedimento. Se o trecho é consulta e não passo, ele não pertence ao corpo

Regra de time escrita dentro da skill

Sintoma: a skill aplica um padrão de commit ou de nomenclatura que não existe no projeto atual, e o time novo estranha

Causa: combinado interno tratado como se fosse regra da linguagem

Solução: move pro ./CLAUDE.md do projeto. É literalmente o que o sistema de memória existe pra guardar

Como prevenir: guarde a frase de bolso: skill descreve a stack, memória descreve o projeto

Script fixo engessando o que aceitava variação

Sintoma: o Claude segue um passo rígido mesmo quando o caso pedia outro caminho, e o resultado fica pior que se ele tivesse decidido sozinho

Causa: grau de liberdade baixo aplicado num ponto que tinha várias abordagens válidas

Solução: devolve o trecho pro texto e deixa a decisão aberta. Script fixo é pra operação frágil, onde um passo errado é catastrófico

Como prevenir: pergunte antes de escrever o script: "existe mais de um jeito certo de fazer isso?". Se existe, é texto

Exemplos de skills por stack que sobrevivem à troca de projeto

O critério fica mais claro quando a gente aplica em caso real. Se liga em quatro recortes:

Revisão de componente de front

No SKILL.md portável: as regras do próprio framework, o que checar em estado e efeito, os erros clássicos da biblioteca, os pontos de acessibilidade que valem em qualquer app

No ./CLAUDE.md do repo: onde ficam os componentes, qual biblioteca de estilo o projeto usa, o padrão de nome que o time combinou

Padrão de teste

No SKILL.md portável: a estrutura de um bom teste naquele framework de testes, o que merece asserção, o que é teste frágil e por quê

No ./CLAUDE.md do repo: o comando que roda a suíte, onde os testes moram, qual módulo é intocável

Migração de banco

É o caso mais óbvio de grau de liberdade baixo. A sequência de gerar, ler o arquivo gerado e confirmar reversibilidade é procedimento do framework, então viaja tranquilo

E por ser uma operação onde um passo errado é catastrófico, é exatamente aqui que faz sentido um script exato em scripts/, em vez de instrução solta em texto

No ./CLAUDE.md do repo fica o que é local: qual banco, qual ambiente é compartilhado, o que jamais pode ser aplicado direto

Geração de endpoint

No SKILL.md portável: como o framework espera que rota, validação e tratamento de erro sejam montados, e em que ordem

No ./CLAUDE.md do repo: o esquema de autenticação usado ali, o formato de resposta padronizado pelo time, onde registrar a rota nova

Repara no padrão que se repete nos quatro: o como fazer é da stack, o onde e com o quê é do projeto

Conclusão

A ideia central cabe numa linha: skill descreve procedimento da stack, memória descreve o projeto

Quando você mistura os dois, a skill fica ótima num repositório e mentirosa em todos os outros

Quando você separa, a mesma skill do Claude Code atravessa projeto, cliente e time sem retrabalho, e o específico de cada repo vive no lugar dele

Próximo passo prático, e faça o teste hoje mesmo: abra uma skill que você já tem e passe o teste de portabilidade linha a linha

O que continua verdadeiro em outro projeto da mesma stack, fica

O que só é verdade por causa deste repositório, migra pro ./CLAUDE.md

E se a skill for boa demais pra ficar só na sua máquina, empacota como plugin com .claude-plugin/plugin.json e a pasta skills/, publica a marketplace e o time inteiro instala com dois comandos

Skill reaproveitada vale muito mais que skill reescrita, né? 😀

Até o próximo post!