Gancho

Seus Skills de IA estão rodando. Os resultados aparecem. Mas você já reparou? Você estoura seus limites de tokens rapidinho e acaba travado por causa do "rate limit" do Claude Code.

Imagine: um skill que roda com frequência e desperdiça 200 mil tokens a cada execução. Com a janela deslizante de 5 horas no plano Pro, você satura em 3-4 execuções. Travado, esperando 5 horas.

A auditoria de tokens é a ferramenta para você não bater nesse teto tão rápido — e continuar construindo sem esperar o reset.

1. O que é um token, de verdade?

Um token = um pedacinho de informação que o modelo de IA precisa processar.

• Olá = 1 token
• Uma frase média = 10-15 tokens
• Uma página de documentação = 500-1.500 tokens
• Um banco de dados inteiro = milhões

O custo é duplo: - Input (o que você entrega ao modelo) = 1 crédito - Output (o que o modelo gera) = 5 créditos

Então, se um skill lê 100 mil tokens e gera 20 mil, o custo real = 100.000 + (20.000 × 5) = 200.000 unidades.

2. As armadilhas: por que você satura seus limites rapidinho

Armadilha 1: ler muito para usar pouco

Cenário real: você tem 500 fichas de clientes. Seu skill precisa analisar 3. Mas, sem filtro, ele lê as 500.

• Impacto: +150 mil tokens de input inúteis por execução
• Risco: você estoura seu limite em 5 horas (em vez de 8), travado até o reset
• Solução: consultar o banco de forma inteligente, não em bloco

Armadilha 2: fazer na mão o que o Python poderia fazer

Cenário real: o modelo de IA transforma JSON em CSV. Ele gera texto. O Python teria feito isso em 1 ms.

• Impacto: +40 mil tokens de output desperdiçados (custam 5× mais)
• Risco: 200 mil tokens extras por execução
• Solução: delegar ao código o que não precisa de raciocínio

Armadilha 3: reler e reescrever a cada execução

Cenário real: na terça, você gera uma ficha de análise de um dos seus concorrentes. Na sexta, chega um documento novo. Você relê TODAS as 500 análises anteriores para regerar a ficha.

• Impacto: +200 mil tokens de input a cada atualização (em vez de 5 mil, só para a análise nova)
• Risco: você dobra seu consumo à toa
• Solução: modo incremental — processar só os dados novos

Armadilha 4: inchar o contexto de sistema

Cenário real: o "prompt" do skill (instruções, templates, exemplos) passa de 5 KB para 25 KB. São 5 mil tokens de contexto fixo a cada chamada.

• Impacto: +5 mil tokens de input × 100 execuções = 500 mil tokens/mês perdidos
• Risco: cota saturada mais rápido a cada mudança no skill
• Solução: externalizar os templates pesados e carregá-los sob demanda

Armadilha 5: usar um modelo superpotente para uma tarefa simples

Cenário real: você usa o Opus 4.6 para extrair números de uma lista. O Haiku teria bastado.

• Impacto: consumo 2-3× maior para o mesmo resultado
• Risco: cota saturada à toa
• Solução: adaptar o modelo à complexidade real

3. Os riscos de não auditar

📊 Risco de cota

• Um skill caro × algumas execuções = saturado em 5 horas
• Sem auditoria, você não sabe onde cortar — então para de trabalhar
• Você perde tempo esperando o reset da janela deslizante

⏱️ Risco de produtividade

• Skills pesados → você bate no rate limit a cada 5 horas
• Você não consegue mais testar, iterar, experimentar com fluidez
• Você fica travado no meio do projeto, esperando o reset

🚀 Risco de escalabilidade

• Enquanto você está sozinho, tudo bem. Mas e se outras pessoas entrarem e dividirem o limite?
• Conflito na cota compartilhada → todo mundo trava um ao outro

⚙️ Risco operacional

• Você faz o deploy de um skill novo sem medir o impacto na sua cota
• Você não sabe por que ficou travado na vez seguinte

4. Como funciona: auditar em 3 fases

O que é um auditor? É um script automatizado que analisa seu skill como um inspetor examinando uma casa: ele olha cada etapa ("você lê este arquivo? quantos tokens?"), faz a conta e diz onde você está desperdiçando.

Fase 1: mapear

O skill escaneia todas as etapas do seu workflow: - Quais arquivos são lidos? - Quais cálculos são feitos? - O que é gerado?

Fase 2: medir

Para cada etapa, ele estima os tokens consumidos: - Arquivos reais no projeto → medição com wc para mais precisão - Sem dados reais? → estimativa conservadora - Acúmulo de contexto → contabilizado (muitas vezes 15-40% do custo)

Fase 3: recomendar

O skill identifica as etapas caras > 15% do total e propõe otimizações:

Cada otimização é quantificada: "esta ação economiza 45 mil tokens = -8% do custo total".

5. Exemplo real: competitor_analyze

Nosso skill competitor_analyze faz o monitoramento da concorrência.

Estado atual: - 478 mil tokens consumidos por execução - Modelo exigido: Opus 4.6 (pesado) - Frequência: ~2-3 vezes por semana em período ativo - Impacto na cota: pesa bastante na cota de sessões, e você acaba travado mais rápido no "rate limit" da janela deslizante de 5 horas

Para onde vão os tokens? (veja o gráfico abaixo)

Otimizações propostas: 1. Ler as análises de forma incremental → -14% (economia: 67 mil tokens) 2. Modo incremental para os temas → -10% (economia: 48 mil tokens) 3. Externalizar os templates do SKILL → -4% (economia: 19 mil tokens)

Impacto: - Tokens consumidos (otimizado): 271.000 (-43%) - Ganho por execução: 207 mil tokens economizados - Resultado: em vez de saturar em 5-6 execuções, você pode disparar 8-10 na janela de 5 horas - Na prática: você sai de "travado em 2 execuções" para "liberado com 3-4 execuções a mais"

6. Plano de ação para o seu time (ou para você, se estiver sozinho)

Passo 1: quais skills auditar?

• Liste todos os seus skills em produção
• Classifique por frequência de uso: "aquele que a gente dispara 10 vezes por semana precisa ser eficiente"
• Comece pelo top 3 dos skills mais frequentes

Passo 2: rodar a auditoria

/token_audit <nome_do_skill>

→ Relatório gerado automaticamente, esforço zero

Passo 3: ler o relatório

Você pode ler direto: - Tabela Resumo: tokens consumidos, etapa mais cara, modelo recomendado - Tabela Otimizações: o que mudar, ganho estimado, complexidade

Passo 4: decidir o que otimizar

Regra simples: - Ganho > 100 mil tokens E complexidade baixa? → Fazer agora - Ganho > 50 mil tokens E complexidade média? → Planejar para quando tiver tempo - Ganho < 50 mil tokens? → Ignorar, não tem ROI

Passo 5: implementar e validar

• Implementar a otimização
• Rodar a auditoria de novo algumas semanas depois para confirmar os ganhos

PS: você também pode criar um Skill "Arquiteto de software" (a gente fala disso outra hora) que vai usar esse relatório de auditoria e outros elementos para propor um plano de otimização avançado.

Frequência recomendada (realista para uma pessoa)

• Quando você lança um skill novo: auditoria assim que fizer o deploy
• Quando sua cota satura rápido demais: auditoria dos suspeitos
• A cada trimestre: auditoria do skill mais pesado (para acompanhar o crescimento dos dados)

7. ROI: por que vale a pena

Investimento

• Tempo: algumas horas para auditar seus 3-5 skills maiores
• Ferramentas: gratuito (integrado ao Claude Code)
• Implementação: depende das otimizações escolhidas (1-20 dias, conforme a complexidade)

Retorno

• Curto prazo (poucos dias): -20% a -40% nos 3 skills prioritários = liberar 3-5 execuções por janela de 5h
• Médio prazo (1-3 meses): portfólio completo otimizado = sair de "travado depois de 2-3 execuções" para "5-6 execuções livres"
• Longo prazo: você pode experimentar, testar, iterar sem bater no rate limit a cada 5 horas

Exemplo concreto: - Você tem 3 skills pesados em produção - Consumo inicial: saturado depois de 2 execuções na janela de 5h - Depois das auditorias e otimizações: -40% de consumo - Resultado: em vez de travar, você tem 3-4 execuções a mais = produtividade de volta - Tempo investido: 1-2 dias para as auditorias + 5-10 dias para as otimizações prioritárias - ROI: você pode trabalhar com fluidez em vez de ficar gerenciando bloqueios constantes

8. Os anexos deste artigo

1. Anexo A: como usar o skill /token_audit

→ spec_token_audit.md

Tudo o que você precisa saber para: - Instalar o skill no seu projeto - Usá-lo (mesmo sem saber programar) - Interpretar o relatório gerado - Conhecer os limites (mede só o uso estático, não a telemetria real de execução)

2. Anexo B: caso concreto — auditoria do skill competitor_analyze

→ token_audit_competitor_analyze.md

Ler o relatório real para ver: - Tabela de custos detalhada por etapa - Onde os tokens são "desperdiçados" - 5 otimizações propostas com ganho quantificado - Comparação antes/depois

⚠️ Os limites do auditor (bom saber)

A auditoria de tokens é poderosa, mas tem fronteiras importantes. Ser honesto sobre isso é o que faz você usar a ferramenta do jeito certo.

1. É uma análise estática, não real

A auditoria lê seu código (SKILL.md, arquivos referenciados) e estima os tokens consumidos. Ela não roda o skill de verdade.

Implicação: - As estimativas costumam ficar perto da realidade (±15%), mas não são exatas - Se seu skill tem um loop condicional ("processar as análises só se forem de menos de 7 dias"), a auditoria considera o pior caso (processar tudo) - Os volumes reais dependem dos dados do dia → variáveis

Quando isso vira um problema: - Um skill com muitos ramos condicionais → a auditoria pode superestimar - Um skill que faz chamadas de API externas (WebFetch) → o volume real depende do tamanho das páginas

2. Sem telemetria real de execução

A auditoria não tem acesso às métricas de execução real (quantos tokens a última execução custou de verdade?).

Implicação: - Você só tem estimativas, não medições certificadas - Impossível validar uma otimização com certeza antes/depois sem instrumentar o código

Quando isso vira um problema: - Se você precisa de uma validação financeira precisa → você tem que instrumentar seu código (adicionar logging de custos reais) - Se um skill passa de 1M unidades → as diferenças ficam significativas em euros

3. A taxa de conversão tokens → euros é estimada

A auditoria estima "output = 5× o custo do input" (regra do Claude). Isso vale só na média.

Realidade com nuances: - É exato para o Sonnet 4.6 e o Opus 4.6 - Mas os preços mudam (novos modelos, mudanças de pricing) - E seus contratos com clientes podem ter tarifas diferentes

4. Não melhora as escolhas de "negócio" do skill

A auditoria pode dizer "você lê 140 análises, poderia ler 50 e fazer incremental".

Mas: "vale mesmo a pena fazer modo incremental?" Isso é uma decisão de negócio, não técnica.

Exemplo: um skill que revalida TODOS os concorrentes todo mês (não incremental) é uma escolha. A auditoria sinaliza isso, mas a resposta "é mais seguro assim" pode ser válida.

5. A complexidade real pode ser subestimada

A auditoria classifica as otimizações por complexidade (baixa / média / alta), mas: - Uma otimização "baixa" segundo a auditoria pode ser "alta" no seu codebase (código velho, dependências) - As estimativas supõem código limpo e modular

Resumo dos limites:

Conclusão sobre os limites:

A auditoria é uma ferramenta de iluminação, não uma máquina de previsão. As estimativas dela são boas o bastante para priorizar, mas não suficientes para dizer "vai custar exatamente X€".

Use a auditoria: - ✅ Para identificar os vazamentos óbvios (> 100k tokens) - ✅ Para priorizar as otimizações (ganho ÷ esforço) - ✅ Para justificar mudanças de arquitetura - ❌ Para orçamentos de custo no centavo - ❌ Para validar resultados (aí precisa de logging real)

Conclusão

Auditar seus skills é sair do "por que estou travado a cada 5 horas?" para o "eu sei onde cortar".

É o equivalente a uma auditoria energética da sua cota: você descobre onde estão os vazamentos, tampa cada um deles e, de repente, tem 5-6 execuções tranquilas em vez de 2-3 antes de travar.

3 pontos para guardar: 1. Os tokens que a gente desperdiça se acumulam rápido e travam você a cada 5 horas 2. Sem auditoria, o desperdício é invisível — você simplesmente para de conseguir trabalhar 3. As otimizações são simples e o impacto é imediato (janelas produtivas mais longas)

Pronto para começar? Dispare uma auditoria do seu skill mais frequente. Você vai ter um relatório em 5 minutos. Os ganhos vêm depois.

Perguntas frequentes

P: A auditoria deixa meus skills mais lentos? R: Não. A auditoria é uma análise estática (ela lê seu código), não uma execução real.

P: E se eu só tiver skills pequenos? R: Auditar skills pequenos (< 1.500 tokens) não compensa. Foque nos seus 3-5 maiores consumidores.

P: Dá para auditar os skills dos concorrentes? R: Impossível (você não tem acesso ao código deles). A auditoria só faz sentido para os seus próprios skills.

P: E se um skill passar de 500 mil tokens por execução? R: É um sinal de alerta. Auditoria prioritária. Muitas vezes dá para economizar 40-50%.

P: Quanto custa uma auditoria? R: Zero (é gratuita, integrada ao Claude Code). Implementar as otimizações leva de 1 a 20 dias, conforme a complexidade.

P: Vale a pena se eu estiver sozinho? R: Vale, e ainda mais! Você é diretamente afetado pela cota. Um skill otimizado = 2-3 semanas de trabalho em vez de 1.