A Vercel quer transformar skills de agentes em algo mais próximo de pacotes de software: fáceis de encontrar, comparar, instalar, atualizar e remover. O projeto vercel-labs/skills é uma CLI para esse ecossistema aberto. E a skill find-skills, incluída no próprio repositório, define um detalhe que faz diferença: um agente não deve indicar qualquer instrução encontrada numa busca; ele deve avaliar popularidade, procedência e reputação antes de recomendar ou instalar.
Isso parece uma regra simples, mas ataca um problema crescente. À medida que assistentes de programação acumulam plugins, prompts, arquivos SKILL.md e ferramentas externas, instalar uma “habilidade” passa a ter consequências reais: ela pode mudar como o agente lê arquivos, planeja tarefas, escreve código, chama comandos e conduz revisões. Descoberta sem critério vira cadeia de suprimentos de prompts.
O que são skills de agentes
Skills são instruções reutilizáveis que ensinam um agente a executar uma tarefa específica. Podem trazer processo de revisão de pull request, padrões de acessibilidade, convenções para uma biblioteca, templates de documentação, passos de deploy ou regras de segurança. Elas não acrescentam inteligência ao modelo por si só; acrescentam contexto operacional e uma forma repetível de trabalhar.
O projeto da Vercel se apresenta como a CLI do ecossistema aberto de agent skills. O comando npx skills instala, lista, busca, atualiza e remove skills. A documentação atual declara suporte para Claude Code, Codex, Cursor, OpenCode e mais de 75 ambientes. Em vez de cada ferramenta criar um formato isolado, a proposta é dar um mecanismo comum para distribuir arquivos de skill a diretórios reconhecidos por diferentes agentes.
| Comando | O que faz | Quando usar |
|---|---|---|
npx skills find [consulta] | Busca skills por palavra-chave | Quando o agente ou a equipe precisa de uma capacidade especializada |
npx skills add <fonte> | Instala uma skill ou pacote de skills | Após revisar fonte, escopo e destino da instalação |
npx skills use <fonte>@<skill> | Gera prompt ou chama agente sem instalar | Para testar uma skill antes de persistir arquivos no projeto |
npx skills list | Lista skills instaladas | Para auditoria e entendimento do ambiente |
npx skills check | Verifica atualizações disponíveis | Antes de atualizar uma instalação existente |
npx skills update | Atualiza skills instaladas | Depois de revisar mudanças e compatibilidade |
A skill find-skills: o filtro antes da instalação
O arquivo skills/find-skills/SKILL.md é menos uma ferramenta de busca e mais uma política de recomendação. Ele orienta o agente a identificar primeiro o domínio e a tarefa: React e performance não são o mesmo que revisão de PR; deploy não é o mesmo que Kubernetes; documentação não é o mesmo que changelog.
Em seguida, ele sugere consultar o leaderboard do diretório skills.sh antes de disparar uma busca por CLI. A razão é pragmática: skills populares e mantidas por organizações reconhecidas costumam ser mais auditáveis do que o primeiro resultado de uma pesquisa ampla. Só depois vem o comando:
# Procurar skills por um problema específico
npx skills find react performance
# Procurar dentro de um mantenedor específico
npx skills find pr review --owner vercel-labsO ponto mais forte do documento está nas regras de validação. Antes de recomendar uma skill, o agente deve conferir contagem de instalações, reputação da fonte e estrelas do repositório no GitHub. A recomendação do próprio arquivo é priorizar skills com mais de mil instalações, ter cautela abaixo de cem e desconfiar de repositórios com menos de cem estrelas. Esses números não provam segurança, mas funcionam como um filtro contra abandono, spam e instruções sem histórico.
Por que isso importa para segurança
Uma skill pode ser apenas um bom checklist. Também pode instruir um agente a varrer arquivos sensíveis, instalar dependências, executar comandos remotos ou alterar infraestrutura. Por isso, skills devem ser tratadas como código de terceiros: com procedência, revisão, permissões mínimas e atualização controlada.
A Vercel inclui sinais úteis, mas não uma garantia absoluta. Uma skill muito instalada pode ter uma atualização problemática; uma fonte oficial pode ser comprometida; um repositório com poucas estrelas pode ser legítimo e especializado. Popularidade deve orientar priorização, não substituir leitura do conteúdo. Antes de instalar, vale abrir o SKILL.md, verificar arquivos auxiliares, identificar chamadas de shell e entender para quais diretórios a CLI vai copiar ou criar links.
Instalação: projeto ou ambiente global?
O README do projeto exige Node.js 22.20 ou superior. Por padrão, uma instalação é feita no projeto atual. A opção -g torna a skill disponível globalmente, para todos os projetos do usuário. A diferença é importante para governança.
# Instalação no projeto atual: mais auditável e versionável
npx skills add vercel-labs/agent-skills
# Escolher uma skill e um agente de destino
npx skills add vercel-labs/agent-skills \
--skill web-design-guidelines \
-a claude-code
# Instalação global: use apenas quando o processo for aprovado
npx skills add vercel-labs/agent-skills@web-design-guidelines -g -yPara equipes, a instalação local costuma ser a escolha mais segura. Ela deixa os arquivos próximos ao repositório, permite revisão no Git e reduz surpresas entre máquinas. Uma instalação global é conveniente, mas pode fazer dois projetos diferentes obedecerem a uma mesma regra invisível no código-fonte.
Onde as skills são instaladas
A CLI detecta agentes disponíveis e direciona as skills para caminhos compatíveis. Claude Code, por exemplo, usa .claude/skills/ no projeto e ~/.claude/skills/ para o usuário. Codex, Cursor e vários outros usam .agents/skills/ localmente ou ~/.agents/skills/ no perfil. Hermes Agent aparece na lista de ambientes suportados, com .hermes/skills/ por projeto e ~/.hermes/skills/ no nível global.
Essa compatibilidade é útil, mas cria uma obrigação: a equipe precisa saber qual diretório tem precedência no seu harness. Uma skill instalada globalmente pode influenciar comportamentos que o repositório não declara. Em projetos sensíveis, liste skills ativas em onboarding, CI ou documentação operacional.
Testar uma skill antes de instalar
O comando use oferece uma alternativa para quem quer avaliar o conteúdo antes de torná-lo persistente. Com um agente compatível, ele pode iniciar o agente com aquela skill. Sem --agent, a CLI imprime o prompt. É uma forma prática de inspecionar o que será entregue ao modelo.
# Executa ou prepara uma sessão com a skill sem instalar arquivos no projeto
npx skills use vercel-labs/agent-skills@web-design-guidelines \
--agent claude-codePara uma auditoria real, não pare no prompt final. Verifique a origem Git, o commit ou release utilizado, instruções em arquivos referenciados e permissões concedidas ao agente. A skill pode parecer inofensiva no frontmatter, mas apontar para scripts, templates ou comandos adicionais.
Experimental: sincronizar skills que vêm com dependências npm
O repositório também documenta comandos experimentais. O experimental_sync procura skills distribuídas dentro de dependências npm e as conecta ao projeto. Isso é útil quando uma biblioteca fornece instruções especializadas para um agente trabalhar com ela, mas deve ser tratado com cuidado: atualizações de dependências podem alterar instruções que passam a chegar ao agente.
npm install -D skills agent-browser
npx skills experimental_sync -yO próprio README marca recursos com prefixo experimental_ como prévias: nomes, opções e comportamento podem mudar ou desaparecer. Em produção, fixe versões de dependência, registre o resultado em lockfiles e evite rodar sincronização automática sem diff e revisão.
✅ O que a CLI resolve bem
- Descoberta estruturada: oferece um diretório e uma CLI para não depender apenas de recomendações soltas em redes sociais.
- Portabilidade: mapeia skills para vários agentes e caminhos de instalação.
- Ciclo de vida: inclui listagem, verificação de atualização, update e remoção.
- Uso sem instalação: permite testar uma skill antes de copiar arquivos para o projeto.
- Critério de recomendação:
find-skillsformaliza a verificação de popularidade e procedência.
⚠️ O que ela não resolve sozinha
- Não certifica segurança. Instalações, estrelas e origem conhecida são sinais, não auditoria completa.
- Não entende o risco do seu repositório. Somente a equipe sabe quais secrets, ambientes e comandos são aceitáveis.
- Não elimina dependência de Node. A versão mínima exigida é Node.js 22.20.
- Não estabiliza recursos experimentais. Comandos experimentais podem mudar.
- Não substitui um processo de revisão. Uma skill deve entrar no projeto com o mesmo cuidado de uma dependência ou ação de CI.
Checklist seguro antes de adicionar uma skill
- Pesquise o problema com termos específicos, não apenas “testing” ou “deploy”.
- Compare a contagem de instalações e o mantenedor no diretório.
- Abra o repositório e leia o
SKILL.mdcompleto. - Procure scripts, chamadas de shell, downloads, uso de MCP e acesso a arquivos fora do projeto.
- Prefira instalação local e faça commit dos arquivos de configuração relevantes.
- Teste em branch ou repositório de laboratório antes de liberar para o time.
- Antes de atualizar, rode
npx skills check, examine o changelog e revise o diff.
Vale a pena?
O find-skills é pequeno, mas expressa uma ideia importante: agentes não deveriam ampliar suas capacidades por impulso. A Vercel está tentando criar uma camada de distribuição para skills semelhante ao que registries fizeram por bibliotecas — com busca, instalação, atualização e compatibilidade entre ferramentas.
Na análise do NoticIA, o valor não está em instalar dezenas de skills. Está em ter uma forma mais consciente de escolher poucas habilidades que realmente elevem a qualidade do trabalho. Para equipes que usam Claude Code, Codex, Cursor ou Hermes, a prática certa é simples: descubra, valide, teste, versiona e só então confie.
Descubra mais sobre noticiAI
Assine para receber nossas notícias mais recentes por e-mail.
