Claude Skills do 0 ao 100: o que são e como criar a tua

Explicas ao Claude a tua forma de redigir um relatório. Funciona lindamente. Amanhã abres outro chat e tens de lhe explicar outra vez. E no dia seguinte, igual. Esse ciclo é exatamente o que as skills vêm quebrar: empacotas um processo uma vez e o Claude usa-o quando calha, sem que tu voltes a explicá-lo.

Este guia vai do zero a ter a tua primeira skill a funcionar: o que é, como o Claude decide usá-la, como criar a tua passo a passo e os erros que a deixam morta antes de começar.

O que é uma skill (e o que não é)

Uma skill é uma pasta com um ficheiro chamado SKILL.md lá dentro. Esse ficheiro contém instruções em linguagem natural para uma tarefa concreta: como escreves os teus emails, como montas um relatório, que regras segues ao rever código. Opcionalmente pode levar mais coisas —modelos, documentos de referência, scripts— mas o coração é sempre o SKILL.md.

A diferença face ao que já conheces:

• Um prompt és tu que o colas de cada vez. Trabalho manual, repetido.
• Um CLAUDE.md é contexto fixo de um projeto: lê-se ao arrancar a sessão nessa pasta.
• Uma skill é modular e por tema. O Claude tem várias e escolhe a que aplica conforme o que lhe pedes. Serve em qualquer projeto, não só num.

Se tens um processo que repetes em sítios diferentes, isso é uma skill.

Como o Claude lê as skills: os três níveis

Aqui está a chave técnica que explica tudo o resto. O Claude não carrega as tuas skills inteiras de uma vez —isso gastaria contexto sem sentido—. Lê-as em três níveis, o chamado progressive disclosure:

1. Frontmatter (sempre carregado). Apenas o name e a description de cada skill. É a "etiqueta" que o Claude tem sempre à vista para saber o que há disponível.
2. SKILL.md completo (carrega-se se aplica). Quando o teu pedido encaixa com a description, o Claude abre o corpo do ficheiro e lê as instruções.
3. Ficheiros extra (a pedido). Pastas como references/, scripts/ ou assets/ só se tocam se a tarefa as precisar.

A consequência prática é enorme: todo o peso de a tua skill se ativar ou não recai na description, porque é a única coisa que o Claude vê antes de decidir. Se a description não lhe disser claramente quando usá-la, nem se dá ao trabalho de abrir o resto.

O frontmatter: name e description

O frontmatter são as duas linhas que vão no início do SKILL.md, entre ---. Mínimas mas decisivas.

name — o identificador, em kebab-case (minúsculas e hífens). Regras que não se saltam:

• Minúsculas, palavras separadas por hífens: revisor-de-emails, não Revisor_Emails.
• Sem a palavra "claude" nem "anthropic" lá dentro.
• Sem etiquetas nem caracteres estranhos.

description — a frase que decide a tua vida. Tem de dizer duas coisas: O QUE faz a skill e QUANDO usá-la, com frases que se pareçam com a forma como tu pedes as coisas. Tens até cerca de 1024 caracteres; não os desperdices em marketing, gasta-os em gatilhos concretos.

# ❌ FRACA — o Claude não sabe quando ativá-la
---
name: emails
description: Ajuda com os correios eletrónicos.
---

# ✅ BOA — diz O QUE + QUANDO com gatilhos reais
---
name: revisor-de-emails-blackdark
description: >
Revê e reescreve emails com a voz da Blackdark: direto, sem enchimento,
com assunto claro e uma só chamada à ação. Usa-a quando o utilizador
pedir "revê este email", "melhora este correio", "reescreve esta mensagem
para soar melhor" ou colar um rascunho de email para enviar.
---

Repara na versão boa: inclui as frases literais com que pedirias a tarefa ("revê este email", "melhora este correio"). É isso que engancha. Uma description vaga é a causa número um de uma skill nunca saltar.

Cria a tua primeira skill, passo a passo

Vamos montar uma skill a sério. Dois caminhos.

Caminho A — deixar que o Claude ta gere. Descreves-lhe o caso em linguagem natural ("quero uma skill que reveja os meus emails com tom direto, assunto claro e uma só CTA") e ele escreve-te o SKILL.md. Rápido para começar; depois afinas a description à mão.

Caminho B — à mão. É mais controlo e percebes melhor o que se passa. Estrutura recomendada do corpo:

---
name: revisor-de-emails-blackdark
description: >
Revê e reescreve emails com a voz da Blackdark: direto, sem enchimento,
assunto claro e uma só chamada à ação. Usa-a quando o utilizador pedir
"revê este email", "melhora este correio" ou colar um rascunho para enviar.
---

# Revisor de emails Blackdark

## Instruções
- Tom direto e prático. Fora o enchimento, fora o "espero que estejas bem".
- Assunto claro com menos de 50 caracteres.
- Uma só chamada à ação, no fim, inequívoca.
- Respeita o idioma do rascunho original.

## Passos
1. Lê o rascunho e deteta o objetivo real do email.
2. Reescreve: assunto + corpo, no máximo 120 palavras salvo se pedirem mais.
3. Assinala numa linha à parte o que mudaste e porquê.

## Exemplo
Entrada: "Olá, queria ver se se calhar poderíamos talvez agendar uma chamada
quando puderes para falar do projeto, obrigado."
Saída:
Assunto: Chamada de 20 min esta semana
Corpo: Serve-te uma chamada de 20 min na quinta às 11:00 para fechar o
projeto? Se não, diz-me dois horários e eu adapto-me.

## Erros a evitar
- Não inventes dados que não estejam no rascunho.
- Não acrescentes mais do que uma CTA ainda que o original tenha várias intenções.

Agora coloca-a onde o Claude a leia:

• No Claude Code: cria a pasta ~/.claude/skills/revisor-de-emails-blackdark/ e mete lá dentro o SKILL.md. Reinicia a sessão e está feito.
• No claude.ai: comprime a pasta num .zip e carrega-a a partir do painel de skills; depois ativa-a com o seu interruptor.

O nome da pasta e o name do frontmatter devem coincidir, e o ficheiro deve chamar-se exatamente SKILL.md, em maiúsculas.

Como testá-la (em duas frentes)

Não dês uma skill por boa até testares as duas coisas que podem falhar em separado:

1. Ativa-se sozinha? Pede-lhe a tarefa com as tuas palavras reais —sem copiar a description— e vê se o Claude a usa sem lho dizeres. Testa três ou quatro variantes de como o pedirias de verdade. Se não salta, o problema está na description.
2. O resultado é correto? Uma vez ativada, comprova que o output respeita as regras (formato, tom, limites). Se se ativa mas ignora instruções, costuma ser que o importante está enterrado no fim ou escrito de forma ambígua.

Erros comuns (e como resolvê-los)

As falhas são quase sempre as mesmas cinco:

• Nunca se ativa → description vaga, sem "quando". Reescreve-a com frases gatilho concretas, as que tu usarias ao pedir a tarefa.
• Ativa-se a mais, metendo-se onde não a chamam → description demasiado ampla. Delimita o domínio e diz explicitamente que casos NÃO cobre.
• Não a reconhece ao carregá-la → o ficheiro não se chama SKILL.md exato, ou o name não está em kebab-case, ou não coincide com a pasta.
• Ativa-se mas não segue as regras → o crítico está enterrado. Sobe as regras importantes para o topo e dá-lhes formato claro (listas, negritos).
• Vai lenta ou gasta muito → o SKILL.md é um calhamaço. Deixa lá o essencial e move o detalhe longo para ficheiros em references/ que se carreguem só quando forem precisos.

Uma skill bem feita é curta no SKILL.md, brutal na description e honesta sobre quando NÃO se usar. Começa por uma só, a do processo que mais repetes, e afina-a até que dispare sozinha. Quando vires o Claude fazer a tua tarefa sem que lho expliques, já apanhaste o jeito.