Uma skill e um pacote de instrucoes e ferramentas que muda o comportamento do Claude Code para uma tarefa especifica. Em vez de explicar o mesmo processo todo dia ("antes de codar, escreva um teste"), voce empacota essa logica numa skill e o agente carrega ela quando precisar.

Tecnicamente, uma skill e um diretorio com um arquivo SKILL.md (frontmatter YAML + corpo markdown) que descreve quando ativar e como agir. Pode incluir slash commands, sub-agents, hooks, e referencias a outras skills.

# Estrutura minima de uma SKILL.md
---
name: grill-me
description: Stress-testa um plano antes de codar.
  Use quando o usuario disser "vou comecar a implementar",
  "tenho uma ideia", "faz sentido fazer assim?".
---

# Grill Me

Voce e um senior cetico. Antes de aceitar qualquer plano:

1. Liste 5 suposicoes implicitas no pedido do usuario.
2. Para cada uma, pergunte "e se essa estiver errada?".
3. Sugira o experimento mais barato para validar cada uma.
4. So entao retorne o plano refinado.

O problema mais caro nao e codigo errado — e codigo certo da coisa errada. O usuario pede X mas quer Y, o agente codifica X perfeitamente, e duas semanas depois o feature e jogado fora.

Quando agente e humano nao compartilham vocabulario, cada conversa precisa ser explicada do zero. Eric Evans (autor de Domain-Driven Design) chama isso de ausencia de linguagem ubiqua: termos que toda a equipe — humanos e agentes — usa da mesma forma.

Exemplo concreto. Imagine um curso onde "aula" pode ser um placeholder OU uma instancia real materializada com aluno e progresso. Sem linguagem ubiqua, voce escreve assim:

LLMs sao treinados pra produzir codigo que parece certo. Tipos batem, imports existem, sintaxe e valida — e mesmo assim a logica esta errada. Sem um sinal externo (testes), o agente acredita no proprio output.

A solucao classica e TDD (Test-Driven Development): escrever o teste primeiro, ver ele falhar (vermelho), implementar o minimo pra ele passar (verde), depois refatorar. Skills como /tdd impoem esse ciclo no agente.

Codigo apodrece. Foi documentado por Foote e Yoder em 1997 com o termo "Big Ball of Mud": sistemas que crescem sem arquitetura coerente porque cada feature foi adicionada na pressa, sem refator. Com agentes a velocidade aumenta — e o apodrecimento tambem.

A intuicao errada: "vou pedir pro agente refatorar tudo agora". A intuicao certa: refator e oportunidade, nao evento. Voce nao reescreve o sistema; voce identifica uma duplicacao e a unifica quando ja precisa mexer naquela area.

Skills individuais ja ajudam. Mas o ganho real aparece quando elas se compoem em fluxos — cada uma resolve um problema, e o output de uma alimenta a proxima.

Workflow tipico de uma feature, do zero ao codigo em producao:

   /grill-with-docs        Stress-testa a ideia contra docs e ADRs
          │              (elimina desalinhamento, problema #1)
          ▼
   /to-prd                 Vira documento de produto curto e cravado
          │              (fixa linguagem ubiqua, problema #2)
          ▼
   /to-issues              Quebra o PRD em issues pequenas e testaveis
          │              (escopo pequeno = menos ball of mud)
          ▼
   /tdd                    Para cada issue: teste vermelho -> verde -> refactor
          │              (resolve problema #3)
          ▼
   /triage                 Revisa diff, sugere refator pontual antes do merge
                         (combate problema #4, deepening opportunity)

Cada seta e uma transicao deliberada. O usuario nao precisa segurar o contexto inteiro na cabeca — as skills fazem o handoff. O PRD vira input do /to-issues; a issue vira input do /tdd; o diff vira input do /triage.