Skills para agentes, direto ao ponto

Escrito e revisado por Jefferson Oliveira. As regras vêm da documentação da Anthropic, conferida em out 2026.

Skill é o jeito mais simples de ensinar um fluxo seu pro agente. Uma pasta, um arquivo SKILL.md com nome, descrição e instruções. O agente lê a descrição de todas e só abre a que serve pro pedido do momento. Este post resume a documentação da Anthropic e as boas práticas que eles publicaram.

Uma pasta com um SKILL.md dentro e, se precisar, scripts e arquivos de referência ao lado. No Claude Code, por exemplo, ela fica em ~/.claude/skills/ quando é sua, pra todos os projetos, ou em .claude/skills/ quando é do projeto. No segundo caso vai pro git, e o time inteiro ganha a skill junto.

1---2name: pr-description3description: Escreve a descrição de um pull request a4  partir do diff. Use ao abrir um PR ou quando pedirem5  pra descrever as mudanças da branch.6---78# pr-description9101. Leia o diff da branch contra a principal.112. Escreva o título como `tipo: o que muda`.123. Explique o porquê em até 15 linhas.

Só name e description são obrigatórios. O name aceita letras minúsculas, números e hífen, até 64 caracteres. A description vai até 1.024 caracteres e diz o que a skill faz e quando usar.

Prompt resolve uma vez. Você escreve, o agente executa, e na próxima sessão começa do zero: ou você cola de novo, ou escreve de outro jeito e recebe outro resultado. A skill é esse prompt guardado num lugar que o agente conhece, e isso muda quatro coisas.

Ela se repete igual. O mesmo SKILL.md roda hoje e daqui a um mês, com os mesmos passos, sem você lembrar de colar nada.

Ela é chamada sozinha. O agente lê a descrição e decide quando usar. Você pede “descreve esse PR” e a skill certa entra.

Ela é do time. Commitada no projeto, vale pra todo mundo, e uma correção de uma linha chega pra todos no próximo pull.

Ela carrega só o necessário. A pasta pode ter script e arquivo de referência, e o agente só abre o que a tarefa pede. Um prompt colado ocupa o contexto inteiro desde a primeira mensagem.

Uma regra que eu uso: colou o mesmo prompt duas vezes, ele virou skill.

A skill carrega em etapas. Na abertura da sessão entram só o nome e a descrição de cada uma. O corpo do SKILL.md entra quando o pedido combina com a descrição. Arquivos extras, como uma referência ou um script, só quando o próprio SKILL.md manda abrir.

Por isso a descrição é a parte que mais importa. Se ela não diz quando usar, a skill nunca é chamada.

Seja curto. A premissa do guia é que o modelo já é muito inteligente, então escreva só o que ele não sabe sobre o seu caso.

Descrição em terceira pessoa, com o que faz e quando usar. “Processa planilhas e gera relatório”, e não “Eu posso te ajudar com planilhas”. A descrição entra no prompt de sistema, e misturar pontos de vista atrapalha a descoberta.

Corpo do SKILL.md abaixo de 500 linhas. Passou disso, divida em arquivos e aponte pra eles a partir do SKILL.md, com um nível de profundidade só.

Um termo por conceito, do começo ao fim, e nada com data de validade. E teste antes de escrever muito: o guia pede pelo menos três avaliações com cenários reais, rodadas em todos os modelos que vão usar a skill.

Jefferson Oliveira // o detalhe que eu gosto

Skill melhora com o uso. A que monta estes posts ganhou uma regra nova esta semana, depois que eu cortei um fechamento que soava grosso. Uma linha no SKILL.md, e o próximo post já sai sem ele.

O agente decide sozinho quando usar uma skill, mas dá pra chamar na mão. No Claude Code é /nome-da-skill. Pra fluxo que só deve rodar quando você pede, como um deploy, coloque disable-model-invocation: true no frontmatter.

1. [1] Documentação oficial · Claude Code Docs: Skills (abre em nova aba) code.claude.com/docs/en/skills copiar link da referência 1copiado
2. [2] Documentação oficial · Agent Skills overview (abre em nova aba) platform.claude.com/docs/en/agents-and-tools/agent-skills/overview copiar link da referência 2copiado
3. [3] Documentação oficial · Skill authoring best practices (abre em nova aba) platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices copiar link da referência 3copiado
4. [4] Padrão aberto · Agent Skills (abre em nova aba) agentskills.io copiar link da referência 4copiado

Fontes conferidas em out 2026.

// quem escreveu

Jefferson Oliveira

AI Engineer · Studio Visual (abre em nova aba) · São Paulo, SP

Trabalho há mais de 5 anos com PHP, Laravel e WordPress, construindo e-commerces, integrações e sistemas internos. Hoje lidero a adoção de IA na Studio Visual (abre em nova aba) e curso MBA em Engenharia de Software na FIAP.

• MBA em Engenharia de Software · FIAP (cursando)
• Análise e Desenvolvimento de Sistemas · FATEC Zona Leste
• Liderança e Gestão de Equipes · FGV
• PHP: Desenvolvimento Web e POO · 4Linux

Conheça minha trajetória → LinkedIn ↗ (abre em nova aba) GitHub ↗ (abre em nova aba)