Skills de IA com Vibecoding e Terminal · Capítulo 6 de 12 · 30 min
Anatomia de uma Skill: Divulgação Progressiva em Três Níveis
O padrão Agent Skills da Anthropic, o SKILL.md como contrato e por que lazy loading é a chave da escalabilidade.
Este capítulo faz parte do curso gratuito Skills de IA com Vibecoding e Terminal.
Se o CLAUDE.md é a constituição do projeto, a Skill é a profissão do agente. Uma Skill é um diretório autocontido que ensina ao agente como executar uma tarefa específica -- 'auditar SEO de uma URL', 'gerar schema JSON-LD', 'validar acentuação PT-BR'. A Anthropic lançou o formato Agent Skills em 2025 e depois abriu a especificação em agentskills.io. Em outubro de 2026, Claude Code, Codex (CLI e app do ChatGPT), Gemini CLI e Antigravity leem o mesmo SKILL.md: uma skill de briefing de campanha escrita uma vez roda nos quatro.
O princípio central é divulgação progressiva (progressive disclosure). O agente não carrega a skill inteira na janela de contexto -- carrega apenas o que precisa, quando precisa. Isso muda a escala: um agente pode ter 50 ou 500 skills instaladas sem estourar contexto, porque cada uma só se 'acorda' quando a descrição bate com a intenção do usuário.
Os três níveis de divulgação
Nível 1 -- Metadados (~100 tokens). O agente carrega apenas o name e o description da skill, do frontmatter YAML do SKILL.md. Funciona como 'menu' de capacidades. Uma skill chamada 'seo-audit' com descrição 'Audita SEO técnico de uma URL verificando meta tags, headings, schema e performance' gasta 20 tokens.
Nível 2 -- Instruções completas (a especificação recomenda menos de 5.000 tokens e menos de 500 linhas no SKILL.md). Quando a demanda do usuário bate semanticamente com a descrição, o agente lê o corpo do SKILL.md completo -- lógica, fluxo, exemplos de uso. Só a partir deste nível o agente tem contexto detalhado.
Nível 3 -- Recursos executáveis. Scripts (.py, .sh, .js), schemas (.json), templates (.md) dentro da pasta da skill são lidos sob demanda. Se o SKILL.md menciona 'use o script validators/accent.py', o agente abre o arquivo apenas quando precisar rodá-lo.
# Estrutura de diretorios de uma skill completa
seo-audit/ # Nome da skill = nome do diretorio
|-- SKILL.md # Contrato obrigatorio (metadata + logica)
|-- scripts/ # Executaveis (Python/Node/Bash)
| |-- audit.py # Script principal
| `-- requirements.txt # Dependencias
|-- templates/ # Templates de output
| |-- report.md
| `-- schema.json
|-- references/ # Docs de referencia
| |-- seo-checklist.md
| `-- schema-org-map.json
`-- tests/ # Validacao automatizada
`-- test_audit.py
# O agente:
# 1. Sabe que essa skill existe (Nivel 1, le frontmatter)
# 2. Le SKILL.md quando a tarefa pede auditoria (Nivel 2)
# 3. Abre scripts/audit.py apenas na execucao (Nivel 3)---
name: seo-audit
description: Audita SEO técnico e prontidão para buscadores com IA (GEO) de uma URL -- meta tags, headings, imagens sem alt, schema JSON-LD, canonical e acesso de robôs de IA. Use quando pedirem auditar, verificar SEO, checar GEO ou analisar uma página por URL. Não use para revisar tom de voz.
license: MIT
compatibility: Requer Python 3.11+, requests e beautifulsoup4, com acesso à internet
metadata:
author: time-de-marketing
version: "1.2"
allowed-tools: Bash(python:*) Read Write
---
# SEO Audit Skill
## Quando usar
O usuário fornece uma URL e pede auditoria, análise ou verificação.
Não use para auditoria de conteúdo (voz, clareza) -- isso é a
skill `content-voice-guard`.
## Passos
1. Execute `python scripts/audit.py <URL>` e capture o JSON de saída.
2. Leia `templates/report.md` como modelo.
3. Preencha o modelo com os dados do JSON, mantendo a estrutura.
4. Destaque problemas críticos (title ausente, H1 duplicado,
mais de 30% das imagens sem alt, robots.txt bloqueando robôs de IA).
5. Salve o relatório em `out/audit-<hostname>-<data>.md`.
6. Devolva no chat um resumo de 5 itens.
## Critérios de sucesso
- Relatório salvo no caminho esperado
- Zero falso positivo em imagens decorativas com alt="" proposital
(confira aria-hidden antes de apontar).
# Os campos triggers e requirements, comuns em tutoriais de 2025,
# não existem na especificação: gatilhos vão na description e
# requisitos vão em compatibility.Onde cada terminal procura skills (outubro de 2026)
| Ferramenta | Pasta do projeto | Pasta pessoal | Como chamar |
|---|---|---|---|
| Claude Code | .claude/skills/ | ~/.claude/skills/ | /nome-da-skill ou automático pela description |
| Codex CLI | .agents/skills/ (da pasta atual até a raiz do repositório) | ~/.agents/skills/ | $nome-da-skill, /skills ou automático |
| Gemini CLI | .gemini/skills/ ou .agents/skills/ | ~/.gemini/skills/ ou ~/.agents/skills/ | /skills list e ativação automática com confirmação |
| Antigravity CLI | .agents/skills/ | ~/.gemini/antigravity-cli/skills/ | /nome-da-skill ou automático |
A pasta .agents/skills/ é o ponto de encontro: Codex, Gemini CLI e Antigravity leem dali. Para o Claude Code, crie um link de .claude/skills/ para ela, como no capítulo "Terminal e Claude Code: o Setup que Vai Servir para os Próximos Anos".
Distribuição: skills prontas chegam empacotadas em plugins. No Claude Code, o marketplace oficial da Anthropic já vem adicionado e /plugin abre a aba Discover; no Codex, $skill-installer instala skills curadas e plugins levam skills para o ChatGPT; no Gemini CLI, gemini skills install aceita um repositório Git.
Descriptions fazem o agente achar a skill certa. O campo description do frontmatter é o que o agente usa para bater com a intenção do usuário. Escreva como se fosse regra SEO: comece com verbo, mencione palavras-chave que o usuário provavelmente usaria ('auditar SEO', 'validar acentuação'), liste quando não usar. Descriptions vagas levam o agente a ignorar a skill mesmo quando ela seria perfeita.
Cuidado com overlap semântico. Duas skills com descriptions parecidas competem pela mesma intenção, e o agente pode escolher a errada silenciosamente. Antes de criar uma skill nova, liste as existentes e confirme que não há sobreposição. Se houver, ou una as duas ou use um discriminante explícito ('use esta para imagens, a outra para vídeo').
Campos do frontmatter: o que vale em qualquer terminal e o que é extensão de uma ferramenta
| Campo | Onde vale | Para que serve no marketing |
|---|---|---|
| name | Especificação aberta (obrigatório) | Até 64 caracteres, minúsculas, números e hífens; igual ao nome da pasta |
| description | Especificação aberta (obrigatório) | Até 1.024 caracteres; diz o que faz e quando usar, com as palavras que o time digita |
| license, compatibility, metadata | Especificação aberta | Licença, requisitos (Python, acesso à internet) e versão da skill |
| allowed-tools | Especificação aberta (experimental) | Libera ferramentas sem pedir aprovação durante a skill |
| disable-model-invocation, argument-hint, arguments | Só Claude Code | Skill que só roda quando alguém digita /nome, com argumentos nomeados |
| context: fork, agent, model, effort | Só Claude Code | Rodar a skill num subagente isolado, com modelo e esforço próprios |
| hooks, paths | Só Claude Code | Validação automática enquanto a skill está ativa; ativação por pasta |
| agents/openai.yaml | Só Codex | Nome de exibição, ícone e allow_implicit_invocation: false |
Regra prática: escreva o SKILL.md só com os campos da especificação e acrescente os extras de cada ferramenta quando precisar. O Claude Code aceita extensões próprias; o upload no claude.ai pode recusar campos fora da especificação. Separe os metadados de cada ferramenta e teste o pacote no destino antes de distribuir.
Se a figura ultrapassar a área visível, deslize para os lados. Pelo teclado, foque a figura e use as setas.
Se a figura ultrapassar a área visível, deslize para os lados. Pelo teclado, foque a figura e use as setas.
Valide antes de compartilhar. O comando skills-ref validate ./minha-skill, da biblioteca de referência da especificação, confere nome, tamanho da description e frontmatter. No Claude Code, claude plugin validate .claude/skills aponta YAML que não abre, e /skill-doctor, comando que chegou em setembro de 2026, mostra quanto contexto cada skill ocupa e quais ninguém usa.
Você entende os três níveis de divulgação progressiva, sabe a estrutura de diretório de referência de uma skill e reconhece o SKILL.md como contrato vivo entre humano, agente e ecossistema.
Seu caderno neste capítulo
Abrir o caderno completoSelecione um trecho do capítulo para destacar ou anotar. Nos vídeos e áudios, use Anotar este momento. No teclado, selecione com Shift e as setas e use Alt+Shift+D para destacar ou Alt+Shift+N para anotar.
Salvo neste navegador. Entre na sua conta para levar o caderno a outros aparelhos.
Entre na sua conta para compartilhar o que aprendeu e convidar alguém para estudar com você.
Conexões deste capítulo
Veja o que estudar antes e para onde seguir depois, explore os conceitos e compare abordagens em outros cursos. Sugestões marcadas como “sugerido pelo grafo” vêm dos assuntos em comum, não do índice do curso.
Estude antes
- CursoClaude Code CLI: Programação com IA
- Agent Mode: a IA que executa sob supervisãosugerido pelo grafoApresenta o conceito “Agent”, usado em “Anatomia de uma Skill: Divulgação Progressiva em Três Níveis”.
- CursoSetup Completo: do zero ao Claude Codesugerido pelo grafo5 capítulos de “Skills de IA com Vibecoding e Terminal” usam conceitos apresentados em “Setup Completo: do zero ao Claude Code”.
- CursoVibecoding para SEOsugerido pelo grafo3 capítulos de “Skills de IA com Vibecoding e Terminal” usam conceitos apresentados em “Vibecoding para SEO”.
Depois, siga para
- Instalar e invocar skills de vídeo no Claude Codesugerido pelo grafoApresenta o conceito “Skill (Agent Skill)”, usado em “Instalar e invocar skills de vídeo no Claude Code”.
- Configurar ambiente, skills e o contêiner de contextosugerido pelo grafoApresenta o conceito “Skill (Agent Skill)”, usado em “Configurar ambiente, skills e o contêiner de contexto”.
- Aplicar direção de arte, UX writing e padrões de códigosugerido pelo grafoApresenta o conceito “Skill (Agent Skill)”, usado em “Aplicar direção de arte, UX writing e padrões de código”.
- Construir o projeto final, medir a cara de IA e revisarsugerido pelo grafoApresenta o conceito “Skill (Agent Skill)”, usado em “Construir o projeto final, medir a cara de IA e revisar”.
Conceitos deste capítulo
O mesmo assunto em outros cursos
- Setup de Vibecoding no MacSkills, plugins e barra de status — deixar o Claude Code com a sua caraExaminar conexões de Skills, plugins e barra de status — deixar o Claude Code com a sua cara
- Vídeo com IA: Claude Code, Codex e ElevenLabsInstalar e invocar skills de vídeo no Claude CodeExaminar conexões de Instalar e invocar skills de vídeo no Claude Code
- Claude Code CLI: Programação com IARevisar o plano antes de agir e ligar suas ferramentasExaminar conexões de Revisar o plano antes de agir e ligar suas ferramentas
- Vibecoding para SEOSetup do Ambiente: Claude Code + Cursor em 15 MinutosExaminar conexões de Setup do Ambiente: Claude Code + Cursor em 15 Minutos
Leve uma ideia para a prática
Escolha uma atividade no painel e volte a este curso quando quiser.
Atividades e evolução ficam reunidas no painel da sua conta.