O que é uma skill de agente (SKILL.md) e como examiná-la

Uma skill é uma pasta com um arquivo SKILL.md que fica onde seu agente de código procura por ela. O agente lê o arquivo apenas quando sua solicitação corresponde a ele. Até lá, a skill custa cerca de cem tokens, enquanto um prompt viaja junto com cada mensagem em que você o cola.

Você provavelmente já encontrou a palavra em um README: "instale a skill, depois peça ao agente para...". Não há nada de misterioso. Abaixo: o que há dentro, quando ela entra na janela de contexto e como examinar uma antes de deixá-la entrar na sua máquina.

O que é uma skill e como ela difere de um prompt#

A documentação de Agent Skills da Anthropic (verificada em 30 de outubro de 2026) descreve uma skill como um recurso reutilizável baseado em sistema de arquivos: um diretório com um arquivo SKILL.md, além de scripts, templates e arquivos de referência opcionais. SKILL.md começa com um pequeno cabeçalho YAML (um nome e uma descrição) e continua com instruções em texto simples.

Pense em um colega novo. Um prompt é você parado atrás da cadeira dele repetindo as regras toda manhã. Uma skill é um fichário na estante com uma etiqueta na lombada: "Estilo de mensagem de commit. Leia quando alguém pedir para você fazer um commit." Ele só pega o fichário quando é necessário.

Dois campos do cabeçalho são obrigatórios, e o formato tem regras. No formato Skills do Claude, o name tem no máximo 64 caracteres: letras minúsculas, dígitos e hífens, e não pode conter as palavras "anthropic" ou "claude". O description não pode ficar vazio, tem limite de 1.024 caracteres e precisa dizer tanto o que a skill faz quanto quando usá-la.

Como uma skill entra na janela de contexto#

A documentação chama isso de divulgação progressiva: o agente lê uma skill em três estágios, e cada estágio só é pago se for alcançado.

• Nível 1, sempre carregado. O nome e a descrição de cada skill instalada, cerca de 100 tokens por skill.
• Nível 2, quando acionado. O corpo do SKILL.md, com menos de 5.000 tokens.
• Nível 3, apenas quando necessário. Arquivos incluídos e scripts. Quando o agente executa um script, o código do script não entra no contexto, apenas sua saída.

Os números de tokens são aproximações da documentação, não contagens exatas.

Eis por que isso importa para sua conta. Digamos que você tenha instalado 20 skills. 20 × 100 = 2.000 tokens viajam junto desde a primeira mensagem. Um agente reenvia seu contexto a cada passo (o exemplo de 20 passos mostra por quê), então uma sessão de 50 passos carrega 50 × 2.000 = 100.000 tokens de entrada em rótulos de skill. No DeepSeek-V4-Flash isso é $0.0015 nos preços atuais.

Agora o contrário. Se essas vinte skills fossem coladas como um único prompt grande, cada corpo ficaria em cada requisição: até 20 × 5.000 = 100.000 tokens por requisição, não por sessão. Essa diferença é o ponto central do carregamento sob demanda. Se o termo "janela de contexto" ainda é nebuloso, este explicador cobre o que a preenche.

Skills vivem no contexto, então o modelo por trás do agente precisa de espaço para elas. O DeepSeek-V4-Flash na CheapTokens (id deepseek-ai/DeepSeek-V4-Flash-0731) tem uma janela de contexto de 380K e até 32.768 tokens de saída por resposta, um preço a qualquer hora do dia e uma API compatível com OpenAI e Anthropic. Para o agente de terminal, siga como conectar o Claude Code à CheapTokens; para qualquer outra ferramenta, comece pela documentação. A página do modelo é esta.

Escreva uma skill mínima em dois minutos#

Ler fica mais fácil depois de escrever uma. Esta skill faz o agente escrever mensagens de commit em um formato fixo. No Claude Code, skills pessoais ficam em ~/.claude/skills/ e skills de projeto em .claude/skills/, então uma skill de projeto pode viajar com o repositório.

mkdir -p ~/.claude/skills/commit-message-style
nano ~/.claude/skills/commit-message-style/SKILL.md   # or any editor

Cole isto no arquivo:

---
name: commit-message-style
description: Writes git commit messages in this project's format. Use when the user asks to commit, to write a commit message, or to summarize staged changes.
---

# Commit message style

1. Run `git diff --staged` and read it.
2. First line: `type(scope): summary`, at most 72 characters. Types: feat, fix, docs, refactor, test.
3. Blank line, then up to three bullets that say why the change was made, not what changed.
4. Do not put file names in the first line.

Agora abra o agente em um repositório com alterações em stage e peça: "escreva uma mensagem de commit para o que eu coloquei em stage". O agente vê a descrição, decide que corresponde, lê as quatro regras e as segue. Se ele ignorar a skill, olhe primeiro o description: ele precisa nomear a situação, aqui "commit", com as palavras que você realmente usaria.

Um detalhe: skills não sincronizam entre claude.ai, a API e o Claude Code. Uma skill que você criou em um lugar precisa ser adicionada aos outros separadamente.

Skill, AGENTS.md, MCP: qual é qual#

Esses três são confundidos o tempo todo. Um arquivo de regras como AGENTS.md ou CLAUDE.md é lido no início de uma sessão e contém fatos sobre o projeto (como esse arquivo pode dar errado em uma pasta Downloads). Um servidor MCP dá ao agente novas ferramentas e dados para acessar (MCP em linguagem simples). Uma skill é um procedimento: como fazer um tipo de trabalho, carregado quando esse trabalho surge.

Examine uma skill de terceiros antes de instalar#

Uma skill é texto que o agente segue e, às vezes, código que o agente executa. A documentação diz para usar skills apenas de fontes confiáveis, auditar cada arquivo incluído (SKILL.md, scripts, recursos) e procurar chamadas de rede ou acesso a arquivos inesperados. Skills que buscam URLs externas são mais arriscadas. No Claude Code, uma skill tem o mesmo acesso à rede que qualquer programa no seu computador, então trate a instalação como instalar um software.

Um bom exemplar é universal-modder, um kit de ferramentas para modding de jogos. Seu README (verificado em 30 de outubro de 2026) descreve um conjunto de skills licenciado sob MIT no formato Agent Skills, uma CLI em Python chamada um, um servidor MCP para geração de assets via fal e uma base de conhecimento compartilhada de notas de campo. A skill principal, mod-any-game, cobre reconhecimento, engenharia reversa, geração de assets, testes no jogo e empacotamento. O README lista Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot e OpenCode como ferramentas suportadas, e diz que o kit se recusa a contornar anti-cheat ou DRM. No Claude Code ele é instalado com /plugin marketplace add rehan-remade/universal-modder, e a geração de assets precisa de uma chave de API fal separada.

Observe o que essa lista contém: skills, um programa de linha de comando e um servidor. Ler um único SKILL.md cobriria apenas uma fatia do que você está instalando. Então passe pelas peças:

A regra principal está em como armazenar uma chave de API com segurança. A página do repositório não mostra a data do último commit, então verifique há quanto tempo o projeto foi atualizado antes de confiar nele.