Skill em inglês ou em português: o idioma do arquivo muda o resultado?

Você baixa uma skill massa da comunidade, abre o arquivo, vê tudo em inglês e pensa: "traduzo isso pro português ou deixo quieto?"

Essa dúvida é mais comum do que parece, e ela tem resposta técnica

Uma skill é um arquivo SKILL.md com frontmatter YAML mais um corpo em markdown, guardado dentro de uma pasta com o nome da skill

Se liga num detalhe importante: o formato não exige idioma nenhum

O inglês que você vê ali é escolha de quem escreveu, não regra da ferramenta

Mas isso não significa que traduzir seja inofensivo, porque nem toda parte do arquivo trabalha do mesmo jeito 🙂

O que o Claude realmente lê de uma skill (e quando lê)

Antes de decidir o idioma, você precisa saber O QUE é lido e QUANDO

O carregamento acontece em dois níveis

No primeiro nível, ao iniciar, entram no system prompt apenas o name e a description de cada skill instalada, a um custo aproximado de 100 tokens por skill

No segundo nível, o SKILL.md completo só é lido quando o agente julga aquela skill relevante para a tarefa

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

A consequência disso é direta e é o coração deste post: a description trabalha o tempo todo, o corpo só entra em cena depois que a skill já foi escolhida

Ou seja, traduzir o corpo mexe na leitura de quem já venceu a seleção

Traduzir a description mexe na PRÓPRIA seleção

Onde essas skills moram no Claude Code:

No Claude Code as skills vivem em dois escopos de pasta

• ~/.claude/skills/ para o escopo pessoal, valendo em todos os projetos
• .claude/skills/ para o escopo de projeto, valendo só naquele repositório

E o acionamento também tem dois caminhos: automático, quando o pedido casa com a description, ou manual, chamando /nome-da-skill direto

Guarda esse segundo caminho, porque ele vira sua rede de segurança lá na frente

O que muda ao traduzir: comparação parte por parte do SKILL.md

Traduzir uma skill não é uma decisão só, são cinco decisões diferentes dentro do mesmo arquivo

Separa por parte e fica óbvio onde tu pode brincar e onde é melhor não encostar

Quando traduzir a skill e quando manter o texto original

Agora a parte prática, dividida em dois grupos

Traduzir compensa quando:

• Você e o time leem o corpo com frequência, porque skill boa é documentação viva e documentação que ninguém lê direito não é seguida direito
• A skill descreve processo interno, tipo padrão de commit, fluxo de review, regra de nomenclatura da empresa: aqui o autor é você, não tem upstream pra brigar
• Os pedidos chegam em português, e nesse caso ter a description no mesmo idioma dos seus pedidos ajuda o match, já que é ela que precisa casar com o fraseado

Essa lógica de "em qual idioma eu falo com o modelo" não é exclusiva das skills, é a mesma discussão de quando você escreve em português com o Claude no dia a dia

Manter o original é mais seguro quando:

• A skill veio de terceiros e você vai receber atualizações: cada git pull vira conflito no arquivo inteiro que tu traduziu
• O corpo é denso em termos técnicos e blocos de código, aquele tipo de arquivo em que quase tudo é comando e nome de flag, com pouquíssima prosa no meio
• O name segue a convenção de gerúndio em inglês, que é justamente a recomendação da documentação

A regra de bolso que resume tudo isso:

name em inglês, description no idioma dos seus pedidos, corpo no idioma de quem mantém

É o mesmo raciocínio que vale pra outros modelos, tipo a dúvida de usar o DeepSeek em português ou escrever tudo em inglês: o idioma é ferramenta, não crença

Traduzi a skill e ela parou de disparar: o que aconteceu

Sintoma clássico: a skill continua instalada, o arquivo está lá bonitinho, mas o Claude simplesmente não aciona ela sozinha depois da tradução

A causa mais citada pra uma skill instalada não disparar é a description não casar com a forma como o usuário faz o pedido

E tradução mal feita costuma quebrar isso de três jeitos:

• a description perdeu o "o que faz" ou o "quando usar" com gatilhos específicos, virando uma frase genérica bonita e inútil
• os termos que você usa no pedido sumiram do texto, então não sobrou nada pra casar
• a terceira pessoa virou segunda pessoa ("você pode usar isso pra…"), justamente o que a documentação de boas práticas manda evitar, porque a description é injetada no system prompt e inconsistência de ponto de vista atrapalha a descoberta

Como consertar, passo a passo:

1. Reescreva a description dizendo o que a skill faz E quando usar, em terceira pessoa, no idioma em que você costuma pedir

---
name: generating-release-notes
description: Gera notas de release a partir dos commits do repositório. Use quando o pedido envolver changelog, notas de versão ou resumo de release
---

O erro comum deste passo: escrever a description olhando pra skill ("skill de release notes") em vez de olhar pro pedido que você faz na prática

2. Faça o diagnóstico invertido: pergunte ao Claude quando ele usaria aquela skill e compare a resposta com o que está escrito na description

Se a resposta dele não bate com o momento em que VOCÊ quer a skill, o problema está no texto, não no idioma

3. Traduza o corpo primeiro e mexa no frontmatter por último

Assim tu isola a variável: se quebrou depois de mexer no frontmatter, você sabe exatamente onde olhar

O erro comum deste passo: traduzir tudo de uma vez e depois não saber o que causou o quê

4. Respeite os limites do formato: 64 caracteres no name (só minúsculas, números e hifens), 1024 caracteres na description, que não pode ser vazia, e nada de tags XML em nenhum dos dois

Tome cuidado! Texto em português costuma ficar mais comprido que o equivalente em inglês, então dá uma olhada no tamanho antes de salvar

5. Enquanto você ajusta, aciona pela barra: /nome-da-skill chama a skill direto, sem depender do match automático

Isso te deixa continuar trabalhando enquanto a description ainda está em obras 😀

Veredito: o idioma do arquivo muda o resultado?

Veredito honesto, sem enrolação

O idioma do CORPO não é o ponto crítico

O suporte multilíngue do Claude é documentado, com performance relativa consistente entre idiomas, inclusive em tarefas zero-shot e em idiomas menos representados

O ponto crítico está em outro lugar: a description precisa casar com o pedido, e o name precisa respeitar as regras do campo

É isso que decide se a skill entra em jogo ou fica dormindo na pasta

E agora a parte que quase ninguém fala: não existe número público comparando taxa de acionamento ou qualidade de execução da mesma skill em inglês e em português

Não tem benchmark, não tem medição publicada, nada

Então quando alguém te garantir "skill em português rende X% menos", pergunta a fonte

Provavelmente é chute embalado com confiança 🙂

A própria documentação oficial de skills não trata do idioma de autoria, e vale a pena ler a referência de skills do Claude Code pra confirmar isso com os próprios olhos

Conclusão

Recapitulando o que ficou de pé:

• só name e description ficam carregados o tempo todo, a cerca de 100 tokens por skill, e o SKILL.md completo entra sob demanda
• a description é o critério de seleção, então ela é a parte que mais sente o idioma
• name tem regra dura: 64 caracteres, só letras minúsculas, números e hifens, sem tags XML e sem palavras reservadas
• blocos de código e termos de API, HTTP e Git ficam intactos, como fazem as skills de tradução da comunidade

Próximo passo prático pra hoje: abre ~/.claude/skills/ e .claude/skills/, lê a description de cada skill instalada e responde uma pergunta simples

Ela diz o que a skill faz e quando usar, no idioma em que você costuma pedir?

Se não diz, achou seu trabalho da semana

Ah, e antes de sair editando: quando você instala pelo /plugin, a instalação te pergunta o escopo (User ou Project)

Vale saber onde a skill traduzida vai morar ANTES de mexer no arquivo, senão tu edita a cópia errada e fica com cara de bobo achando que não funcionou haha

até o próximo post!