🧬 Anatomia de uma Skill

Uma Agent Skill é, na essência, um arquivo de texto Markdown chamado SKILL.md. Nada de binário compilado, nada de instalação complexa: é um documento que você consegue abrir num editor de texto e ler de cima a baixo. O que o torna especial não é a tecnologia, e sim o contrato que ele estabelece — ele ensina o Claude a executar uma tarefa específica, e diz quando essa tarefa se aplica.

---
name: travel-itinerary
description: Generates an interactive HTML travel itinerary.
  Use when the user wants to "plan a trip", "create an itinerary",
  or types /travel.
---

# TravelWings — AI Travel Itinerary Generator

## Setup Flow
Before generating anything, ask the user the trip basics...

## Output Format
Generate a single self-contained HTML file...

O name é o identificador da skill. Parece o campo mais bobo do arquivo, mas ele é a chave estável pela qual a skill é referenciada — em comandos, em outras skills, em logs. Um bom name é curto, em kebab-case, e diz o que a skill é num relance.

Se o name é a identidade, a description é o cérebro da descoberta. É a única parte da skill que o Claude lê quando decide se deve ou não usá-la. Por isso, ela não pode ser uma simples definição — precisa dizer o que a skill faz E quando ela deve ser usada. Esse módulo só apresenta a ideia; o Módulo 1.3 inteiro é dedicado a escrever descriptions afiadas.

Abaixo do frontmatter vem o corpo da skill — Markdown livre onde você escreve o passo a passo da execução. É aqui que a qualidade do resultado é decidida. Um corpo bem estruturado costuma ter quatro blocos recorrentes, como vemos nas skills reais que o curso disseca.

Aqui mora o detalhe que muda tudo: o Claude não lê o corpo de todas as skills o tempo todo. Imagine 50 skills instaladas, cada uma com centenas de linhas — carregar tudo a cada mensagem seria impraticável. Em vez disso, ele mantém um índice leve: só o name + a description de cada skill. É contra esse índice que o pedido do usuário é comparado.

travel-itinerary    → "plan a trip, create an itinerary, /travel"
vibe-coding         → "fix CSS/layout live in the browser before editing"
n8n-reviewer        → "review an n8n automation as a senior engineer"
rag-architect       → "design the right RAG before writing code"
...                 → (só name + description, nunca o corpo inteiro)

Descobrir é reconhecer que a skill se aplica; disparar é efetivamente carregar o corpo e passar a seguir suas instruções. Há dois caminhos para isso acontecer, e entender a diferença evita muita confusão.

🧰 Prompts copiáveis

Use estes prompts com o Claude para fixar o conteúdo do módulo na prática.

Abra um SKILL.md qualquer que você tenha acesso e me explique,
linha a linha: qual é o frontmatter, o que cada campo (name,
description) faz, e onde começa o corpo de instruções.

Aqui está a description da minha skill: "<cole aqui>".
Lendo SÓ essa linha, sem o corpo, você saberia em quais pedidos
de usuário disparar esta skill? Liste 3 pedidos que disparariam
e 3 que NÃO disparariam.

Vou descrever uma tarefa que faço sempre. Me ajude a separar:
(1) qual seria o name e a description (o gatilho), e
(2) o que vai no corpo (workflow, regras, formato de saída).
A tarefa é: <descreva>.

📤 Exemplo de saída

Um SKILL.md mínimo, mas completo e válido — exatamente o esqueleto que você vai expandir nos próximos módulos.

---
name: changelog-writer
description: Writes a clean CHANGELOG entry from a list of git
  commits. Use when the user asks to "write a changelog",
  "summarize these commits", or "prep release notes".
---

# Changelog Writer

## Workflow
1. Ask for the version number and the commit list (or read it).
2. Group commits into: Added, Changed, Fixed, Removed.
3. Rewrite each line in plain, user-facing language.

## Rules
- Never invent changes that aren't in the commits.
- Keep each entry to a single line.

## Output Format
Markdown under a `## [version] - YYYY-MM-DD` header,
one section per group, bullets per change.

✏️ Exercícios práticos