Antes dos sete tópicos, veja o caminho que liga tudo: você escreve um workflow em markdown, ele passa a viver numa pasta (.claude/skills), e o agente o expõe como um slash command que pode chamar quando você (ou uma instrução) o invoca. Uma skill é, no fundo, um pedaço de processo embalado para reuso.
Diagrama ilustrativo — uma skill nasce de um workflow descrito em texto; depois de salva, o agente a oferece como comando e a reusa de forma consistente sempre que invocada.
📦 O que é uma skill
O que é
Uma skill é, na essência, um arquivo markdown de instruções — conceitualmente idêntico à camada W (workflows) do framework WAT. A diferença em relação a um workflow que você só descreve no chat é onde ele mora e como é acionado: a skill fica salva numa pasta do projeto e é invocada por um comando, então pode ser executada da mesma forma quantas vezes você quiser, sem você reescrever o processo.
O que é?Workflow — uma sequência de passos que resolve uma tarefa (o "W" do WAT). Slash command — um comando que começa com / e dispara uma ação no agente (ex.: /clear). Uma skill é um workflow embalado e exposto como slash command.
O detalhe libertador: você não precisa saber escrever skills. Você descreve o workflow em linguagem natural — "toda vez que eu pedir, faça X, depois Y, depois salve em Z" — e pede ao agente para transformar isso numa skill / slash command. Ele cria o arquivo, e você passa a chamá-lo por um comando. É o mesmo princípio do vibe coding: descreve o resultado, a IA faz o trabalho pesado.
Por que aprender
Skills resolvem quatro dores de uma vez. Sem elas, você reexplica o mesmo processo toda sessão, gasta tokens repetindo contexto e perde consistência. Embaladas numa skill, ganham:
- •Consistência: o mesmo processo roda igual toda vez, sem reexplicar.
- •Economia de tokens: a skill carrega sob demanda, só quando invocada — não fica ocupando o contexto o tempo todo.
- •Compartilhável: é um arquivo — você passa para o time inteiro.
- •Confiável: embrulha passos complexos e fáceis de esquecer → você delega-e-esquece.
🎯 Objetivo: pedir ao agente para transformar um workflow seu numa skill
Transforme este workflow numa skill chamável (slash command). Nome desejado: <nome-da-skill> Quando deve ser usada: <descreva o gatilho — ex.: "quando eu pedir um resumo de reunião"> Argumentos que ela recebe: <ex.: texto-bruto, formato-de-saida> Passos do processo: 1. <passo 1> 2. <passo 2> 3. <onde salvar / formato final> Crie o arquivo em .claude/skills/ e me diga como invocá-la.
✅ Como verificar: o agente deve criar o arquivo e responder com o comando /<nome-da-skill>. Rode-o uma vez para confirmar que aparece e pede os argumentos.
Conceitos-chave
Instruções em texto.
Workflow do WAT.
Carrega só ao chamar.
A IA escreve a skill.
📁 Onde vivem e como viram slash command
O que é
As skills vivem num diretório do projeto chamado .claude/skills. A organização é simples: cada skill fica na sua própria pasta, e dentro dela há um arquivo de skill que descreve o que ela faz. O agente varre essa pasta e expõe cada skill como um slash command — um comando que começa com / e que você digita para acioná-la.
O que é?Diretório .claude — uma pasta de configuração que o agente lê dentro do seu projeto. Built-in — um comando que já vem pronto (ex.: /clear limpa o contexto). Suas skills aparecem ao lado dos built-ins, na mesma lista de slash commands.
Por que aprender
Entender o lugar e o mecanismo desfaz a mágica: skill não é um recurso oculto da IA, é um arquivo numa pasta que vira comando. Vale notar a unificação recente: os slash commands foram unificados em skills — ou seja, criar uma skill e criar um slash command viraram a mesma coisa. Por isso, comparar com built-ins como /clear ajuda: a diferença é só que os seus são definidos por você, no projeto.
Ciclo de vida de uma skill
-
1
Descrever o workflow
Você conta o processo em linguagem natural — passos, entradas, saída.
-
2
Agente gera o arquivo de skill
Ele cria a pasta em
.claude/skillscom nome, descrição e passos. -
3
Invocar pelo slash command
Você digita
/nome-da-skille o agente executa o processo. -
4
Reusar (e compartilhar)
Mesma execução sempre; e por ser arquivo, vai junto no projeto para o time.
Conceitos-chave
O lar das skills.
Skill isolada por pasta.
Exposta como slash command.
Slash commands = skills.
🧬 Anatomia do SKILL.md
O que é
Toda skill tem quatro partes essenciais: nome (como ela é chamada), descrição (o gatilho — ensina o agente QUANDO usar a skill), argumentos esperados (as entradas que ela recebe) e as instruções passo a passo (o que fazer). A peça mais subestimada é a descrição: ela não é decorativa — é o que faz o agente decidir, sozinho, que aquela skill é a certa para a situação.
O que é?Gatilho (trigger) — a condição que faz a skill ser escolhida. Uma boa descrição diz "use isto QUANDO...". Se ela for vaga, o agente não saberá quando aplicar; se for precisa, ele acerta sozinho.
🎯 Objetivo: criar o arquivo que define uma skill chamável
--- name: <nome-da-skill> description: <quando-acionar — ex.: rascunhar um e-mail a partir de bullets> --- # <Título da skill> ## Argumentos - destinatario: <quem recebe> - tom: <profissional | casual> - bullets: <pontos-chave do e-mail> ## Passos 1. Leia os <bullets> e o <tom>. 2. Escreva um e-mail polido, conciso, sem enrolação. 3. Salve em temporary/<nome-arquivo>.md
✅ Como verificar: rode /<nome-da-skill> — se a skill aparecer na lista de slash commands e pedir os argumentos que faltam, está registrada.
Por que aprender
Conhecer a anatomia te dá controle mesmo sem escrever: você sabe pedir uma descrição-gatilho boa ("use quando eu colar bullets de e-mail"), nomear argumentos claros e listar passos na ordem certa. E sabe revisar o que o agente gerou — se a descrição estiver fraca, é só pedir para deixá-la mais específica. A estrutura frontmatter (nome + descrição) + corpo (argumentos + passos) é o esqueleto de toda skill.
Conceitos-chave
Como é chamada.
O gatilho: QUANDO usar.
As entradas esperadas.
As instruções em ordem.
🔧 Skills podem chamar tools
O que é
Uma skill não substitui as tools (ferramentas) — ela as orquestra. Dentro dos seus passos, uma skill ainda pode acionar tools: scripts em Python que fazem busca na web, raspagem de uma página, geração de um documento. Ou seja, o WAT permanece intacto por baixo: a skill é o W (workflow), a tool é o T (ferramenta), e o agente é quem decide quando rodar cada tool no meio do processo.
O que é?Tool (ferramenta) — um pedaço de código que faz uma ação concreta no mundo (busca, raspagem, salvar arquivo). WAT — o framework Workflows + Agents + Tools: skills são os workflows, tools são as ferramentas, o agente costura tudo.
Por que aprender
Saber que skill ≈ W e tool ≈ T evita uma confusão comum: achar que adotar skills joga fora tudo o que você aprendeu sobre tools e MCP. Não joga. A skill apenas dá um roteiro reutilizável de quando e como usar as suas ferramentas. Uma skill de "pesquisa de mercado", por exemplo, pode dizer: busque na web, raspe as três primeiras páginas, resuma e gere um documento — chamando uma tool em cada passo.
Conceitos-chave
O workflow do WAT.
A ferramenta concreta.
A skill chama tools.
Quando rodar cada tool.
⚖️ Quando usar skill vs digitar
O que é
Nem tudo merece virar skill. A regra: crie uma skill quando o processo se repete, a consistência importa, as instruções são complexas ou esquecíveis, ou você quer compartilhar com o time. Para o resto — uma tarefa de uma frase, uma experimentação inicial, uma instrução simples — é mais rápido só digitar. Embalar uma tarefa trivial numa skill só adiciona cerimônia.
O que é?Cerimônia — o esforço extra de formalizar algo (criar arquivo, nomear, documentar). Vale a pena quando você vai reusar; é desperdício para um pedido único.
Por que aprender
O critério evita os dois extremos: nunca usar skills (e reexplicar tudo, toda vez) ou virar skill de qualquer coisa (e poluir a pasta com comandos que você usa uma vez só). A pergunta-chave é simples: "vou repetir isto?" Se sim, e a consistência importa, vale a skill. Se é one-off, digite.
✓ Crie uma SKILL quando…
- ✓O workflow se repete (você já fez isso 3+ vezes).
- ✓A consistência importa (mesmo formato/qualidade sempre).
- ✓As instruções são complexas ou fáceis de esquecer.
- ✓Você quer compartilhar o processo com o time.
✗ Só DIGITE quando…
- ✗É uma tarefa de uma frase, pontual.
- ✗Você ainda está experimentando / explorando o problema.
- ✗A instrução é simples e não se repete.
- ✗Formalizar custaria mais do que só pedir de novo.
Conceitos-chave
Se repete → skill.
Importa → skill.
Pontual → digitar.
A pergunta-chave.
🪶 Skills vs CLAUDE.md (contexto sob demanda)
O que é
A divisão de trabalho: o CLAUDE.md guarda só o que vale para toda sessão — propósito do projeto, objetivo, framework, regras gerais. Ele está sempre no contexto. Já o que é por-tarefa (per-task) vai para skills, que carregam sob demanda — só quando você invoca aquele comando. É a diferença entre "o que a IA precisa saber sempre" e "o que ela só precisa quando vai fazer X".
O que é?CLAUDE.md — arquivo de memória que o agente lê no início de toda sessão. Contexto sob demanda — carregar informação só no momento em que ela é necessária, para não ocupar a "memória de trabalho" o tempo todo.
Diagrama ilustrativo — jogar tudo no CLAUDE.md enche o contexto fixo; manter o per-task em skills deixa dezenas de comandos disponíveis sem peso, porque só o invocado é carregado.
Por que aprender
O erro clássico do iniciante é jogar tudo no CLAUDE.md — toda instrução, todo workflow, todo detalhe. Isso estoura o contexto: o arquivo fica gigante, ocupa espaço em toda sessão e degrada a atenção da IA. A sacada das skills é exatamente essa: você pode ter 20, 50 skills sem inchar nada, porque elas só carregam quando chamadas. CLAUDE.md enxuto + muitas skills sob demanda > CLAUDE.md gigante.
✓ No CLAUDE.md (toda sessão)
- ✓Propósito e objetivo do projeto.
- ✓O framework / convenções gerais.
- ✓Regras que valem em qualquer tarefa.
✗ NÃO no CLAUDE.md → vai pra skill
- ✗Workflows específicos de uma tarefa só.
- ✗Passo a passo longo e detalhado de um processo.
- ✗Tudo que só importa quando você vai fazer X.
🎯 Dica prática
Antes de adicionar algo ao CLAUDE.md, pergunte: "isto vale para toda sessão, ou só quando faço uma tarefa específica?" Se for específico, vire skill. Seu CLAUDE.md deve caber numa olhada; o resto do conhecimento mora na pasta de skills, pronto para ser chamado.
Conceitos-chave
CLAUDE.md x skill.
Ficam no CLAUDE.md.
Vira skill.
20–50 skills, sem peso.
🤝 Compartilhar e versionar
O que é
Como uma skill é apenas um arquivo numa pasta do projeto, ela herda todas as vantagens de um arquivo de código: pode ser versionada no Git (histórico de mudanças, revisão, reverter), e compartilhada com qualquer pessoa que clone o projeto. O processo deixa de ser conhecimento preso na cabeça de uma pessoa e vira um ativo do time.
O que é?Git — o sistema que guarda o histórico de versões de arquivos. Versionar — registrar cada mudança de um arquivo ao longo do tempo, para poder ver, revisar e reverter. Como a skill é arquivo, ela entra nesse fluxo de graça.
Por que aprender
Esse é o salto de "truque pessoal" para "capacidade de equipe". Quando o seu melhor workflow vira uma skill versionada, qualquer colega passa a executar o mesmo processo, com a mesma qualidade, sem precisar te perguntar como. Erros corrigidos na skill beneficiam todo mundo na próxima invocação. É reuso de verdade: escreve uma vez, todo o time colhe.
Conceitos-chave
Logo, versionável.
Histórico e reverter.
Clonou, já tem.
Não preso numa cabeça.
Você tem um processo de 8 passos que repete toda semana e quer que um colega execute igual. Onde isso deve morar?
📌 Resumo do Módulo
Próximo Módulo:
4.2 — Construindo Skills na Prática