Skill grande demais no Claude Code: o que cortar quando ela virou um manual?

Sua skill parou de funcionar no dia em que ficou completa

É quase sempre a mesma história: ela nasce com dez linhas, resolve bem, aí o modelo erra uma vez e você acrescenta uma regra

Erra de novo, mais uma regra

Seis meses depois aquilo virou um documento que nem você lê inteiro, e a sensação é de que a skill piorou justamente conforme foi ficando "completa"

Este post é um guia de poda com critério, usando o que a documentação oficial de skills realmente diz, sem achismo e sem número inventado 🙂

Por que uma skill inchada rende pior que uma enxuta

Pra entender o corte, primeiro o mecanismo

Skills funcionam por divulgação progressiva (progressive disclosure) em três níveis: no início só o nome e a descrição do frontmatter entram no contexto, o corpo do SKILL.md entra quando a skill é acionada e os arquivos empacotados só são lidos quando alguém referencia eles

Ou seja: o que você escreve no corpo não é de graça, é uma conta que chega na hora do uso

A própria doc explica o motivo do limite como custo de contexto: depois que o Claude carrega o SKILL.md, cada token dele compete com o histórico da conversa e com o resto do contexto

Pré-inscrição Formação Claude Code

Domine o Claude Code do básico ao avançado

Você vai aprender a criar sistemas completos com Claude Code, sem precisar ser programador. Inscreva-se para ter acesso a um desconto de lançamento e bônus especiais!

Quero minha vaga

E qual o problema de competir por espaço?

Aqui entra o efeito que a Anthropic chama de context rot: conforme o número de tokens na janela de contexto cresce, cai a precisão do modelo em recuperar informação daquele contexto

A descrição de boa engenharia de contexto é bem direta: achar o menor conjunto possível de tokens de alto sinal

Junta as duas pontas e o paradoxo some

Encher a skill de regra pra garantir que a regra seja seguida faz o contrário: aumenta o volume e diminui a chance da regra certa ser puxada na hora certa

É como entregar um manual de 300 páginas pra alguém que tem 30 segundos, ao invés de um bilhete com as 5 coisas que ele ainda não sabe

O que você precisa antes de podar a skill

Antes de sair cortando, localize o arquivo certo

No Claude Code as skills podem viver em quatro níveis: enterprise (configurações gerenciadas), pessoal, projeto e plugin

~/.claude/skills/<nome-da-skill>/SKILL.md     (pessoal)
.claude/skills/<nome-da-skill>/SKILL.md       (projeto)
<plugin>/skills/<nome-da-skill>/SKILL.md      (plugin)

Isso importa porque existe precedência quando duas skills têm o MESMO nome: enterprise vence pessoal, pessoal vence projeto e projeto vence plugin

Tome cuidado aqui: dá pra passar uma tarde podando a cópia de projeto enquanto quem está sendo acionada é a pessoal

Skills de plugin usam o namespace nome-do-plugin:nome-da-skill, então essas não conflitam

Outro detalhe fácil de esquecer: se um comando em .claude/commands/ e uma skill em .claude/skills/ têm o mesmo nome, a skill tem precedência

Uma ajuda oficial pra testar antes e depois

A Anthropic mantém um plugin chamado skill-creator, invocado com /skill-creator, com quatro modos: Create, Eval, Improve e Benchmark

O código dele é público, fica no repositório anthropics/claude-plugins-official, na pasta plugins/skill-creator

O valor dele pra poda está nos modos Eval e Benchmark: cortar no escuro é chute, cortar medindo antes e depois é engenharia

Como podar uma skill grande demais, passo a passo

Bora ver na prática?

A sequência abaixo vai do corte grosso pro ajuste fino

1. Meça o corpo do SKILL.md contra as 500 linhas. A documentação oficial de boas práticas recomenda manter o corpo abaixo de 500 linhas e dividir o conteúdo em arquivos separados quando passar disso

Essa é a régua confirmada, e é ela que vale como gatilho de poda

O erro comum deste passo: tratar 500 linhas como meta de preenchimento ao invés de teto

2. Corte tudo que o Claude já domina. A regra de redação oficial é partir do princípio de que ele já é muito capaz e só acrescentar contexto que ele ainda não tem

Aquele parágrafo explicando o que é um pull request, o que é um teste unitário ou como funciona git rebase? Sai

O erro comum deste passo: confundir "explicar o conceito" com "explicar a nossa convenção". A convenção do seu time fica, o conceito genérico vai embora

3. Tire a informação sensível ao tempo. A recomendação é não incluir esse tipo de informação na skill, ou isolar ela numa seção de padrões antigos (old patterns)

O erro comum deste passo: deixar "por enquanto ainda usamos X" solto no meio das instruções. Daqui a três meses isso não é contexto, é ruído

4. Mova o detalhe longo pra arquivos separados. Referência gigante, tabelona de parâmetros e passo a passo raro não precisam estar no corpo

A regra é que as referências fiquem a UM nível de profundidade a partir do SKILL.md

.claude/skills/revisao-de-pr/
  SKILL.md                 <- corpo curto, linka os arquivos abaixo
  referencia-migracoes.md
  checklist-testes.md

O erro comum deste passo: aninhar (o SKILL.md aponta pro arquivo A, que aponta pro arquivo B). Em referências aninhadas o Claude pode ler os arquivos parcialmente, espiando com head -100 por exemplo, e ficar com informação incompleta

5. Revise o frontmatter. Ele exige dois campos: name e description

O name tem limite de 64 caracteres, aceita apenas letras minúsculas, números e hífens, não aceita tags XML e não pode usar as palavras reservadas anthropic e claude

A description tem limite de 1024 caracteres, não pode ficar vazia nem conter tags XML, e deve dizer o que a skill faz E quando usar

---
name: revisao-de-pr
description: Revisa pull requests deste projeto conferindo estilo, cobertura de testes e migrações de banco. Use quando o pedido mencionar PR, diff, review ou merge.
---

O erro comum deste passo: descrição que só diz o que a skill faz e esquece o quando. É por isso que ela não é acionada na hora certa

6. Troque exemplo abstrato por concreto e uniformize a terminologia. Exemplo concreto é item do checklist oficial de qualidade, e terminologia consistente também

Se metade da skill fala "componente" e a outra metade fala "módulo" pra mesma coisa, você está pagando tokens pra criar ambiguidade

O erro comum deste passo: manter os dois termos "pra ficar claro". Não fica, escolhe um

7. Ajuste os graus de liberdade ao risco da tarefa. A doc orienta usar instruções em texto (alta liberdade) quando várias abordagens são válidas e a decisão depende do contexto

E usar scripts específicos (baixa liberdade) quando a operação é frágil, propensa a erro e exige sequência exata

O erro comum deste passo: descrever em prosa, com dez ressalvas, um procedimento que só funciona numa ordem. Isso não é instrução, é um script mal escrito em português 😀

O que sai primeiro: os tipos de conteúdo que engordam a skill à toa

Na hora da poda a pergunta pra cada bloco é sempre a mesma: corto, movo ou reescrevo?

Repara no destino de cada linha: o que mais aparece é REESCREVER, não deletar

Exemplo abstrato, sinônimo solto, passo frágil em prosa e referência aninhada continuam na skill, só que numa forma mais curta e mais direta

Corte puro mesmo é pra explicação de conceito que o modelo já domina, e a informação sensível ao tempo fica no meio do caminho: ou sai, ou vai pra seção de padrões antigos

E tem um caso, o mais pesado deles, que não é corte nem reescrita: a referência longa sai do corpo e vira arquivo separado, lido só quando referenciado, que é exatamente o terceiro nível da divulgação progressiva

Sinais de que a skill virou manual (e o que fazer em cada caso)

Sintoma: a skill não é acionada na hora certa

Causa provável: a description está genérica, sem os termos-chave que aparecem no pedido do usuário, ou estourando os 1024 caracteres

Correção: reescrever dizendo o que ela faz E quando usar, com termos específicos do seu contexto

Sintoma: a skill é acionada, mas metade das regras é ignorada

Causa provável: corpo grande demais, e aí entra o context rot (mais tokens, menor precisão de recuperação)

Correção: cortar o que ele já domina e empacotar o detalhe longo em arquivos separados

Sintoma: o Claude usa a informação pela metade, com dados que não batem

Causa provável: referência aninhada, lida parcialmente

Correção: achatar tudo pra um nível de profundidade a partir do SKILL.md

Sintoma: a operação frágil dá errado de um jeito diferente a cada vez

Causa provável: grau de liberdade errado, instrução vaga onde a sequência precisa ser exata

Correção: virar script

Sintoma: você edita a skill e nada muda no comportamento

Causa provável: duas skills com o mesmo nome, e a que está valendo é outra

Correção: conferir a precedência (enterprise > pessoal > projeto > plugin) e lembrar que skill vence comando de mesmo nome

E como evitar chegar nesse ponto de novo?

A prevenção é chata e funciona: a cada regra nova que você acrescenta, olhe o tamanho do corpo em vez de deixar acumular por um ano

Regra nova quase sempre pede regra velha saindo, e faz parte do trabalho decidir quando revisar e aposentar uma skill ao invés de só empilhar

Checklist final antes de publicar a skill podada

Existe um checklist oficial de qualidade antes de compartilhar uma skill, com oito itens

Use ele como conferência rápida no fim da poda:

1. A descrição é específica e tem os termos-chave?
2. O corpo do SKILL.md está abaixo de 500 linhas?
3. Os detalhes extras estão em arquivos separados?
4. Não sobrou nenhuma informação sensível ao tempo?
5. A terminologia está consistente do começo ao fim?
6. Os exemplos são concretos em vez de abstratos?
7. As referências estão a um nível de profundidade?
8. A divulgação progressiva está sendo usada de forma adequada?

E o caminho contrário, juntar várias skills numa maior?

Acontece também, principalmente quando você tem várias skills feitas para se combinar e bate a vontade de fundir tudo numa só

A orientação oficial pra consolidar skills estreitas em uma maior é decidir por avaliações (evals): só junte quando os evals da skill unificada confirmarem desempenho equivalente ao das skills que ela substitui

É aqui que os modos Eval e Benchmark do /skill-creator fazem o trabalho, do mesmo jeito que fazem na poda

Sem eval, fusão é fé 🙂

Conclusão

Skill não é manual

Skill é o menor conjunto de tokens de alto sinal que o Claude ainda não tem, entregue no nível certo: metadados no startup, corpo ao ativar, arquivo extra sob demanda

Tudo que foge disso está competindo com o histórico da conversa e cobrando o preço em precisão

Próximo passo prático, hoje mesmo: abre a sua skill mais antiga, mede o corpo contra as 500 linhas, roda o checklist de oito itens e valida a versão podada com os modos Eval e Benchmark do /skill-creator antes de adotar de vez

Aposto que a versão podada resolve o que a versão completa não estava resolvendo…

até o próximo post!