Skills: como ensinar seu agente de IA a trabalhar do seu jeito

Quem começa a trabalhar com agentes de programação, como o Claude Code ou o Codex, logo percebe um padrão irritante: você explica a mesma coisa toda semana. Como criar uma entidade no padrão do projeto. Como escrever o teste. Qual comando roda a migração. Onde fica cada coisa.

O agente é capaz. Ele só não sabe como a sua equipe faz as coisas. E a cada sessão nova, ele esquece.

As skills resolvem exatamente isso. Neste artigo, a gente vai entender o que elas são, por que funcionam e construir uma do zero.

Se você ainda não sabe o que é o harness de um agente, recomendo ler antes Claude Code e Codex: o que é um harness. Skills são uma das peças dele.

O que é uma skill

Uma skill é uma pasta com um arquivo SKILL.md dentro. Esse arquivo tem duas partes:

um cabeçalho com o nome e a descrição da skill;
as instruções, em Markdown, de como fazer aquela tarefa.

Opcionalmente, a pasta pode trazer arquivos de apoio: documentos de referência, modelos, scripts.

nova-entidade-jpa/
├── SKILL.md              obrigatório: descrição + instruções
├── referencias/
│   └── convencoes.md     lido só se as instruções mandarem
└── scripts/
    └── verificar.sh      executado pelo agente quando preciso

É só isso. Não é plugin compilado, não precisa de linguagem especial. É texto organizado, que um colega humano também conseguiria seguir.

E tem um detalhe que vale ouro: o formato foi publicado como padrão aberto. O Claude Code e o Codex leem o mesmo SKILL.md. Escreveu uma vez, funciona nos dois.

Por que não colocar tudo no CLAUDE.md ou no AGENTS.md?

Boa pergunta, e a resposta explica por que skills existem.

O CLAUDE.md (no Claude Code) e o AGENTS.md (no Codex) são lidos no início de toda sessão. Tudo o que está ali ocupa espaço na janela de contexto o tempo todo, mesmo quando não tem nada a ver com a tarefa. Se você colocar ali o passo a passo de vinte tarefas diferentes, o agente carrega as vinte para corrigir um erro de digitação.

A skill funciona por carregamento progressivo:

No começo da sessão, o agente vê só o nome e a descrição de cada skill. Poucas linhas.
Quando a tarefa combina com a descrição, ele carrega as instruções completas do SKILL.md.
Os arquivos de apoio só são lidos se as instruções mandarem e quando for preciso.

É o mesmo princípio de um bom índice de livro: você não lê o livro inteiro para achar um capítulo.

A regra prática fica assim:

Coloque em…	Quando a informação é…
`CLAUDE.md` / `AGENTS.md`	regra que vale sempre (como rodar os testes, padrão de nomes)
Skill	procedimento para um tipo de tarefa (criar entidade, publicar versão)
O próprio pedido	algo que vale só agora

Onde as skills ficam

Cada ferramenta procura skills em pastas específicas:

	Claude Code	Codex
Só neste projeto	`.claude/skills/<nome>/SKILL.md`	`.agents/skills/<nome>/SKILL.md`
Em todos os seus projetos	`~/.claude/skills/<nome>/SKILL.md`	`~/.agents/skills/<nome>/SKILL.md`
Chamar manualmente	`/nome`	`$nome`

Além de chamar manualmente, nos dois o agente escolhe a skill sozinho quando a tarefa combina com a descrição. Skills de projeto vão para o git junto com o código: a equipe inteira passa a trabalhar do mesmo jeito.

Construindo uma skill do zero

Vamos a um caso real. Num projeto Java com Spring, toda entidade nova exige o mesmo ritual: a classe com as anotações certas, o repositório, a migração do banco e um teste. E a equipe tem regras que o agente não teria como adivinhar.

Passo 1: o cabeçalho

Crie a pasta .claude/skills/nova-entidade-jpa/ (ou .agents/skills/nova-entidade-jpa/, no Codex) e, dentro dela, o SKILL.md. Comece pelo cabeçalho:

---
name: nova-entidade-jpa
description: >-
  Cria uma entidade JPA nova no padrão do projeto: classe da entidade,
  repositório Spring Data, migração Flyway e teste. Use quando pedirem uma
  entidade, tabela ou modelo novo, ou um novo cadastro que precise ser salvo
  no banco.
---

A descrição é a parte mais importante da skill inteira. É o único texto que o agente vê antes de decidir se vai usá-la. Repare que ela diz duas coisas:

o que a skill faz (cria entidade, repositório, migração e teste);
quando usar, com as palavras que alguém usaria ao pedir (“entidade”, “tabela”, “modelo”, “cadastro”).

Uma descrição vaga como “ajuda com banco de dados” faz a skill ser ignorada quando deveria ser usada e lembrada quando não deveria.

Passo 2: as instruções

Agora o corpo, logo depois do cabeçalho. Escreva como se fosse para um colega competente que acabou de chegar na equipe:

# Nova entidade JPA

Antes de começar, leia `referencias/convencoes.md` (nomes e tipos usados no projeto).

## Passos

1. Pergunte os campos e os relacionamentos, se o pedido não disser.
2. Crie a entidade em `src/main/java/com/loja/dominio/`:
   - `@Id` com `@GeneratedValue(strategy = GenerationType.IDENTITY)`;
   - todo relacionamento com `fetch = FetchType.LAZY`, inclusive `@ManyToOne`;
   - sem setters públicos para o id.
3. Crie o repositório em `com.loja.repositorio`, estendendo `JpaRepository`.
4. Crie a migração em `src/main/resources/db/migration/`, com o próximo número
   da sequência (`V<n>__cria_<tabela>.sql`). Nunca altere uma migração existente.
5. Crie um teste com `@DataJpaTest` que salva e busca a entidade.
6. Rode `scripts/verificar.sh` e só diga que terminou se ele passar.

## Exemplo de entidade no padrão

(cole aqui uma entidade pequena do projeto que esteja do jeito certo)

Algumas escolhas aqui não são por acaso:

Passos numerados. O agente segue uma lista melhor do que um parágrafo.
Caminhos e nomes exatos. “Na pasta de domínio” é ambíguo; src/main/java/com/loja/dominio/ não é.
O porquê fica no lugar certo. A regra do LAZY evita o problema que expliquei em O problema N+1 no JPA/Hibernate. Se a equipe precisar lembrar o motivo, ele pode ir no arquivo de convenções.
Um exemplo real. Um trecho de código no padrão ensina mais que dez regras escritas.
Uma verificação no fim. Isso fecha o laço “agir, verificar” do agente: ele confere o próprio trabalho antes de dizer que terminou.

Passo 3: os arquivos de apoio

O referencias/convencoes.md guarda o que é detalhado demais para o SKILL.md: tabela de tipos (dinheiro sempre BigDecimal, datas sempre LocalDate), padrão de nomes de colunas, exemplos maiores. Como ele só é lido quando a instrução manda, pode ser longo sem custar nada nas outras tarefas.

O scripts/verificar.sh mostra outra ideia poderosa: o que pode ser feito por um programa não deve depender da IA. Compilar, rodar os testes, conferir se a migração tem o número certo: tudo isso um script faz de forma exata, toda vez.

#!/usr/bin/env bash
set -e
./mvnw -q test
echo "Testes ok."

A IA cuida da parte que exige julgamento; o script cuida da parte que exige exatidão.

Passo 4: testar e ajustar

Abra uma sessão nova e peça, com palavras naturais: “preciso de um cadastro de fornecedores, com nome, CNPJ e e-mail”. Observe:

O agente usou a skill? Se não, a descrição não conversa com o jeito que as pessoas pedem. Acrescente as palavras que faltaram.
Seguiu os passos? Se pulou algum, talvez a instrução esteja ambígua ou enterrada no meio de um parágrafo.
Errou de novo uma coisa? Esse erro vira uma regra nova na skill.

Skill boa não sai pronta na primeira versão. Ela amadurece como qualquer código, com uso e correção. E, por ser texto no git, cada melhoria fica registrada para a equipe toda.

Se quiser um ponto de partida, o Codex traz uma skill pronta para criar skills ($skill-creator), que faz perguntas e monta a estrutura com você.

Boas práticas

Uma skill, uma tarefa. “nova-entidade-jpa” é bom; “tudo-sobre-o-backend” vira um CLAUDE.md disfarçado.
Instruções curtas no SKILL.md, detalhes nos arquivos de apoio. A documentação do Claude Code sugere manter o SKILL.md com menos de 500 linhas.
Escreva para um colega, não para uma máquina. Se uma pessoa nova na equipe não entenderia, o agente provavelmente também vai tropeçar.
Nada de segredos. Senha e chave de API não vão na skill, que vai para o git. Use variáveis de ambiente.
Leia antes de instalar skills de terceiros. Uma skill pode mandar o agente executar scripts. Instalar uma skill desconhecida sem ler é como rodar um programa baixado de qualquer lugar.

Conclusão

Uma skill é uma pasta com um SKILL.md: descrição + instruções + arquivos de apoio opcionais.
Ela é carregada só quando a tarefa pede, o que permite ter muitas sem pesar no contexto.
A descrição decide se ela será usada: diga o que faz e quando usar, com as palavras de quem pede.
Passos numerados, caminhos exatos, um exemplo real e uma verificação no fim fazem o agente acertar.
O mesmo formato funciona no Claude Code e no Codex.

No fundo, escrever uma skill é escrever um bom procedimento: pensar no problema, decompor em passos, prever os erros e definir como verificar o resultado. Ou seja, é programar, só que em português. E programar, como eu sempre digo, é um ato de pensar.