🧩 O que são Agent Skills
Agent skills são arquivos de instrução no formato SKILL.md que ensinam comportamentos específicos a agentes de IA. Pense nelas como "plugins de conhecimento" — cada skill encapsula um conjunto de instruções que o agente segue quando a situação é relevante.
💡 Conceito Central
Uma skill não é um script que executa automaticamente — é uma instrução que o agente lê e incorpora ao seu comportamento. Quando o contexto bate com a descrição da skill, o agente a aplica naturalmente.
- •Formato: Arquivo Markdown com frontmatter YAML
- •Ativação: Automática, baseada no contexto da conversa
- •Portabilidade: Funciona em múltiplos agentes
- •Reutilização: Pode ser compartilhada via GitHub
Exemplo mínimo de SKILL.md:
--- name: react-best-practices description: Aplica boas práticas React ao gerar ou revisar código --- # React Best Practices Quando gerando componentes React, sempre: - Use componentes funcionais com hooks - Prefira TypeScript com types explícitos - Siga o padrão de nomenclatura PascalCase
🎯 Dica Prática
Pense em skills como a memória persistente que você sempre quis ter com seu agente. Sem skills, você explica as convenções do projeto toda sessão. Com skills, o agente já sabe — e mantém esse conhecimento atualizado via npx skills update.
📦 A Analogia com npm
A analogia mais precisa para entender o Skills CLI é compará-lo ao npm. Assim como npm gerencia pacotes Node.js que adicionam funcionalidades ao seu projeto, o Skills CLI gerencia "pacotes de habilidades" que adicionam capacidades ao seu agente de IA.
📦 npm (Node.js)
- →
npm install react— instala pacote - →
npm install -g eslint— instalação global - →
npm list— lista pacotes - →
npm update— atualiza pacotes - →package.json — registro local
🧰 Skills CLI (Agentes)
- →
npx skills add owner/repo— instala skill - →
npx skills add -g owner/repo— instalação global - →
npx skills list— lista skills - →
npx skills update— atualiza skills - →skill-lock.json — registro local
Diferenças importantes
Ao contrário do npm, skills são instaladas como symlinks por padrão (não cópias). Isso significa que ao atualizar o repositório fonte, todas as instalações são atualizadas automaticamente com npx skills update.
Skills também são instaladas em pastas específicas de cada agente — não em node_modules. O CLI sabe exatamente onde cada agente procura suas instruções.
🌐 skills.sh e agentskills.io
O ecossistema de agent skills é suportado por duas plataformas essenciais: skills.sh (o diretório público de skills) e agentskills.io (a especificação oficial do formato SKILL.md).
skills.sh — O Diretório
Marketplace público de skills
Cataloga repositórios de skills com contagem de instalações (install count). O leaderboard mostra as skills mais usadas — um bom indicador de qualidade e confiabilidade. Skills com 100K+ instalações são consideradas maduras.
agentskills.io — A Especificação
Documentação oficial do formato
Hospeda a especificação oficial do formato SKILL.md: campos obrigatórios, campos opcionais, semântica de cada campo e como agentes devem processar o arquivo. Referência definitiva para criar skills compatíveis.
💡 Como usar o skills.sh
1. Acesse skills.sh e navegue pelo leaderboard
2. Encontrou algo interessante? Copie o caminho owner/repo
3. Execute: npx skills add owner/repo
Ou use o CLI diretamente: npx skills find react
🎯 Agentes Genéricos vs Especialistas
Um agente de IA sem skills é como um desenvolvedor júnior no primeiro dia de trabalho: capaz, mas sem conhecimento específico do seu contexto. Com skills, ele se torna um especialista no seu stack, nas suas convenções e nos processos do seu time.
✗ Sem Skills (Genérico)
- ✗Você explica as convenções toda sessão
- ✗O agente não sabe seu stack favorito
- ✗Padrões de código inconsistentes
- ✗Conhecimento não é compartilhado no time
- ✗Resultado depende de qual prompt você usou
✓ Com Skills (Especialista)
- ✓Convenções aplicadas automaticamente
- ✓Conhece seu stack, bibliotecas e padrões
- ✓Código consistente sempre
- ✓Skills versionadas e compartilhadas via Git
- ✓Resultado previsível e reproduzível
Casos de uso reais
- •Time de frontend: Skill com convenções de componentes React, patterns de TypeScript e guidelines de acessibilidade
- •DevOps: Skill com padrões de Dockerfile, configurações de CI/CD e práticas de segurança
- •Equipe de dados: Skill com convenções de SQL, padrões de pipeline e documentação de schemas
🔧 Filosofia Modular e Reutilizável
O design do Skills CLI é guiado por três princípios fundamentais: atomicidade (cada skill tem uma responsabilidade), composição (múltiplas skills trabalhando juntas) e portabilidade (funciona em qualquer agente compatível).
Os três princípios
Atomicidade
Uma skill, uma responsabilidade. A skill react-best-practices cuida apenas de React. A skill git-commit-style cuida apenas do formato dos commits. Skills pequenas são mais fáceis de manter e testar.
Composição
Instale múltiplas skills para criar um agente completo. react-best-practices + typescript-strict + accessibility-guidelines = agente frontend completo.
Portabilidade
Skills escritas com campos padrão funcionam em Claude Code, Cursor, Copilot e 47+ outros agentes. Seu investimento não fica preso em um único ecossistema.
💡 Dica de Design
Quando criar uma skill, se você estiver tentado a nomear algo como "tudo-sobre-react", divida em skills menores. Uma skill de 50 linhas será mais eficaz do que uma skill de 500 linhas — o agente absorve melhor instruções focadas.
🏢 Vercel Labs e a Origem do Projeto
O Skills CLI foi criado pelo Vercel Labs, o braço de experimentação e inovação da Vercel. O projeto nasceu da necessidade real de padronizar como times de desenvolvimento usam agentes de IA — resolvendo a fragmentação entre diferentes ferramentas.
A história por trás
Antes do Skills CLI, times que usavam múltiplos agentes tinham o mesmo problema: instruções duplicadas, inconsistentes e difíceis de manter. Um time que usava Claude Code, Cursor e Copilot precisava manter três conjuntos de instruções separados.
O Skills CLI resolve isso com um formato único (SKILL.md) e um CLI que sabe onde instalar as instruções para cada agente. Uma skill, múltiplos destinos.
🔓 Open Source
O projeto está disponível em github.com/vercel-labs/skills. Contribuições são bem-vindas — desde correções de bugs até novos adaptadores de agentes.
🚀 Status Atual
Em rápida evolução. Novos agentes são adicionados regularmente. A especificação agentskills.io garante compatibilidade entre versões.
✅ Resumo do Módulo
Próximo Módulo:
1.2 — 📄 Anatomia de um SKILL.md — Aprenda a estrutura completa: frontmatter, campos obrigatórios e como escrever instruções eficazes