Como transformar uma tarefa repetitiva em uma skill reutilizável para o seu agente de programação com IA

Se você fica colando a mesma checklist no seu agente de programação com IA — "escreva um conventional commit, depois rode os testes, depois atualize o changelog" — você está fazendo um trabalho que o agente poderia memorizar por você. A maioria dos agentes modernos permite empacotar um procedimento recorrente em um arquivo pequeno e reutilizável. No Claude Code, eles são chamados de skills; o mesmo arquivo também alimenta slash commands como /deploy. Este guia explica como construir uma do zero e, em seguida, apresenta os princípios que se aplicam a outras ferramentas.

O que é uma skill

Uma skill é uma pasta com um único arquivo SKILL.md dentro. Esse arquivo tem duas partes: o frontmatter YAML, que diz ao agente quando usar a skill, e um corpo em markdown com as instruções que ele segue quando a skill é executada. A principal vantagem em relação a amontoar tudo em um arquivo CLAUDE.md (ou AGENTS.md) é a divulgação progressiva: o corpo só é carregado quando a skill é de fato invocada, então material de referência longo custa quase nada até você precisar dele.

Você invoca uma skill de duas maneiras: diretamente, digitando /skill-name, ou automaticamente — o agente lê seu pedido, compara-o com a description da skill e a carrega se for relevante.

Onde as skills ficam

Onde você coloca a pasta decide quem pode usá-la. No Claude Code, conforme a documentação oficial:

• ~/.claude/skills/<name>/SKILL.md — pessoal, disponível em todos os seus projetos.
• .claude/skills/<name>/SKILL.md — do projeto, versionada no repositório para que todos na equipe tenham o mesmo comando.

O nome da pasta se torna o comando. Uma pasta chamada summarize-changes lhe dá /summarize-changes.

Um exemplo concreto

Vamos construir uma skill que resume suas alterações não commitadas e sinaliza qualquer coisa arriscada antes de você fazer o commit. Crie o diretório:

mkdir -p ~/.claude/skills/summarize-changes

Depois salve isto como ~/.claude/skills/summarize-changes/SKILL.md:

---
description: Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed, wants a commit message, or asks to review their diff.
---

## Current changes

!`git diff HEAD`

## Instructions

Summarize the changes above in two or three bullet points, then list any
risks you notice such as missing error handling, hardcoded values, or tests
that need updating. If the diff is empty, say there are no uncommitted changes.

Duas coisas fazem isso funcionar. Primeiro, a description é escrita para o agente, não para você — ela nomeia os gatilhos ("what changed", "wants a commit message", "review their diff") para que o agente saiba quando recorrer a ela. Segundo, a linha !`git diff HEAD` é a injeção dinâmica de contexto: o Claude Code executa esse comando e cola sua saída no prompt antes de o agente ler a skill. As instruções chegam com o seu diff real já incorporado, de modo que a resposta é fundamentada na sua árvore de trabalho real, em vez de em suposições.

Faça uma pequena edição em qualquer arquivo, inicie seu agente e experimente das duas maneiras — pergunte "o que eu mudei?" para acioná-la automaticamente, ou digite /summarize-changes para executá-la diretamente.

Passando argumentos

Skills podem receber entrada. Um placeholder $ARGUMENTS no corpo é substituído por aquilo que você digitar após o comando, e variantes indexadas ($0, $1) capturam palavras específicas. Uma skill invocada como /fix-issue 4821 pode referenciar o número da issue diretamente, de modo que um único arquivo lida com todas as issues, em vez de um por ticket.

Cinco princípios para skills que se sustentam

Estes se aplicam quer você esteja escrevendo uma skill do Claude Code, um comando do Cursor ou — desde o recurso Record & Replay da OpenAI, de junho de 2026 — editando uma automação que o agente gravou para você:

1. Escreva a description para o modelo. Coloque frases de gatilho concretas logo no início. Uma description vaga significa que o agente nunca carregará a skill automaticamente, e você volta a digitar / e a lembrar nomes.
2. Mantenha cada skill com uma única função. Uma skill que faz deploy e executa migrações e posta no Slack é difícil de confiar e ainda mais difícil de depurar. Skills pequenas e de propósito único se combinam melhor.
3. Injete contexto ao vivo em vez de descrevê-lo. Trazer um diff real, um resultado de teste ou uma listagem de arquivos é melhor do que dizer ao agente "verifique o estado atual" — isso elimina uma etapa em que o agente pode supor errado.
4. Coloque uma trava em qualquer coisa com efeitos colaterais. Para skills que fazem deploy, migram ou apagam, exija invocação explícita em vez de deixar o agente dispará-las automaticamente. Você quer um humano no circuito antes de ações irreversíveis.
5. Versione as skills da equipe no repositório. Colocar as skills do projeto em .claude/skills/ e versioná-las significa que cada desenvolvedor — e cada execução do agente no CI — segue o mesmo procedimento. Suas convenções deixam de viver na cabeça de uma única pessoa.

Quando recorrer a uma skill

A regra prática: no momento em que você cola as mesmas instruções de múltiplas etapas pela terceira vez, ou uma seção do seu CLAUDE.md deixa de ser um fato e vira um procedimento, mova isso para uma skill. Você ganha um comando reutilizável, seu arquivo de contexto permanece enxuto e as instruções só são carregadas quando realmente necessárias — o que mantém você e o agente focados na tarefa à sua frente.