📜 O que é uma Skill
Uma Skill é um processo reutilizável declarado em Markdown — com entrada esperada, passos a seguir, saída definida e exemplos. No Claude Code, ela se torna um slash command: você digita /formato-curso e o agente executa o processo completo. É o oposto de pedir tudo do zero toda vez.
🔑 Skill vs Prompt: diferença fundamental
- Prompt — instrução única, esquecida após a resposta. Sem estrutura, sem exemplo, sem reutilização.
- Skill — documento persistente com comportamento declarado. O agente o lê e executa o processo completo, toda vez que invocado, com a mesma qualidade.
- Resultado — skill garante consistência que prompt não garante. É a diferença entre pedido verbal e SOP escrito.
💡 Quando criar uma skill
Se você pediu a mesma coisa ao agente mais de três vezes, é hora de codificar como skill. Marco usa /analise-campanha toda semana. Sally usa /scaffold-caso toda vez que abre processo. Sana usa /sumario-clinico no início de cada consulta.
🛤️ Caminho crítico da skill
O caminho crítico é a sequência de passos que sempre funciona — sem desvios, sem improvisação. É o resultado da iteração: você testa, observa onde o agente tropeça, refina os passos até o happy path ser sólido. Sem critical path explícito, o agente perde tempo explorando.
🗺️ Exemplo: caminho crítico de /scaffold-caso (Sally)
📐 Anatomia de uma Skill
Skills bem construídas têm estrutura previsível: frontmatter com metadados, body com instruções, exemplos de uso. O agente aprende a antecipar o que vai encontrar — e executa com mais precisão. Padronização permite auditoria e reuso.
📄 Template canônico de skill
--- name: analise-campanha description: Analisa performance de campanhas de mídia paga e gera recomendações trigger: /analise-campanha inputs: - silver_platter: marketing.md (obrigatório) - periodo: últimos 7 dias (padrão) outputs: - análise narrativa com dados - 3 recomendações priorizadas - 1 alerta se ROAS < 2.5x when_to_use: Toda segunda-feira ou após pedir revisão de campanha específica --- ## Instruções 1. Ler `platters/marketing_current.md` 2. Verificar timestamp — se > 24h, alertar antes de continuar 3. Identificar as 3 campanhas com pior ROAS 4. Comparar com benchmark da semana anterior 5. Gerar análise em 3 parágrafos: contexto, achados, recomendações 6. Se ROAS geral < 2.5x, incluir alerta explícito no topo ## Exemplos Input: "analise as campanhas de Black Friday" Output esperado: Análise com dados reais do platter, não estimativas
🔁 Skill como jogo infinito
Você nunca termina uma skill — você itera eternamente. Cada uso revela um caso edge. Cada erro é insumo para melhorar o próximo passo. A mentalidade "uma e pronto" é o maior inimigo da qualidade agêntica. Skills são documentos vivos, não código congelado.
🔄 Ciclo de iteração
💡 Versionamento de skills
Skills vivem no filesystem com git. Toda mudança é um commit com mensagem clara: "adiciona verificação de TTL antes de análise". O histórico é o log de aprendizado da operação.
📦 Portabilidade: Claude Code vs Codex vs outros
O conceito de skill é convergente — múltiplas plataformas estão adotando variantes do mesmo padrão. Mas a sintaxe varia. Saber as diferenças permite portar skills entre ambientes sem reescrever tudo do zero.
🔄 Comparativo de plataformas
Claude Code (.claude/skills/)
Arquivos Markdown com frontmatter YAML. Acionados via /nome-da-skill. Suporte a tools, MCP, hooks, contexto hierárquico.
OpenAI Codex / Agents SDK
Instructions declarativas em sistema de agente. Conceito similar, mas sem slash commands nativos — requer orquestração explícita via SDK.
Cursor / Windsurf Rules
Arquivos .cursorrules ou .windsurfrules — regras de comportamento, análogos mas sem exemplos estruturados.
⚠️ Armadilha do vendor lock-in
Skills escritas com sintaxe proprietária demais dificultam portabilidade. Escreva o corpo das instruções em Markdown puro e universal. Só o frontmatter deve ter campos específicos da plataforma.
🧪 Skill ↔ Teste
Skill sem teste regride silenciosamente. Uma mudança na skill para cobrir um caso novo quebra um caso antigo — e você só descobre quando o agente errar em produção. Cada skill deve ter casos-exemplo com saída esperada. Eval automatizado quando possível.
🧪 Estrutura de teste de skill
## Casos de Teste — /analise-campanha ### Caso 1: platter fresco, ROAS saudável Input: marketing_current.md (timestamp hoje, ROAS 3.2x) Output esperado: ✓ Análise menciona ROAS de 3.2x ✓ Sem alerta de ROAS ✓ 3 recomendações presentes ✗ NÃO deve inventar números ### Caso 2: platter velho (> 24h) Input: marketing_current.md (timestamp 48h atrás) Output esperado: ✓ ALERTA de dado desatualizado no início ✓ Análise continua, mas com ressalva explícita ### Caso 3: ROAS abaixo do threshold Input: marketing_current.md (ROAS 1.8x) Output esperado: ✓ ALERTA de ROAS crítico no topo ✓ Recomendações mais urgentes (pausar, revisar)
💡 Eval automatizado
Para skills críticas, crie um script Python que roda a skill com fixtures conhecidas e verifica se as assertions passam. Não precisa ser perfeito — checar as 3-5 assertions mais importantes já captura 80% das regressões.
📋 Resumo do Módulo
Próximo Módulo:
3.4 — MCP — conectando ferramentas e dados