📄 O que é uma agent skill
Uma agent skill é, na prática, um único arquivo: SKILL.md. Ele tem duas partes — um frontmatter YAML com os campos obrigatórios name e description, e um corpo em Markdown com a instrução em si. Quando o contexto da conversa bate com a descrição, o agente lê esse arquivo e incorpora a instrução ao próprio comportamento — como se você tivesse explicado a convenção na hora.
💡 Conceito central
Skill não é um plugin que roda código. É conhecimento empacotado em texto que o agente passa a "saber". O canônico aqui é o skill-creator da Anthropic, que define a estrutura SKILL.md como padrão.
- •Formato: Markdown com frontmatter YAML
- •Obrigatórios: name + description
- •Ativação: automática, por relevância de contexto
- •Distribuição: versionada via git, instalável via skills.sh
SKILL.md mínimo:
--- name: react-best-practices description: Aplica boas práticas React ao gerar ou revisar componentes. Use quando o usuário cria ou edita arquivos .jsx/.tsx. --- # React Best Practices Ao gerar componentes React, sempre: - Use componentes funcionais com hooks - Prefira TypeScript com tipos explícitos - Siga nomenclatura PascalCase para componentes
🎯 Dica prática
Pense em skill como a memória persistente do agente. Sem ela, você reexplica as convenções toda sessão. Com ela, o agente já chega sabendo — e o conhecimento fica num arquivo que todo o time compartilha.
🧠 Instrução, não script
O erro mais comum de quem vem de programação é tratar skill como função. Skill não executa — ela é lida. Não há "chamada"; há ativação por contexto. O agente compara a situação atual com a description de cada skill instalada e, quando há relevância, aplica a instrução. Você descreve o quê e quando, não os passos mecânicos.
✗ Pensar como script
- ✗"Passo 1, passo 2, passo 3..." rígido
- ✗Espera que a skill "rode" e retorne
- ✗Description vaga ("ajuda com código")
- ✗Assume controle de fluxo determinístico
✓ Pensar como instrução
- ✓Descreve o comportamento e o porquê
- ✓Confia que o agente aplica no momento certo
- ✓Description diz O QUE faz E QUANDO usar
- ✓Deixa espaço para o julgamento do agente
A description é o gatilho
Como a ativação é por contexto, a description é literalmente o que decide se a skill dispara. Ela precisa dizer o que faz e quando usar, e ser até um pouco "pushy" — agentes tendem a subdisparar skills.
Por isso o corpo da skill deve explicar o porquê das coisas, em vez de empilhar MUSTs em maiúscula. Instrução com razão é seguida melhor do que ordem seca.
🏆 Por que o formato venceu
Havia muitos jeitos de ensinar comportamento a um agente — arquivos proprietários, configs específicas, plugins binários. O que pegou foi o mais simples: Markdown puro. Por três razões que se reforçam: portabilidade entre agentes, versionamento via git e um efeito de rede medido em milhões de instalações.
Portável entre 50+ agentes
Markdown é o menor denominador comum. Uma skill escrita uma vez roda em Claude Code, Cursor, Copilot, Codex e dezenas de outros. Seu investimento não fica preso a uma ferramenta.
Versionável via git
Por ser texto, a skill entra no fluxo de trabalho que times já dominam: PRs, diffs, review, histórico. Mudou a convenção? É um commit. Nada de formato binário opaco.
53,9M de installs somados
O efeito de rede já aconteceu: o skills.sh soma 53,9 milhões de instalações. Quando todo mundo publica no mesmo formato, o formato vira o padrão de fato — e reforça a si mesmo.
💡 Por que isso importa pra você
Escrever uma skill é uma das raras coisas em IA com baixo risco de "vendor lock-in". O artefato é um .md. Se a ferramenta mudar amanhã, sua skill continua valendo.
🔀 Skill vs prompt vs CLAUDE.md vs MCP vs subagente
Skill não substitui as outras camadas — convive com elas. O erro é transformar tudo em skill, ou nada. Cada mecanismo resolve um problema diferente. A tabela mental abaixo te ajuda a escolher.
💬 Prompt
Efêmero, vale só naquela mensagem. Use para algo pontual que você não vai repetir. Não escala, não versiona.
📌 CLAUDE.md (regras do projeto)
Contexto sempre ativo daquele repositório. Use para regras que valem em toda sessão do projeto. Custa tokens o tempo todo — por isso só o essencial.
🔌 MCP
Dá ao agente ferramentas e dados (chamar uma API, ler um banco). É capacidade, não conhecimento. Skill diz como agir; MCP dá o que usar.
🤖 Subagente
Um executor isolado com seu próprio contexto, para delegar uma tarefa pesada sem poluir a conversa principal. É arquitetura de execução, não instrução reutilizável.
🧩 Skill
Conhecimento reutilizável que dispara por contexto. Use quando há um comportamento que se repete em muitas situações e que vale carregar só quando relevante — sem ocupar contexto o tempo todo (diferente do CLAUDE.md).
Regra de bolso para escolher:
é só desta vez? -> prompt vale sempre, neste repo? -> CLAUDE.md preciso de uma ferramenta? -> MCP quero delegar execução? -> subagente conhecimento que se repete? -> skill
💡 Atenção ao custo de contexto
A grande vantagem da skill sobre o CLAUDE.md é o carregamento sob demanda: só o name+description fica sempre no contexto; o corpo entra apenas quando a skill dispara. Conhecimento extenso que nem sempre é necessário deve virar skill, não regra de projeto.
📦 skills.sh como registry — o "npm de skills"
Se a skill é o "pacote", o skills.sh é o registry — o npm desse mundo. Ele cataloga skills por repositório, mostra a contagem de instalações (o melhor sinal público de qualidade e confiança) e instala com um comando.
📦 npm (Node.js)
- →
npm install react— instala pacote - →downloads/semana — sinal de adoção
- →registry central (npmjs.com)
- →package.json — registro local
🧩 skills.sh (agentes)
- →
npx skills add owner/repo— instala skill - →install count — sinal de adoção
- →catálogo central (skills.sh)
- →repos no GitHub — fonte versionada
Fluxo de uso do catálogo:
# 1. descobrir no leaderboard / buscar npx skills find react # 2. instalar pelo caminho owner/repo npx skills add vercel-labs/skills # 3. listar o que está instalado npx skills list
O install count é o seu radar de qualidade
Como qualquer registry aberto, há muita skill ruim ao lado de ótimas. A contagem de instalações é o filtro mais barato: a skill mais instalada do catálogo, find-skills (vercel-labs/skills), tem 1.802.925 installs. frontend-design (anthropics/skills) tem 488.299.
Não é prova de qualidade, mas é um forte indicador de que muita gente confiou — e continuou usando.
👥 Quem publica
O ecossistema não é jardim murado de uma empresa só. Publicam grandes players e milhares da comunidade — ao todo 5.075 repos fonte alimentam o catálogo. Isso é o que dá ao formato sua força: ninguém é dono dele.
🟢 vercel-labs
Dona de campeãs de instalação como find-skills (1,8M), vercel-react-best-practices (443k) e web-design-guidelines (358k). Foco em web/frontend e ferramentas de agente.
🟢 anthropics
Publica o skill-creator (246k) — o canônico de como escrever skills — e frontend-design (488k). É a referência de estrutura do formato.
🟢 microsoft
Via azure-skills, domina DevOps/Cloud: microsoft-foundry (360k), azure-ai (358k) e família azure-deploy/diagnostics/prepare.
🟢 comunidade
A maioria dos repos. Exemplos: obra/superpowers (test-driven-development, 107k), larksuite/cli (lark-slides, 139k), supabase, stripe, coreyhaines31.
Anatomia de um caminho de skill no catálogo:
vercel-labs/skills # repo fonte (owner/repo) └── find-skills # a skill (1.802.925 installs) └── SKILL.md # o arquivo de instrução
💡 O que isso te diz
Os grandes nomes dominam os tópicos mais quentes (web, cloud, agentes). Sobra espaço enorme nos nichos que eles não cobrem — e é exatamente onde a sua skill da comunidade pode liderar. O mapa completo é o tema do Módulo 1.2.
✅ Resumo do Módulo
Próximo:
1.2 — 🗺️ O mapa do skills.sh: 39k skills, a lei de potência e os 16 grupos. Onde estão as oportunidades e por que a maioria das skills quase não é instalada.