No meu último post, compartilhei meus workflows com Claude Code depois de mais de 280 mensagens. Uma coisa não parava de aparecer nas conversas: as pessoas queriam saber mais sobre os Skills customizados que construí. Não só o que eles fazem, mas como eu penso para criá-los.
Então aqui vai o passo a passo. Não é um tutorial sobre sintaxe de Skill — isso você acha na documentação. Aqui é sobre o raciocínio: identificar o que automatizar, projetar o Skill, iterar nele e os erros que cometi pelo caminho.
O que me fez começar a construir Skills
Eu não saí buscando construir Skills. Saí buscando parar de me repetir.
Depois de algumas semanas usando o Claude Code todo dia, notei um padrão nas sessões. Toda vez que pegava um ticket de bug, eu passava pela mesma sequência: buscar o ticket no Jira, ler a descrição, criar uma branch com uma convenção de nome específica, implementar a correção, rodar o build, testar, commitar, fazer push, criar o PR e transitar o ticket. Toda. Santa. Vez.
Os passos individuais não eram difíceis. Mas a sobrecarga cognitiva de orquestrá-los — me certificar de seguir a estratégia certa de branches, lembrar de incluir o número do ticket no título do PR, ligar o ticket do Jira corretamente — era real. E quando o Claude esquecia um passo no meio do fluxo, eu tinha que re-explicar o processo todo.
Foi aí que percebi: se estou dando ao Claude as mesmas instruções de múltiplos passos repetidamente, eu deveria codificá-las uma vez e reutilizar.
Skill #1: o pipeline Jira-para-PR
Esse foi meu primeiro Skill de verdade, e passou por três iterações distintas antes de ficar útil.
Versão 1: a abordagem ingênua
Minha primeira tentativa foi basicamente um copia-e-cola dos prompts que eu vinha dando ao Claude manualmente:
# Workflow de Bugfix
1. Buscar o ticket do Jira
2. Criar uma branch de bugfix
3. Implementar a correção
4. Criar um PR
Isso foi... bem fraco. Era vago demais. O Claude criava branches com nomenclatura inconsistente, esquecia de incluir o ID do ticket nas mensagens de commit e às vezes pulava o passo de build inteiro. O Skill capturava o que fazer, mas não como fazer — e é no "como" que mora boa parte do valor.
Versão 2: codificando as convenções
A virada veio quando comecei a codificar as convenções reais do meu time no Skill. Em vez de "criar uma branch", especifiquei o padrão exato de nome. Em vez de "criar um PR", descrevi o que o título e a descrição do PR deveriam conter:
# Workflow de Bugfix
## Estratégia de branches
- Formato do nome da branch: `bugfix/TICKET-ID-descricao-curta`
- Sempre derivar da última `develop`
## Implementação
- Buscar o ticket do Jira via JQL: `key = TICKET-ID`
- Ler a descrição e os critérios de aceite
- Implementar a correção em todos os arquivos afetados
- Rodar `npm run build` depois de cada mudança — não pule isso
## Criação do PR
- Título do PR: `[TICKET-ID] Descrição curta da correção`
- Descrição do PR deve incluir:
- O que estava quebrado
- O que mudou
- Como foi testado
- Transitar o ticket do Jira para "Em Review"
Isso foi significativamente melhor. Mas ainda tive atrito.
Versão 3: lidando com os casos de borda
A versão final veio de acumular padrões de falha. Toda vez que uma sessão dava errado, eu me perguntava: "O Skill poderia ter prevenido isso?" Geralmente a resposta era sim.
Os maiores ganhos vieram de codificar workarounds para as manhas das ferramentas. Por exemplo, a integração com o Jira MCP ocasionalmente retorna resultado vazio na primeira chamada. Em vez de o Claude travar e tentar repetir a mesma abordagem que já falhou, adicionei lógica de fallback direto no Skill:
## Buscando o ticket
- Primeira tentativa: usar a ferramenta MCP do Jira com a chave do ticket
- Se a resposta for vazia: cair para busca JQL `key = TICKET-ID`
- Se as duas falharem: pedir os detalhes do ticket manualmente
Também aprendi a ser explícita sobre o que "feito" significa. Sem um critério claro de conclusão, o Claude às vezes declarava vitória depois de editar o código mas antes de verificar que o build passou:
## Definição de Pronto
Um bugfix NÃO está completo até que:
1. O build passe com zero erros
2. A correção tenha sido verificada (visualmente ou via testes)
3. O PR tenha sido criado e linkado ao ticket do Jira
4. O ticket do Jira tenha sido transitado
Por que três Skills em vez de um
Eventualmente dividi o Skill único em três: hotfix, bugfix e feature. Eles compartilham a mesma estrutura mas diferem na estratégia de branches, na branch base e em quão agressivos são os requisitos de teste. Um hotfix deriva da main e tem requisitos mais rígidos de verificação. Uma branch de feature pode envolver mais trabalho exploratório.
Essa separação pode parecer exagero, mas eliminou uma classe inteira de erros em que o Claude usava a estratégia errada de branches porque o contexto era ambíguo. Quando digito /bugfix, o Claude sabe exatamente quais convenções aplicar. Sem chute.
Skill #2: o workflow de verificação
Esse nasceu da dor. Se você leu meu post anterior, sabe que um dos meus maiores pontos de atrito era o Claude pular o teste até eu pedir explicitamente. Os dados do meu relatório de uso confirmaram isso — várias sessões em que a correção estava tecnicamente certa mas quebrava outra coisa porque ninguém verificou.
O Skill de verificação é mais simples que o pipeline do Jira mas, sem exagero, mais impactante:
# Verificar mudanças
Depois de implementar qualquer mudança de código, execute esta
sequência de verificação:
## Passo 1: Checagem de build
- Rodar `npm run build`
- Se houver erros de TypeScript, corrigir antes de prosseguir
- NÃO pule este passo
## Passo 2: Verificação no browser
- Usar Playwright para navegar até a página afetada
- Tirar um snapshot e confirmar que a UI renderiza corretamente
- Checar o console do browser por erros de runtime ou requisições
com falha
## Passo 3: Teste direcionado
- Interagir com a feature específica que foi alterada
- Clicar em botões, enviar forms, verificar se os dados aparecem
corretamente
- Se algo falhar, corrigir e re-verificar
## Passo 4: Reporte
- Status do build: pass/fail
- Verificação visual: como a página está
- Status do console: erros ou warnings
- No geral: pronto para shippar ou precisa de mais trabalho
A virada aqui foi que esse Skill não precisa ser invocado manualmente toda vez. Eu o referencio a partir dos outros Skills. A "Definição de Pronto" do Skill de bugfix inclui rodar os passos de verificação. Isso cria uma sequência: /bugfix dispara a implementação, que dispara a verificação, que dispara o PR só se tudo passou.
O raciocínio: como decido o que vira Skill
Nem tudo deveria ser um Skill. Aprendi a aplicar um filtro simples:
Faça virar Skill quando: o workflow tem mais de três passos, você já fez ao menos três vezes e os passos envolvem convenções que o Claude não saberia sem ser avisado. Se os três forem verdade, vale os 15 minutos para escrever o Skill.
Não faça virar Skill quando: a tarefa é genuinamente diferente toda vez, ou quando o valor está no raciocínio em vez da execução. Decisões de arquitetura, por exemplo — exigem contexto que muda toda vez. Não quero o Claude no piloto automático para essas.
Há também um meio-termo que uso bastante: regras no CLAUDE.md. São convenções que valem em todos os workflows em vez de serem específicas para um. Coisas como "sempre cheque a estrutura da resposta da API antes de assumir que um bug é do frontend" ou "ao debugar, adicione logs antes de chutar". Não são Skills — são guardrails que tornam toda sessão melhor.
O que eu fiz errado (e o que faria diferente)
Eu super-especifiquei no começo. Meus primeiros Skills tentavam antecipar todo cenário possível. Eram longos, e o Claude às vezes ficava confuso com a lógica de bifurcação. Skills mais curtos e focados funcionam melhor. Deixe o Claude descobrir os detalhes — só dê as restrições e convenções que ele precisa para se manter no trilho.
Eu não testei os Skills em si. Em retrospecto isso parece óbvio, mas nas primeiras vezes que usei um Skill novo, não verifiquei se o Claude de fato seguia todos os passos. Eu só confiava no output. Hoje trato os três primeiros usos de qualquer Skill novo como fase de teste. Acompanho de perto, anoto onde o Claude desvia e refino as instruções.
Esperei demais para separar os Skills. O Skill monolítico "faz tudo" era mais difícil de manter e mais difícil para o Claude seguir do que três focados. Se seu Skill tem lógica condicional ("se hotfix, faça X; se feature, faça Y"), isso é sinal de que deveriam ser múltiplos Skills.
O efeito composto
O retorno real não está em nenhum Skill isolado — está em como eles se compõem. Quando me sento para trabalhar num bug, meu workflow é assim:
/bugfix TICKET-123— o Claude busca o ticket, cria a branch, implementa a correção, verifica e abre o PR- Eu reviso o diff do PR e os screenshots da verificação no Playwright
- Se algo está fora, dou uma correção de uma linha e ele re-roda a verificação
O que costumava ser uma sequência de 30 minutos de troca de contexto — entre Jira, terminal, browser, editor de código e GitHub — agora é um único comando seguido por uma revisão. A carga cognitiva caiu drasticamente.
E porque os Skills codificam as convenções do meu time, o output é consistente. Todo PR segue o mesmo formato. Toda branch usa o padrão correto de nome. Toda correção é verificada antes do PR ser criado. Essa consistência vale mais que a economia de tempo.
Como começar
Se você quer construir seus próprios Skills, eis o que eu sugiro:
Comece rastreando seu atrito por uma semana. Toda vez que repetir uma instrução para o Claude, anote. Depois de alguns dias, você vai ver padrões. As instruções mais repetidas são seus primeiros Skills.
Mantenha a primeira versão simples. De três a cinco passos. Foque nas convenções que o Claude não saberia — padrões de branch, convenções de nome, expectativas de teste. Você sempre pode adicionar mais depois.
Inclua verificação. Seja o que for que o Skill faça, inclua um passo que confirme que funcionou. Uma checagem de build, um screenshot, um run de testes — qualquer coisa. Essa única adição previne mais sessões desperdiçadas do que qualquer outra coisa.
E itere. Skills são código para o Claude. Merecem o mesmo tratamento: comece simples, teste, refine com base no uso real e não tenha medo de refatorar quando ficarem incômodos.
O objetivo não é se automatizar para fora do loop. É automatizar as partes que não precisam do seu cérebro, para você poder focar nas partes que precisam.