📋 Skill é o POP do seu agente
Novo aqui? POP é a sigla de "procedimento operacional padrão" — o passo a passo escrito que uma empresa usa pra garantir que uma tarefa seja feita sempre do mesmo jeito, não importa quem execute. Uma skill é exatamente isso, mas para o seu agente: um arquivo de texto reutilizável que ensina, em detalhe, como fazer um processo específico — desde "como escrever um post no padrão da minha empresa" até "como gerar um relatório financeiro seguindo estas regras".
A diferença para o que você já viu na Trilha 2 é o disparo. Uma ferramenta MCP (módulo 2.1) o agente escolhe
na hora, olhando o que está disponível. Uma skill ele carrega quando reconhece a tarefa — seja porque
você digitou um comando explícito (tipo /relatorio-financeiro),
seja porque a sua frase em linguagem natural bate com a descrição que a skill carrega de si mesma.
Ninguém precisa digitar comando nenhum — só descrever o que quer.
💡 Conceito Principal
Skill = markdown reutilizável, carregado quando o agente reconhece a tarefa, disparado por comando ou por linguagem natural.
- •Um funcionário novo não tem a sua experiência de anos — mas pode consultar o manual plastificado da mesa.
- •A skill é esse manual: escrito uma vez, consultado toda vez que a tarefa se repete.
🔍 Por dentro
Você mesmo tem POPs mentais que nunca escreveu: "quando o cliente reclama de prazo, primeiro eu confirmo a data, depois ofereço duas opções". A skill é forçar você a escrever isso uma vez — e o agente passa a seguir esse mesmo roteiro toda vez, sem esquecer um passo.
📁 A pasta por dentro
Fisicamente, uma skill é uma pasta com o nome da skill.
Dentro dela, um arquivo obrigatório chamado skill.md,
e dois tipos de conteúdo opcional: uma pasta references/
com documentos mais longos, e uma pasta scripts/
com pequenos programas que a skill pode executar.
Legenda: o único arquivo obrigatório é o skill.md no topo da pasta; references/ e scripts/ existem mas só são abertos quando o passo a passo manda — isso é o assunto do módulo 3.2.
🏷️ O front matter: a etiqueta da skill
Novo aqui? Front matter é
um cabeçalho de metadados no topo de um arquivo markdown, delimitado por três traços (---)
em cima e embaixo. Pense nele como a etiqueta colada na lombada de uma pasta de arquivo físico: antes de
abrir e ler o conteúdo inteiro, você já sabe do que se trata só olhando a etiqueta.
O front matter de uma skill precisa de pelo menos dois campos: name (o
nome curto da skill) e description (uma
frase dizendo o que a skill faz e quando usar). É só isso que o agente lê o tempo todo — o corpo do arquivo
só é aberto quando a skill é de fato disparada. Isso volta com detalhe no módulo 3.2.
---
name: relatorio-financeiro
description: Gera o relatório financeiro mensal no padrão da empresa,
a partir de uma planilha exportada do sistema de vendas. Use quando
o usuário pedir "relatório financeiro", "fechamento do mês" ou
"resumo de vendas".
---
# Relatório financeiro mensal
## Passo a passo
1. Peça o caminho da planilha exportada se não foi informado.
2. Leia as colunas: data, valor, categoria.
3. Some por categoria e calcule o total do mês.
4. Gere o arquivo `relatorio-<mês>.md` seguindo o modelo em
`references/modelo-relatorio.md`.
5. Mostre o resumo em texto antes de salvar o arquivo.💡 Dica Prática
Escreva a description pensando em como VOCÊ pediria a tarefa em voz alta, não em termos técnicos. É essa frase que o agente compara com o seu pedido pra decidir se aquela skill serve. O módulo 3.4 é inteiro sobre isso.
📝 O corpo: o passo a passo de verdade
Depois do front matter, o resto do skill.md é
markdown normal — o mesmo formato de texto do CLAUDE.md (módulo 0.4). É aqui que fica o processo em si: os
passos numerados, as regras a seguir, os exemplos, os avisos do que não fazer. Pense nisso como o
miolo do manual plastificado: a etiqueta na capa te disse o assunto, agora as páginas de dentro ensinam
o procedimento completo.
✓ Anatomia bem-feita
- ✓Passos numerados, um por linha, em ordem de execução
- ✓Detalhe longo (tabela de códigos, exemplos extensos) empurrado pra
references/ - ✓Diz explicitamente quando NÃO usar a skill
✗ Anatomia mal-feita
- ✗Um parágrafo corrido, sem passos claros
- ✗Cola tudo no
skill.md— inclusive a tabela gigante que só é usada uma vez a cada dez execuções - ✗Assume que o agente "vai adivinhar" quando algo não está escrito
🔍 Por dentro
Não existe limite rígido de tamanho, mas a prática que funciona é manter o corpo curto — algo entre um parágrafo de contexto e uma lista de passos, geralmente cabendo numa página. Se o assunto exige muito mais detalhe, isso é sinal de que parte dele deveria virar um arquivo em references/, e não inchar o corpo principal.
📚 Referências e scripts: os apêndices
A pasta references/ guarda
documentos mais longos — uma tabela de categorias, um glossário de termos internos, um exemplo extenso —
que o agente só abre se o passo a passo mandar explicitamente ("se precisar do detalhe X, leia o arquivo Y").
É o apêndice técnico do manual: existe, está ali, mas ninguém carrega ele na cabeça o tempo todo.
A pasta scripts/ guarda
pequenos programas — um script Python que calcula um total, um shell script que renomeia arquivos em lote —
que a skill pode rodar em vez de pedir para o agente reinventar aquela lógica toda vez do zero. Roda mais
rápido e sai sempre igual, porque é código determinístico, não uma decisão nova do modelo a cada execução.
🎯 Conceito Principal
- •
references/= conhecimento sob demanda (o agente lê texto) - •
scripts/= ação sob demanda (o agente executa código) - •Nenhuma das duas pesa no dia a dia — só entram em cena quando chamadas
💡 Dica Prática
Regra prática pra decidir onde algo vai: se você reler aquele trecho toda vez que executa a skill, ele fica no corpo do skill.md. Se você só consulta de vez em quando ("qual é mesmo o código da categoria X?"), ele vai pra references/.
⏱️ O que acontece quando a skill é chamada
Juntando tudo: quando você pede algo em linguagem natural, ou digita o comando, o agente percorre uma pequena sequência de decisões até a skill virar ação. Veja a linha do tempo de uma chamada real.
Você pede: "fecha o relatório financeiro do mês"
Frase normal, sem comando especial.
O agente compara sua frase com a description de cada skill instalada
Reconhece o casamento com a description da skill relatorio-financeiro.
Carrega o corpo inteiro do skill.md daquela skill
Agora sim lê o passo a passo completo — não só a etiqueta.
Segue os passos; abre references/ ou roda scripts/ só se o passo mandar
Nesse exemplo: lê o modelo de relatório em references/ no passo 4.
⚠️ Atenção
Se duas skills têm descriptions parecidas demais, o agente pode escolher a errada — ou hesitar. O módulo 3.4 mostra como escrever gatilhos que não colidem.
Checagem rápida (opcional): qual arquivo é o único obrigatório dentro da pasta de uma skill?