Lição 3: Mão na massa: escrevendo sua primeira Skill

Objetivos de aprendizado:

• Criar a estrutura de diretórios de uma Skill
• Escrever um SKILL.md completo do zero
• Entender o princípio da revelação progressiva (progressive disclosure)
• Invocar sua Skill pela primeira vez

Pré-requisitos: << Lição 2 | Próxima: Lição 4 >>

O que vamos construir

Nesta lição vamos construir do zero uma Skill real e utilizável: um organizador de tarefas.

O que ela faz:

• Entrada: um monte de tarefas bagunçadas (texto solto, texto extraído de uma captura de tela, anotações de reunião)
• Saída: uma lista organizada, agrupada por prioridade e prazo

Por que esta:

• É simples — nenhuma lógica complicada atrapalhando
• É útil — você pode começar a usar hoje
• Ela exercita todas as partes centrais da estrutura de uma Skill

Passo 1: criar o diretório e o arquivo

Abra um terminal e execute:

Sua estrutura de diretórios agora está assim:

~/.claude/skills/└── task-organizer/    └── SKILL.md

Abra o SKILL.md no editor de texto de sua preferência (VS Code, Cursor, o que você usar).

Passo 2: escrever o frontmatter

Comece pelos metadados no topo do arquivo: ¹

Checklist:

• ✓ name está em minúsculas e com hifens
• ✓ description cobre o que ela faz (organiza tarefas), o que recebe (uma lista bagunçada) e quando recorrer a ela (itens de ação de reuniões, backlogs de projeto)

Passo 3: escrever o título e a introdução

Depois do frontmatter, adicione um título:

Por que se dar ao trabalho de escrever título e introdução:

• O título é para humanos — volte a este arquivo daqui a três meses e você lembrará para que ele serve num relance
• A introdução é para o Claude — ela preenche os detalhes que não couberam na description

Passo 4: definir o formato de entrada

Diga ao Claude que tipo de entrada aceitar: ²

O que esta seção realiza:

• Ela enumera todos os formatos de entrada que a Skill pode encontrar
• Ela dá um exemplo concreto, para que o Claude saiba como é uma entrada real

Passo 5: escrever os passos de processamento

Este é o coração das instruções, e precisa ser específico: ²

Por que tanto detalhe:

O Claude não é uma pessoa e não vai “entender o que você quis dizer”. Escreva “atribua uma prioridade” e ele não faz ideia de qual critério aplicar. Escreva “contém 'urgente' → Urgente” e não sobra nada para adivinhar. ³

Passo 6: definir o formato de saída

Diga ao Claude com o que o resultado deve parecer:

O que o exemplo garante para você:

Uma vez que o Claude viu um exemplo, o layout, os símbolos e a formatação estão resolvidos. Nada de adivinhar onde vai o emoji ou se o horário vem antes ou depois da tarefa.

Passo 7: lidar com os casos de borda

Explicite como tratar os casos estranhos:

O arquivo completo

Seu SKILL.md agora deve estar assim:

Salve o arquivo.

Passo 8: sua primeira invocação

Abra o Claude Code e digite:

/task-organizer
Finalizar o relatório trimestralRevisar o PR #234, até sextaCorrigir o bug de login amanhãAtualizar a documentaçãoUrgente: problema de pagamento relatado por um cliente

O Claude deve devolver:

### 🔴 Urgente- Corrigir o bug de login - amanhã- Problema de pagamento relatado por um cliente - sem prazo
### 🟡 Importante- Revisar o PR #234 - sexta
### ⚪ Normal- Finalizar o relatório trimestral - sem prazo- Atualizar a documentação - sem prazo

Se a saída não estiver certa, não se desespere. A próxima lição é inteiramente sobre depuração.

Revelação progressiva: por que você não escreve todos os detalhes de cara

Você deve ter notado que esta Skill não diz nada sobre tarefas que dependem de outras tarefas, nem sobre tarefas atribuídas a pessoas diferentes. ^{3 2}

Isso é de propósito.

Revelação progressiva: dê ao Claude apenas o que ele precisa agora, em vez de despejar tudo de uma vez. ³

A primeira versão faz o trabalho central e nada mais — extrair, classificar, ordenar. Use por alguns dias e, se você perceber que realmente precisa de atribuição de tarefas, adicione naquele momento.

O que você ganha com isso:

• Um arquivo de Skill curto: menos contexto consumido, carregamento mais rápido
• Lógica simples: menos formas de dar errado
• Confirmação rápida de que o comportamento central de fato funciona

Coloque a versão um para rodar e então itere. É assim que toda boa Skill é construída. ³

Recapitulação

• Os 7 passos para construir uma Skill: diretório → frontmatter → título → entrada → passos → saída → casos de borda
• Os passos precisam ser específicos: não “analise as tarefas”, mas “procure palavras de data: hoje, amanhã…”
• Exemplos importam: mostre ao Claude como a entrada e a saída realmente se parecem
• Revelação progressiva: a versão um faz só o trabalho central — não escreva todos os detalhes de cara
• Como invocar: /skill-name seguido da sua entrada

Na próxima lição tratamos de testar e depurar Skills — indo de “funciona” para “funciona corretamente”.

>> Lição 4: Testando e depurando