Claude Code Skills: crie seus próprios fluxos de trabalho com IA · Lição 2 de 6

Lição 2: Anatomia de uma Skill: o arquivo SKILL.md

Objetivos de aprendizado:

Entender a estrutura em duas partes do SKILL.md

Conhecer os campos obrigatórios do YAML frontmatter

Aprender a escrever uma description que realmente funciona

Ver como organizar a seção de instruções

Pré-requisitos: << Lição 1 | Próxima: Lição 3 >>

Como é um arquivo de Skill

Abra qualquer Skill e você encontrará o mesmo formato:¹

MARKDOWN

---
name: task-organizer
description: Organiza uma lista de tarefas bagunçada em grupos por prioridade e prazo
---

# Organizador de tarefas

Extraia informação estruturada de uma lista de tarefas desorganizada.

## Formato de entrada

Aceite qualquer um destes:
- Uma lista em texto simples
- Uma checklist em Markdown
- Um log de conversa com carimbos de hora

## Passos

1. Extraia o conteúdo central de cada tarefa
2. Identifique o prazo, se houver
3. Julgue a prioridade (urgente / importante / normal)
4. Ordene por prazo, do mais próximo ao mais distante

## Formato de saída

### 🔴 Urgente (vence hoje ou amanhã)
- [tarefa] - horário de vencimento

### 🟡 Importante (vence esta semana)
- [tarefa] - horário de vencimento

### ⚪ Normal (sem prazo claro, ou mais distante)
- [tarefa]

Este arquivo tem duas partes:

YAML frontmatter (tudo entre os marcadores ---): metadados que informam ao Claude o básico sobre esta Skill
Instruções em Markdown (tudo o que vem depois): as orientações concretas que dizem ao Claude o que fazer

YAML frontmatter: como o Claude encontra sua Skill

O frontmatter é o bloco no topo do arquivo delimitado por ---. Ele informa ao Claude as duas coisas que mais importam:² ³

name: o identificador único da Skill

YAML

name: task-organizer

Regras: letras minúsculas, dígitos e hifens. Sem espaços.
O que ele faz: o nome vira o comando, como /task-organizer
Recomendação: escolha algo descritivo, curto e óbvio à primeira vista

Bons nomes:

meeting-notes
code-review
changelog-generator

Nomes ruins:

my-skill-1 (não diz nada)
super_amazing_task_helper (longo demais, e underscores não são permitidos)
taskOrganizer (camelCase — precisa ser minúsculas com hifens)

description: o campo que mais importa

YAML

description: Organiza uma lista de tarefas bagunçada em grupos por prioridade e prazo

Esta única frase determina três coisas:⁴

Quando o Claude carrega esta Skill por conta própria
O que os usuários veem na lista de Skills
Para que o Claude entende que esta Skill serve

É por isso que ela merece mais cuidado do que qualquer outra coisa no arquivo:⁴

"The description is the single most important field in your frontmatter. A bad description means your skill either never triggers or triggers on everything. The formula: What it does + When to use it + Key capabilities."

Uma boa description:

YAML

description: Organiza uma lista de tarefas bagunçada em grupos por prioridade e prazo. Use em listas de tarefas sem estrutura ou em itens de ação de reuniões

Descriptions ruins:

YAML

description: Ajuda com tarefas  # Vaga demais — o Claude não faz ideia de quando recorrer a ela
description: Um poderoso gerenciador de tarefas com análise inteligente de prioridades  # Texto de marketing; os detalhes úteis vêm por último, se é que vêm

Campos opcionais (tratados na Lição 6, não aqui)

model: escolhe qual modelo usar
allowed-tools: restringe quais ferramentas esta Skill pode acessar
version: um número de versão

Para sua primeira Skill, name e description são tudo de que você precisa.³

Instruções em Markdown: dizendo ao Claude como fazer

Tudo o que vem depois do frontmatter é escrito para o Claude ler e seguir.¹

Boas instruções compartilham três características:

1. Seções claras

Use títulos para separar as partes:

MARKDOWN

## Formato de entrada
(que tipos de entrada aceitar)

## Passos
(detalhe o procedimento, um passo por vez)

## Formato de saída
(com o que o resultado deve parecer)

## Casos de borda
(como lidar com as situações complicadas)

2. Passos concretos

Fraco:

MARKDOWN

1. Analise as tarefas
2. Determine a prioridade
3. Produza o resultado

Forte:

MARKDOWN

1. Leia a lista de tarefas, uma tarefa por linha
2. Extraia palavras-chave de data do texto da tarefa (hoje, amanhã, sexta-feira, 2024-01-15 e assim por diante)
3. Se uma tarefa contiver "urgente", "ASAP" ou "até o fim do dia", marque como prioridade alta
4. Ordene por prazo, do mais próximo ao mais distante
5. Produza três grupos: Urgente, Importante, Normal

3. Exemplos

Se o formato de saída importa, mostre um:

MARKDOWN

## Formato de saída

### 🔴 Urgente
- Finalizar o relatório trimestral - amanhã 17:00
- Corrigir o bug em produção - hoje

### 🟡 Importante
- Revisar o PR #234 - nesta sexta

### ⚪ Normal
- Atualizar a documentação
- Melhorar o desempenho

Assim que o Claude tem um exemplo, ele sabe exatamente como organizar as coisas. Mostrar vence descrever — uma saída de exemplo trabalha mais do que três parágrafos sobre formatação.

Como as duas partes trabalham juntas

O frontmatter é o mecanismo de descoberta; as instruções são o guia de execução.⁵ ⁶

Você digita /task-organizer, ou simplesmente diz “me ajude a organizar estas tarefas”
O Claude lê o name e a description no frontmatter e decide se carrega esta Skill
Se carregar, o Claude lê as instruções completas
O Claude percorre os passos como foram escritos
A saída segue o formato que as instruções especificaram

É por isso que a description precisa ser boa: ela é a única evidência que o Claude tem ao decidir se vai usar esta Skill.⁴

Escreva “ajuda com tarefas” e o Claude não faz ideia de quais situações pedem por ela. Escreva “organiza uma lista de tarefas bagunçada em grupos por prioridade e prazo” e as palavras “organizar”, “lista de tarefas” e “tarefas” em um pedido já bastam para trazê-la.

Um exemplo real: desmontando uma Skill de revisão de código

Aqui está uma Skill que é usada de verdade:

MARKDOWN

---
name: code-review
description: Revisa mudanças de código em busca de violações das convenções do time, prováveis bugs e problemas de desempenho
---

# Assistente de revisão de código

## Checklist de revisão

Percorra cada item abaixo:

### 1. Convenções
- Os nomes de variáveis seguem a convenção do time (camelCase, nomes significativos)?
- Existem funções com mais de 50 linhas (considere dividir)?
- Existe código duplicado (DRY)?

### 2. Prováveis bugs
- Existem erros não tratados (try-catch, valores de retorno de erro)?
- Alguma possível desreferência de null?
- Algum risco de injeção de SQL (se houver banco de dados envolvido)?

### 3. Desempenho
- Alguma consulta N+1?
- Algum laço aninhado desnecessário?
- Algum cálculo repetido que poderia ser colocado em cache?

## Formato de saída

Para cada problema, informe:
- **Local**: nome do arquivo + número da linha
- **Problema**: o que especificamente está errado
- **Sugestão**: como corrigir

Se nada estiver errado, retorne "✓ Revisão de código aprovada"

Destrinchando:

A description no frontmatter: diz o que ela faz (revisa código) e o que ela verifica (convenções, bugs, desempenho)
As instruções divididas em três checklists: convenções, bugs, desempenho, cada uma com itens específicos a observar
O formato de saída é explícito: todo problema precisa trazer um local, um problema e uma sugestão

Uma Skill escrita assim acerta na primeira tentativa.

Recapitulação

O SKILL.md tem duas partes: YAML frontmatter (metadados) e instruções em Markdown (orientações)
Campos obrigatórios do frontmatter: name (minúsculas, hifens, único) e description (o que impulsiona o acionamento automático)
A fórmula da description: o que ela faz + quando usar + principais capacidades
Três características de boas instruções: seções claras, passos concretos, exemplos trabalhados
Como as partes se encaixam: o frontmatter permite que o Claude encontre a Skill; as instruções permitem que o Claude a execute

Na próxima lição, começamos do zero e escrevemos uma Skill completa de ponta a ponta.

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

Documentação oficial do Claude Code: Extend Claude Code with skills — https://code.claude.com/docs/en/skills ↩ ↩²
Blog de engenharia da Anthropic: Equipping agents for the real world with Agent Skills — https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills ↩
Central de ajuda da Anthropic: How to create custom skills — https://support.claude.com/en/articles/12512198-how-to-create-custom-skills ↩ ↩²
Building skills for Claude, na prática: frontmatter YAML e testes — https://sjramblings.io/building-skills-for-claude-part-2/ ↩ ↩² ↩³
Documentação da plataforma da Anthropic: Agent Skills overview — https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview ↩
Claude Skills em profundidade (uma visão a partir dos primeiros princípios) — https://leehanchung.github.io/blogs/2025/10/26/claude-skills-deep-dive/ ↩

Exercícios

O que está errado neste frontmatter e como você corrigiria?

Nível 1: Corrigir um frontmatter quebrado

MARKDOWN

---
name: My Amazing Tool
description: A tool
---

Critérios de conclusão · marcado localmente

Problema com `name` identificado (sem espaços, precisa ser minúsculas, usar hifens)Problema com `description` identificado (vaga demais, não diz o que faz)Proposta de melhoria concreta

Pegue a tarefa que você encontrou no exercício da Lição 1 e escreva um frontmatter para ela.

Nível 2: Escrever um frontmatter para o seu próprio caso

Critérios de conclusão · marcado localmente

`name` segue as regras de nomenclatura (minúsculas, hifens, descritivo)`description` cobre o que faz, quando usar e as principais capacidades`description` cabe em uma frase, com menos de cerca de 200 caracteres

Lição 2: Anatomia de uma Skill: o arquivo SKILL.md

Como é um arquivo de Skill

YAML frontmatter: como o Claude encontra sua Skill

name: o identificador único da Skill

description: o campo que mais importa

Campos opcionais (tratados na Lição 6, não aqui)

Instruções em Markdown: dizendo ao Claude como fazer

1. Seções claras

2. Passos concretos

3. Exemplos

Como as duas partes trabalham juntas

Um exemplo real: desmontando uma Skill de revisão de código

Recapitulação

Footnotes

Exercícios

O que está errado neste frontmatter e como você corrigiria?

Pegue a tarefa que você encontrou no exercício da Lição 1 e escreva um frontmatter para ela.