🗃️ O problema do skill sprawl
Skill sprawl acontece quando você cria um skill para cada tarefa nova sem pensar no sistema como um todo. Começa com 5 skills razoáveis. Dois meses depois, você tem 20 — e nenhum deles dispara de forma confiável porque o LLM não sabe qual escolher entre opções sobrepostas.
⚠️ O inventário que virou pesadelo
Um caso real: 15 skills que pareciam distintos mas faziam coisas parecidas:
Auditoria (3 skills)
- audit-csv
- audit-excel
- audit-source
Inspeção (2 skills)
- inspect-data
- peek-at-file
Summaries (3 skills)
- build-revenue-summary
- build-customer-summary
- build-utilization-summary
Atualização (3 skills)
- refresh-data
- update-summaries
- rerun-pipeline
Relatórios (3 skills)
- aggregate-monthly
- business-brief
- weekly-report
Snapshot (1 skill)
- snapshot
Resultado: o agente frequentemente disparava o skill errado ou não disparava nenhum. A área de superfície era grande demais.
💡 Dica Prática
Se você tem dois skills com nomes parecidos, as funcionalidades provavelmente se sobrepõem. Consolide. A pergunta não é "quão diferente são?" mas "o LLM consegue distinguir consistentemente?"
📂 Progressive Disclosure
A solução para consolidar sem perder especificidade é progressive disclosure: um único skill com seções internas que cobrem casos distintos. O LLM lê apenas a seção relevante para o contexto, mantendo o skill compacto mas abrangente.
🔄 Antes vs Depois
✗ Antes — 3 skills separados
# audit-csv.md
Use quando analisar CSVs...
# audit-excel.md
Use quando analisar Excel...
# audit-source.md
Use quando inspecionar fonte...
✓ Depois — 1 skill com seções
# audit-source.md
Use para auditar qualquer fonte...
## Quando for CSV:
Verificar delimitador, encoding...
## Quando for Excel:
Verificar sheets, merged cells...
📐 Estrutura ideal de um skill com progressive disclosure
- • Header: Nome único, descrição com múltiplos triggers, lista de casos cobertos
-
•
Seções condicionais:
## Quando X:para cada variação relevante - • Footer: Exemplos de output, casos de borda, o que NÃO fazer
🏷️ Nomes Únicos e Descrições Trigger-Heavy
O nome e a descrição de um skill são o que o LLM usa para decidir se o aciona. Um nome genérico compete com dezenas de outros. Um nome único com descrição rica em triggers dispara com precisão cirúrgica.
✗ Descrição fraca
# analysis.md
Use para fazer análise de dados.
Problema: "análise" pode ser qualquer coisa. O LLM vai ignorar esse skill na maioria dos casos.
✓ Descrição trigger-heavy
# audit-source.md
Use SEMPRE que o usuário pedir para: inspecionar, auditar, verificar, checar, analisar qualidade, revisar, examinar um arquivo de dados (CSV, Excel, JSON, Parquet).
Resultado: disparo confiável em qualquer variação da instrução.
💡 A anatomia de uma boa descrição de skill
- 1.Verbo de ação + contexto: "Use SEMPRE que o usuário pedir para INSPECIONAR..."
- 2.Lista de sinônimos: inspecionar, auditar, verificar, checar, analisar, revisar...
- 3.Tipos de objeto: "...um arquivo de dados (CSV, Excel, JSON, Parquet)"
- 4.Exemplos concretos: "Exemplos: 'me diz o que tem nesse CSV', 'olha essa planilha'"
🔧 Consolidando Skills Sobrepostos
Consolidar não é apenas juntar arquivos. É redesenhar a lógica para que o skill unificado seja melhor que qualquer um dos originais. O processo tem 4 etapas claras.
Inventário e mapeamento
Liste todos os skills. Para cada um, anote: o que faz, quando dispara, que resultado produz.
Coloque side-by-side os que parecem similares. Se 70%+ do comportamento se sobrepõe, são candidatos à consolidação.
Identificar o núcleo comum
O que audit-csv, audit-excel e audit-source têm em comum?
Todos: inspecionam estrutura, checam nulos, verificam tipos, identificam anomalias. Isso vira o corpo principal do skill unificado.
Isolar as diferenças como seções
O que é específico de cada tipo vira uma seção condicional.
CSV tem delimitador e encoding. Excel tem sheets e merged cells. JSON tem nested structures. Cada particularidade fica na sua seção ## Quando for X:
Deletar os originais
Esse é o passo que a maioria evita — e é o mais importante.
Deletar os skills originais força o sistema a usar o novo. Manter ambos garante confusão. A hesitação em deletar é o sinal de que a consolidação não foi completa.
🤖 Testando Skills com Sub-Agentes em Paralelo
Antes de um skill ir para produção, ele precisa ser testado em condições reais. A abordagem mais eficiente é usar sub-agentes em paralelo — múltiplas instâncias com prompts diferentes para mapear o comportamento do skill em todos os cenários.
🧪 Matriz de teste para um skill de auditoria
| Prompt de teste | Deve disparar? | Resultado |
|---|---|---|
| "me diz o que tem nesse CSV" | ✓ Sim | verificar |
| "audita essa planilha" | ✓ Sim | verificar |
| "qual a receita do Q3?" | ✗ Não | verificar |
| "inspeciona o arquivo customers.json" | ✓ Sim | verificar |
| "gera um relatório semanal" | ✗ Não | verificar |
Execute todos os prompts em sessões limpas (cold start). Qualquer resultado inesperado indica que a descrição do skill precisa ser refinada.
⚠️ Atenção: Falsos Positivos São Piores que Falsos Negativos
Um skill que não dispara é apenas ineficiente — você faz a tarefa manualmente. Um skill que dispara quando não deveria pode interromper o fluxo de trabalho, injetar contexto desnecessário e confundir o agente. Priorize eliminar falsos positivos primeiro.
✂️ O Processo Lean-Down Completo
O lean-down não é um evento único — é um processo. O objetivo final: mesma cobertura, um terço da área de superfície. De 15 skills para 5 skills + 3 regras no CLAUDE.md.
O resultado do caso real
Antes — 15 skills
audit-csv, audit-excel, audit-source
inspect-data, peek-at-file
build-revenue-summary
build-customer-summary
build-utilization-summary
aggregate-monthly, refresh-data
update-summaries, rerun-pipeline
business-brief, weekly-report, snapshot
Depois — 5 skills + 3 regras
Skills:
- • audit-source (cobre os 5 de auditoria)
- • build-summary (cobre os 3 de summary)
- • refresh-pipeline (cobre os 3 de update)
- • generate-report (cobre business/weekly)
- • snapshot-state
Regras (CLAUDE.md):
- • Sempre auditar antes de sumarizar
- • Snapshots antes de qualquer refresh
- • Reports incluem timestamp de dados
💡 Quando uma Regra é Melhor que um Skill
Regras no CLAUDE.md são comportamentos que devem acontecer sempre, sem exceção. Skills são comportamentos contextuais. Se a instrução não varia conforme o contexto — use uma regra, não um skill.
- →"Sempre use snake_case em nomes de variáveis" → Regra
- →"Quando auditar dados, siga este checklist" → Skill
✅ Resumo do Módulo
Próximo Módulo:
3.2 — 🌳 Devemos Construir um Sistema? — O framework de decisão para evitar over-engineering