As 5 skills que sustentam meu fluxo no Claude Code

Skill, no Claude Code, é um SKILL.md com frontmatter (name + description) que o agente carrega sob demanda quando a descrição casa com o pedido. Não é atalho de prompt: é procedimento versionado, que mora no repositório e vale para qualquer sessão — minha, de um colega, ou de um cron às 9h.

Levantei o uso real nos meus transcripts (~/.claude/projects/, 136 sessões, 01–26/07/2026): 67 invocações em 16 skills distintas. As cinco abaixo concentram a maior parte disso — e, mais interessante que o ranking, elas se encaixam num fluxo único que vai do ticket até o PR aberto.

---

1. relatorio-cards-jira — o que fazer primeiro, hoje

O que faz

Busca todos os cards do Jira atribuídos a mim (assignee = currentUser()), descarta os inativos (Concluído, CANCELADA), ordena pela escala Highest → High → Medium → Low e classifica por etapa de fluxo, não por status:

• Etapa 1 — Finalização: o que já está em Em teste, CODE REVIEW, Em andamento. Para cada card, diz o que falta para fechar — merge, evidência, alinhamento, quebra em subtarefas — extraído da própria descrição.
• Etapa 2 — A iniciar: o que está em Backlog, agrupado por iniciativa/label. Quando os cards formam uma sequência numerada (P5, P6, …), monta o grafo de dependências e separa o que pode começar já do que aguarda predecessor.

Fecha marcando cards vencidos (duedate vs. hoje), listando decisões pendentes que travam o avanço, e uma seção "Próximos passos sugeridos" numerada. Saída sempre no mesmo arquivo, sobrescrito — um relatório vivo, não um histórico de versões.

Roda sob demanda ou pela rotina agendada das 9h (BRT é UTC-3 o ano todo, então 12:00 UTC no cron).

Que problema resolve

Board do Jira mostra estado; não mostra ordem de ação. Toda manhã eu pagava o mesmo pedágio: abrir 15 cards, ler descrição por descrição, reconstruir de cabeça o que estava travado esperando decisão e o que já podia começar. Trinta minutos de leitura para produzir uma decisão de cinco segundos.

Pior: a informação que decide a prioridade não está nos campos estruturados. Está no corpo da descrição — "aguardando alinhamento com o time de dados", "depende do P5". Nenhum filtro JQL alcança isso.

Benefícios

• A classificação é semântica, não sintática. Dois cards em Em andamento podem estar a um merge ou a uma decisão de terceiros de distância. A skill lê a descrição e diz qual é qual.
• Dependências viram grafo explícito. "Pode iniciar já?" é coluna de tabela, não dedução minha.
• Zero configuração diária. cloudId e usuário estão fixados na skill; a rotina das 9h entrega o relatório antes de eu abrir o terminal.
• Os gotchas ficaram resolvidos uma vez. A busca estoura o limite de tokens e vira um .txt — a skill documenta isso como fluxo normal, não como falha. A descrição vem em ADF (JSON aninhado da Atlassian) e exige walker recursivo. jq não existe nesta máquina, então é python3. Cada um desses eu descobri sofrendo uma vez; nenhum eu redescubro.

O último ponto é o real valor de uma skill: conhecimento operacional que não regride. Um driver.py ao lado do SKILL.md faz o processamento pesado — a skill não reimplementa parsing a cada execução.

---

2. tlc-spec-driven — especificação executável, com verificador independente

Skill de terceiro (Felipe Rodrigues, v3.2.0, CC-BY-4.0), e a mais densa das cinco. Quatro fases: Specify → Design → Tasks → Execute.

O que faz

Auto-sizing é o princípio central: a complexidade define a profundidade, não um pipeline fixo. Specify e Execute são sempre obrigatórios; Design e Tasks o agente pula sozinho quando o escopo não pede.

Com uma válvula de segurança: mesmo pulando Tasks, o Execute começa listando os passos atômicos. Se aparecerem mais de 5 passos ou dependências complexas, para e cria o tasks.md — sinal de que a fase foi pulada errado.

Estado mora em .specs/: STATE.md (log de decisões AD-NNN + snapshot de handoff), spec.md com IDs rastreáveis, design.md, tasks.md, validation.md.

O contrato de execução é não-negociável:

1. Testes derivam dos critérios de aceite da spec e afirmam resultados definidos pela spec — nunca espelham a implementação.
2. O gate passa antes de a task fechar — o test runner decide, não autoavaliação.
3. Um commit atômico por task. Nunca agrupar tasks; nunca enfraquecer, pular ou deletar teste para fazê-lo passar.
4. Depois da última task, um Verifier novo roda automaticamente — nunca é opcional, nunca é perguntado.

O Verifier é a parte que muda o jogo. Autor ≠ verificador, com regra evidence-or-zero: ele re-deriva a cobertura de forma independente, sem herdar o modelo mental de quem implementou. Faz duas coisas:

• Checagem ancorada na spec: confirma que o valor afirmado em cada teste é o resultado que a spec define — e sinaliza imprecisões da própria spec.
• Sensor de discriminação: injeta falhas comportamentais em estado descartável e confirma que os testes as matam. Mutante que sobrevive vira task de correção. O loop corrigir → re-verificar é limitado a 3 iterações antes de escalar.

E uma camada auto-evolutiva: cada falha fundamentada (mutante sobrevivente, lacuna de precisão da spec, AC reprovado) é destilada em lição reutilizável, local ao projeto, via scripts/lessons.py. PASS limpo não registra nada. Lições confirmadas são recarregadas nas próximas fases Specify e Design.

Fecha com a Knowledge Verification Chain, em ordem estrita: codebase → docs do projeto → Context7 MCP → web search → sinalizar incerteza. Com a regra explícita: nunca assuma nem fabrique — inventar API propaga erro em cascata por design → tasks → implementação.

Que problema resolve

O modo de falha clássico do agente em feature grande não é escrever código ruim. É escrever teste que confirma o que o código faz, e não o que a spec pede — e depois se declarar aprovado. Fica verde, o critério de aceite continua descoberto, e ninguém percebe até produção.

Junto com isso: contexto que se perde entre sessões, decisões arquiteturais tomadas duas vezes de formas incompatíveis, e a alternativa igualmente ruim de escrever documento de 40 páginas para mudar três arquivos.

Benefícios

• Autoavaliação sai do caminho crítico. O gate é o test runner; o veredito é de um agente que não escreveu o código. É a diferença entre "acho que cobri" e "mutante injetado morreu".
• Testes que discriminam. O sensor de mutação responde a pergunta que cobertura de linha não responde: se o comportamento quebrar, algum teste falha?
• Cerimônia proporcional. Mudança de 3 arquivos não gera design doc. Feature multi-componente gera. Sem escolher template na mão.
• Memória entre sessões. STATE.md com decisões AD-NNN e handoff — "resume work" é ler um arquivo, não reconstruir contexto de cabeça.
• O sistema aprende. Cada verificação reprovada deixa lição; a próxima spec nasce com ela carregada. É o oposto de ferramenta estática.
• Contexto é orçado. Meta de <40k tokens, com regras de "nunca carregue simultaneamente" — o que evita o degradê silencioso de qualidade em janela cheia.

---

3. jira-assistant — Jira sem sair do terminal

O que faz

Operações de issue via MCP da Atlassian: buscar, criar (Task, Epic, Subtask), editar, transicionar status, comentar, gerenciar assignees.

Três decisões de design que importam:

Auto-detecção de configuração. Procura jira-config.mdc em .cursor/rules//.claude/rules/; sem arquivo, descobre os projetos acessíveis via MCP e pergunta. Nada de cloudId chumbado.

Linguagem natural antes de JQL. search("issues em andamento no projeto X") primeiro; searchJiraIssuesUsingJql só quando o filtro precisa ser preciso — e aí com project = {PROJECT_KEY} obrigatório em toda query.

Template fixo de descrição: Contexto, Objetivo, Requisitos Técnicos, Critérios de Aceite, Notas Técnicas, Estimativa. Com duas restrições explícitas: requisitos técnicos em nível macro (o objetivo técnico, não a classe) e nunca caminhos de arquivo — eles mudam e transformam o ticket em documentação mentirosa.

Para criar, o fluxo lê metadados antes: tipos de issue do projeto, depois campos obrigatórios daquele tipo, só então cria.

Que problema resolve

Criar ticket decente custa mais que a decisão de criá-lo. O resultado previsível é um backlog de títulos sem critério de aceite — "ajustar conciliação" — que ninguém consegue estimar nem verificar depois.

E há o atrito de contexto: sair do terminal, achar a aba do Jira, lembrar a chave do projeto, clicar em cinco campos.

Benefícios

• Critério de aceite deixa de ser opcional. O template pede; a skill preenche. Ticket que nasce verificável fecha sem arqueologia.
• Ticket que não apodrece. Proibir caminho de arquivo e detalhe de implementação é o que separa descrição que ainda serve em três meses de uma que virou ruído.
• Portável entre projetos. A auto-detecção fez a skill rodar em 3 repositórios diferentes sem editar uma linha.
• project = obrigatório. Detalhe pequeno com efeito grande: query que acidentalmente varre a instância inteira estoura tokens e traz lixo.

---

4. realizar-commit-pr — de implementação pronta a PR em revisão

O que faz

Seis passos obrigatórios, em ordem:

1. Escopo: git status, git diff, git log antes de commitar. Só arquivos da implementação. Nada de .env, segredo ou mudança não relacionada — se houver alteração fora do contexto, ignora ou pergunta.
2. Commit: semântico, ≤72 caracteres, prefixos feat/fix/chore/refactor/ test/docs/build/ci, mensagem em pt-BR.
3. Push: git push -u origin HEAD quando a branch não rastreia remoto. Nunca force push sem pedido explícito.
4. PR: usa o template do repositório quando existe (.github/pull_request_template.md e variantes); sem template, cai num formato com Descrição / Ticket / Validações. Título começa com [ARCD-XXX], extraído do contexto ou do nome da branch — e se não conseguir identificar, pergunta antes de abrir.
5. Revisores: CODEOWNERS como fonte preferencial, casando com os arquivos alterados; fallback nominal quando não há owner aplicável.
6. Ticket: comentário curto no Jira com o link do PR e transição de em andamento → code review.

Com regras de segurança explícitas: nunca commitar segredo, nunca alterar config global do Git, nunca --no-verify sem pedido, e se o hook falhar — corrigir o problema e criar novo commit, não contornar.

Que problema resolve

O trecho final de qualquer tarefa é repetitivo, tem seis etapas e a etapa esquecida é sempre a última. Código commitado, PR aberto, e o ticket do Jira parado em "em andamento" — o board mente para o time inteiro.

E é onde acontecem os erros caros: git add . levando .env para o histórico remoto, PR sem revisor certo dormindo três dias, --no-verify para escapar de um hook de lint que estava certo.

Benefícios

• O passo esquecível é obrigatório. A transição do ticket faz parte do fluxo, não da minha memória. Board reflete a realidade.
• Segredo não vaza por descuido. Escopo explícito + proibição de .env cobre o incidente clássico de git add ..
• Revisor certo desde o início. CODEOWNERS casado com os arquivos alterados elimina o ping-pong de reatribuição.
• Hook falhando é sinal, não obstáculo. A regra de corrigir em vez de pular preserva o valor do CI local.
• Rastreabilidade sai de graça. [ARCD-XXX] no título + link do PR no ticket fecham o ciclo nos dois sentidos.

---

5. deslop — 828 bytes que melhoram todo commit

A menor das cinco, e a de melhor relação valor/tamanho.

O que faz

Olha o diff contra main e remove o slop que a IA introduziu na branch:

• comentários desnecessários ou fora do estilo local
• checagens defensivas e try/catch anormais para caminhos de código confiáveis
• casts para any usados só para calar o type checker
• aninhamento profundo que pede early return
• qualquer padrão inconsistente com o arquivo e a base ao redor

Com três guardrails: comportamento inalterado (exceto bug claro), edições mínimas em vez de reescrita ampla, resumo final em 1–3 frases.

Que problema resolve

Agente escreve código que funciona e soa errado. Comenta o óbvio (// incrementa o contador), embrulha em try/catch uma chamada interna que não falha, silencia o TypeScript com as any, aninha quatro if onde cabiam dois early returns.

Nada disso quebra teste. É exatamente por isso que passa. E o custo é composto: cada merge desses move a média do estilo do repositório um pouco para baixo, até o "padrão do projeto" ser o slop — e aí o próprio agente começa a imitá-lo, porque ele lê o código ao redor para decidir como escrever.

O try/catch supérfluo é o pior dos cinco: ele engole erro. Quando quebrar, você perde a stack trace e o horário do incidente descobrindo onde.

Benefícios

• Blast radius no diff, não no repo. Compara contra main — revisa o que esta branch trouxe, não a dívida histórica. Escopo pequeno, resultado confiável.
• Interrompe a espiral. Slop que não é mergeado não vira exemplo para o próximo agente imitar.
• Guardrail de comportamento. "Sem mudança de comportamento" é o que torna seguro rodar antes de todo commit — limpeza não é refatoração disfarçada.
• Revisor humano gasta atenção no que importa. PR sem ruído de estilo recebe revisão de lógica.
• Tamanho é a feature. 828 bytes: cinco focos, três guardrails. Carrega barato, não compete por contexto, cabe em qualquer sessão.

---

O encaixe: as cinco são um fluxo, não cinco ferramentas

O ranking esconde o mais interessante. O CLAUDE.md do suportehub já encadeia parte disso como regra do projeto:

Utilize a skill deslop antes de realizar qualquer commit Utilize a skill realizar-commit-pr para criação de commits e/ou abertura de pull request

Somando ao padrão de 1 PR por fase de implementação (as fases do tasks.md do SDD), o ciclo completo fica:

    relatorio-cards-jira      → o que atacar hoje (etapa + dependências + vencidos)
              ↓
    jira-assistant            → ticket com critério de aceite verificável
              ↓
    tlc-spec-driven           → Specify → Design → Tasks → Execute
                                (commit atômico por task, gate de testes)
              ↓
    deslop                    → limpa o slop do diff da branch
              ↓
    realizar-commit-pr        → commit + push + PR + revisores
              ↓
    jira-assistant            → ticket → code review, link do PR

Cada seta é um handoff que eu não faço mais na mão. E o fluxo fecha em si: o ticket que o jira-assistant cria com critério de aceite é exatamente a entrada de que o tlc-spec-driven precisa para derivar teste da spec em vez da implementação. Ticket mal escrito quebra a verificação três etapas adiante.

Isso explica por que Jira concentra 39% do meu uso (26 de 67 invocações): o gargalo nunca foi escrever código.

---

O que essas cinco ensinam sobre escrever skills

Cinco padrões que aparecem em todas, e que valem para a próxima que eu escrever:

1. Codifique o gotcha, não só o happy path. O melhor conteúdo do relatorio-cards-jira são os gotchas: jq ausente, descrição em ADF, resultado que estoura tokens e vira .txt — "não é falha, é o fluxo normal". Isso transforma dor aprendida em ativo permanente.

2. Separe quem faz de quem verifica. O Verifier do tlc-spec-driven existe porque autoavaliação de agente é o ponto cego estrutural, não um bug pontual. Author ≠ verifier, evidence-or-zero.

3. Guardrail é o que torna a skill segura de rodar sempre. "Comportamento inalterado" no deslop, "nunca force push" no realizar-commit-pr, "nunca fabrique API" no SDD. Sem eles, cada invocação exigiria revisão — e eu deixaria de invocar.

4. Proporcione a cerimônia ao escopo. Auto-sizing é o que faz o SDD sobreviver ao uso real. Processo que cobra o mesmo preço de uma mudança de 3 arquivos e de uma feature multi-componente é abandonado no primeiro dia corrido.

5. Detecte a configuração, não a fixe. O jira-assistant roda em 3 repositórios sem edição porque descobre projeto e cloudId. Skill com valor chumbado morre no segundo projeto — a menos que seja deliberadamente pessoal, como o relatorio-cards-jira.

O denominador comum: nenhuma dessas skills automatiza a parte difícil do trabalho. Elas automatizam a parte repetível ao redor da parte difícil — e devolvem atenção para onde ela rende.