Ninguém te avisa que prompt não escala. Você escreve o prompt perfeito, ele funciona uma vez, e some no instante em que você fecha a aba. As skills de IA resolvem isso. Uma skill é uma pasta reutilizável e versionada que seu agente carrega sob demanda: você escreve uma vez, e tanto o Claude Code quanto o Codex rodam ela. Em vez de listar cinquenta ideias de uma linha, este artigo constrói oito skills que vale a pena ter primeiro, cada uma com sintaxe SKILL.md de verdade e a invocação que a dispara. Uma biblioteca curta que você realmente publica vale mais do que uma longa que você nunca escreve.
A razão para aprender isso como padrão, e não como truque, é que as skills são multi-fornecedor. A Anthropic apresentou o Agent Skills e a OpenAI adicionou skills ao Codex no mesmo formato. Mesma pasta, vários agentes — então a skill que você escreve hoje sobrevive a qualquer ferramenta que você por acaso esteja usando esta semana.
O que é uma skill (e como ela difere de um prompt)
Uma skill é um diretório com um arquivo obrigatório, SKILL.md. Esse arquivo tem um cabeçalho YAML, no mínimo um name e uma description, seguido de instruções em português claro. Ela pode trazer pastas irmãs: scripts/ para código de verdade, references/ para documentação aprofundada e assets/ para templates. Um exemplo mínimo:
---
name: invoice-chaser
description: Draft polite payment-reminder emails for overdue invoices, escalating tone by days late. Trigger on "chase overdue invoices".
---
Read the overdue-invoice CSV. For each row, draft an email that names the
invoice, the amount, and the days overdue, with tone set by how late it is.
Um prompt é algo que você digita. Uma skill é algo que seu agente possui. Três diferenças importam:
- Skills persistem e versionam. Elas vivem no git, passam por revisão e viajam junto com seu repositório. Seu histórico de prompts não.
- Skills rodam código, não só texto. Uma skill pode trazer um script que preenche um formulário PDF ou reorganiza uma planilha, algo que um modelo não faz de forma confiável só pensando a respeito.
- Skills carregam por revelação progressiva. O agente enxerga primeiro só o nome e a descrição de cada skill, e lê o corpo completo só quando uma tarefa combina. Então uma prateleira de skills não incha seu contexto; essa contenção é o ponto.
É por isso também que a description é peça-chave. É o único texto que o agente lê na hora de decidir se dispara uma skill. Descrição vaga, skill que nunca aciona.
Como Claude Code e Codex usam skills
O Claude Code descobre skills no sistema de arquivos: solte uma pasta no seu diretório de skills e ela está no ar, sem etapa de upload. O Codex oferece dois modos de invocação, explícito (/skills ou $skill-name) e implícito, em que ele seleciona automaticamente com base na sua tarefa. Como ambos leem o mesmo layout de pastas, uma skill bem escrita passa de um para o outro com pouca mudança.
Um enquadramento que vale internalizar: prefira skills a MCP para conhecimento procedural. Skills são baseadas no sistema de arquivos, versionadas em git e sem servidor, bem menos trabalho do que subir um servidor MCP. O MCP continua ganhando para dados ao vivo e conexões com sistemas. Skills ganham para fluxos reutilizáveis. Escolha a ferramenta certa em vez de copiar qualquer uma no piloto automático.
Oito skills para criar primeiro
Cada uma é portátil, e cada uma mostra o SKILL.md mais a linha que a invoca. Comece pelas duas ou três mais próximas da sua semana de verdade.
1. Escritor de mensagem de commit.
---
name: commit-msg
description: Write a Conventional Commits message from the staged diff. Trigger on "write a commit message".
---
Read the staged diff. Output one line: type(scope): summary, then a short body
explaining why, not what. Types: feat, fix, chore, docs, refactor, test.
Invoque: $commit-msg depois de dar stage, ou "escreva uma mensagem de commit para essas mudanças".
2. Descrição de PR a partir de um diff. Transforma o diff de uma branch num resumo com título, uma lista de riscos e um checklist de plano de testes. Invoque com "abra um PR para esta branch". O valor é um template consistente em que seus revisores podem confiar.
3. Esqueleto de teste a partir de uma assinatura. Dada uma função, ele escreve o caminho feliz, um caso de borda e um caso de falha, e para em vez de inventar comportamento que não consegue ver. Invoque: "crie o esqueleto de testes para esta função".
4. Guardião de tom de voz da marca.
---
name: brand-voice
description: Rewrite a draft to match our tone rules. Trigger on "make this on-brand".
---
Apply these rules: short sentences, concrete nouns, no hype words. Keep claims
that have a number or a source; cut claims that do not. Return the edit only.
Escreva as regras uma vez e todo rascunho sai em conformidade sem você ter que se reexplicar.
5. Changelog a partir dos commits. Lê o histórico de commits desde a última tag e rascunha release notes agrupadas em Added, Fixed, Changed. Invoque: "rascunhe o changelog desde a v1.2.0".
6. Screenshot para relatório de bug. Recebe uma imagem mais uma reclamação de uma linha e produz passos de reprodução, esperado versus obtido e um palpite do primeiro erro. Invoque anexando o screenshot e dizendo "registre isto como um bug".
7. Respondedor de macros de suporte ao cliente. Classifica uma mensagem recebida, rascunha uma resposta no tom da sua marca e sinaliza o que precisa de um humano. Tudo em Markdown, sem código. Invoque: "faça a triagem e rascunhe uma resposta para este ticket".
8. A meta-skill: skill-creator. Uma skill que te entrevista sobre um fluxo e cria a pasta da próxima skill. É assim que a biblioteca cresce sem você escrever YAML à mão toda vez.
Para founders não técnicos, comece pelo guardião de tom de voz e pelo respondedor de suporte. Para devs, o escritor de commit, a descrição de PR e o esqueleto de teste se pagam na mesma semana em que você os escreve.
Checklist de segurança e revisão
Skills executam código, então uma ruim é um risco de cadeia de suprimentos. Trate como uma dependência:
- Audite qualquer coisa de fonte não confiável. Leia o
SKILL.mde todo arquivo dentro descripts/antes de instalar. - Mantenha as instruções enxutas. Entulhar um único
SKILL.mdmata a revelação progressiva; empurre material aprofundado parareferences/. - Escreva uma
descriptionafiada. É o gatilho; uma fraca faz a skill silenciosamente nunca disparar. - Construa com uma eval. Parta de um teste do que é "bom", itere junto com o agente, depois enxugue.
- Projete para portabilidade. É um padrão aberto; cravar as suposições de um fornecedor joga fora a principal vantagem.
Mantenha a biblioteca
Salve as skills que você cria como um conjunto versionado no Command Center, para que seu processo seja um ativo que você reutiliza, em vez de um prompt que você redigita.
Fontes e leitura adicional
- Anthropic: Equipping agents for the real world with Agent Skills
- OpenAI Codex: Agent Skills
- Anthropic: Claude Code documentation
FAQ
Uma prateleira de skills vai sobrecarregar minha janela de contexto? Não. A revelação progressiva faz o agente enxergar só nomes e descrições de cara e carregar uma skill inteira sob demanda, então uma skill parada custa quase nada.
Preciso ser programador para escrever uma skill?
Não. A skill mais simples é um SKILL.md com cabeçalho e instruções em português. Use um skill-creator ou um fluxo de record-and-replay para gerar uma a partir de uma demonstração.
Skill é a mesma coisa que servidor MCP? Não. Skills são fluxos procedurais baseados no sistema de arquivos que vivem no git. O MCP conecta a sistemas e dados ao vivo. Use skills para conhecimento de "como fazer" repetível, MCP para conexões em tempo real, e muitas vezes os dois.
Onde coloco uma skill para meu agente achar?
No diretório de skills do seu agente, como uma pasta nomeada contendo um SKILL.md. Claude Code e Codex descobrem skills no sistema de arquivos, e é por isso que a mesma pasta funciona entre fornecedores.