[MCP·Skill #2] Guia de Skills de IA: comandos e gatilhos

Ao usar ferramentas de programação com IA, você acaba repetindo as mesmas instruções. “Use este formato nas mensagens de commit”, “siga este checklist antes do deploy” e coisas do tipo.

Explicar tudo no prompt toda vez é demorado, mas colocar todas as regras permanentes em arquivos como CLAUDE.md ou AGENTS.md deixa o contexto de cada sessão mais pesado.

Skill resolve essa repetição. Em uma frase, é um módulo que empacota em arquivos os procedimentos e o conhecimento de uma tarefa específica e os carrega somente quando necessário.

Embora tenha começado como um recurso do Claude Code, hoje não pertence a uma ferramenta específica. Em dezembro de 2025, a Anthropic publicou a especificação como um padrão aberto chamado Agent Skills; desde então, mais de 30 ferramentas, incluindo OpenAI Codex, Gemini CLI, Cursor e VS Code(GitHub Copilot), adotaram o mesmo formato. Isso significa que um arquivo SKILL.md criado uma vez continua funcionando mesmo se você trocar de ferramenta.

Este artigo apresenta a estrutura de Skill, as duas formas de invocação —comandos de barra e gatilhos automáticos—, o suporte de cada ferramenta e a separação de responsabilidades em relação aos arquivos de regras permanentes. Os exemplos usam o Claude Code, que adotou o recurso primeiro, mas o conceito é igual em qualquer ferramenta.

Vamos começar pelo resumo dos pontos principais.

1. Skill é uma pasta de instruções que começa com um único arquivo SKILL.md e agora é um padrão aberto, independente da ferramenta.
2. Há duas formas de invocação: o comando de barra chamado diretamente pelo usuário e o gatilho automático acionado pelo modelo.
3. O conceito central é o carregamento progressivo. Normalmente, apenas o nome e a descrição são carregados; o corpo é lido no momento da execução.
4. Regras que sempre se aplicam ficam em arquivos como CLAUDE.md e AGENTS.md; procedimentos de tarefas específicas ficam em Skills.

---

A essência do Skill é uma pasta Markdown

A estrutura do Skill é simples: uma pasta com um arquivo SKILL.md já atende aos requisitos mínimos.

---
name: release-note
description: Redigir um rascunho de notas de versão. Usar quando houver solicitação de “notas de versão” ou “notas de deploy”
---

# Procedimento para redigir notas de versão
1. Reunir os commits posteriores à tag anterior
2. feat/fix/choreClassificá-los por categoria
3. Escrever o rascunho ordenando-os pelo impacto para o usuário

O name e a description do frontmatter no topo são os metadados de registro; o corpo abaixo é o procedimento propriamente dito. Você também pode adicionar documentos de referência ou scripts à pasta e expandi-la como um “manual de instruções + caixa de ferramentas”.

O padrão define somente este formato. Como cada ferramenta decide de qual pasta ler os arquivos, basta conhecer o caminho da ferramenta que você mais usa.

Ferramenta	Diretório de Skills
Claude Code	~/.claude/skills/ (global), 프로젝트/.claude/skills/ (projeto)
OpenAI Codex	.agents/skills/
Gemini CLI (Antigravity)	~/.gemini/antigravity/skills/

Na prática, é especialmente útil poder compartilhar o Skill com a equipe via git quando ele é colocado na pasta do projeto. O conhecimento de trabalho deixa de ser uma anotação pessoal e vira um ativo do repositório. Mesmo que os membros usem agentes de programação diferentes, todos podem ler o mesmo SKILL.md e compartilhar procedimentos sem padronizar as ferramentas.

---

Duas formas de invocação: manual e automática

O Skill é executado por dois caminhos.

Primeiro, o comando de barra. O usuário o digita diretamente, como em /release-note, para fazer uma invocação explícita. A pessoa decide quando executá-lo.

Segundo, o gatilho automático. O modelo analisa o conteúdo da conversa e decide sozinho: “Esta solicitação é responsabilidade daquele Skill”. A description do frontmatter é a base dessa decisão.

description não é uma explicação para pessoas, mas uma condição de roteamento para o modelo. Quanto mais especificamente você descrever “quando usar este Skill”, incluindo frases de gatilho, mais precisas serão as invocações automáticas.

Aqui, o design de carregamento progressivo(progressive disclosure) é importante. No início da sessão, apenas o nome e uma linha de description de cada Skill entram no contexto. O corpo completo só é lido quando o Skill é realmente invocado.

Graças a isso, mesmo registrando dezenas de Skills, o peso normal no contexto é mínimo. Essa é a diferença decisiva em relação a colocar todos os procedimentos nos arquivos de regras permanentes. Também é o principal motivo pelo qual vários fornecedores adotaram esse formato: a janela de contexto é um recurso caro para qualquer modelo.

---

Dividindo responsabilidades com os arquivos de regras permanentes

Cada ferramenta tem seu próprio “arquivo de regras sempre lido”: CLAUDE.md no Claude Code, AGENTS.md no Codex e rules no Cursor. É fácil confundi-los porque ambos são “instruções dadas ao modelo”. O critério é o momento de aplicação.

• Arquivo de regras permanentes(CLAUDE.md·AGENTS.md etc.): regras sempre aplicadas, em todas as sessões e tarefas. Convenções de código, proibições e contexto do projeto
• Skill: procedimentos necessários somente para tarefas específicas, como deploy, revisão e geração de documentação

Se, ao perguntar “isso precisa ser sempre verdadeiro?”, a resposta for sim, use o arquivo de regras permanentes; se só for verdadeiro em situações específicas, é um Skill. Tirar uma regra permanente do arquivo e colocá-la em um Skill faz com que ela desapareça quando o gatilho não ocorrer. Por outro lado, colocar todos os procedimentos no arquivo permanente desperdiça contexto.

---

Pontos difíceis na criação

Na prática, vale destacar dois problemas frequentes.

Quando o gatilho automático não funciona, quase sempre o problema está na description. Uma descrição abstrata como “assistente de criação de documentos” não ajuda o modelo a decidir quando usá-la. É mais eficaz listar frases que um usuário real provavelmente digitaria.

Quando o gatilho ocorre com frequência excessiva, inclua condições de exclusão na description, como “usar somente quando…; não usar para perguntas simples”.

Esse método funciona em qualquer ferramenta. A estrutura é a mesma no nível do padrão: quem decide pelo gatilho automático é o modelo, e o que ele vê é apenas uma linha de description.

---

Conclusão

Skill é, em essência, transformar prompts em funções. Em vez de copiar e colar instruções repetidas, você dá um nome a elas, salva-as e as carrega somente quando necessário. Agora, essa função também tem um formato padrão que não depende de uma ferramenta específica.

Se você já digitou a mesma instrução duas vezes, ela é uma candidata ao seu primeiro Skill. O SKILL.md criado hoje continuará com você no ano que vem, qualquer que seja o agente usado.

Continue lendo

• [Claude Code #2] /plan: modo de planejamento, alinhe o design antes de modificar