Guia Definitivo: skills.sh

O skills.sh é o diretório aberto de skills para agentes de codificação mais popular do ecossistema. Lançado pela Vercel em janeiro de 2026, ele transformou a forma como desenvolvedores descobrem, instalam e compartilham conhecimento procedural para seus agentes. Com mais de 91.000 skills indexadas e 385.000+ instalações totais rastreadas, é a referência quando o assunto é especializar agentes como Claude Code, Cursor, Kiro e Copilot.

Overview

O que é o skills.sh

O skills.sh é um diretório aberto e gratuito que funciona como um “npm para skills de agentes”. Em vez de instalar bibliotecas de código, você instala conhecimento procedural — instruções em Markdown que ensinam seu agente a executar tarefas específicas sem poluir a janela de contexto.

A proposta é simples: você encontra uma skill no diretório, roda um comando no terminal, e seu agente passa a “saber” aquilo. Sem configuração manual, sem copiar prompts, sem editar arquivos de config.

Posicionamento no mercado

O skills.sh foi um dos primeiros diretórios abertos de skills, e continua sendo o maior em volume. Ele se diferencia por:

• Gratuito e aberto — sem assinaturas, sem rate limits, baseado em GitHub
• Agnóstico de agente — a mesma skill funciona em Claude Code, Cursor, Copilot, Codex, Kiro CLI, OpenCode, Antigravity e mais de 15 outros agentes
• Instalação com um comando — npx skills add <owner/repo> e pronto
• Leaderboard por instalações — ranking transparente baseado em telemetria anônima

Modelo de execução

O skills.sh não é uma IDE, não é um CLI autônomo, e não é um serviço hospedado. É infraestrutura de descoberta e distribuição. O fluxo é:

1. Você navega o diretório em skills.sh
2. Encontra uma skill relevante
3. Instala via CLI (npx skills add)
4. O CLI detecta seu agente e coloca a skill no diretório correto
5. Na próxima sessão, seu agente carrega a skill automaticamente

Preço e planos

Gratuito. Ponto. Não existe plano pago, não existe freemium. O skills.sh é infraestrutura aberta mantida pela Vercel. As skills são hospedadas em repositórios GitHub dos próprios autores — o diretório apenas indexa e rankeia.

Números atuais

Diferencial vs concorrentes

Comparado a outros catalogadores como agentskill.sh (107K+ skills) ou officialskills.sh (581 skills curadas), o skills.sh ocupa um meio-termo: maior que os curados, mais acessível que os massivos, e com a credibilidade da Vercel por trás.

Tutorial

Pré-requisitos

Antes de começar, você precisa de:

• Node.js (v18+) instalado
• npm ou npx disponível no terminal
• Um agente de codificação configurado (Claude Code, Cursor, Kiro CLI, etc.)
• Git instalado (as skills vêm de repositórios GitHub)

Instalação do CLI

O CLI do skills.sh não precisa de instalação global — ele roda via npx:

npx skills --help

Isso já mostra todos os comandos disponíveis. Sem npm install -g, sem setup.

Primeiro Uso: Instalando sua primeira skill

Vamos instalar a skill mais popular do ecossistema — frontend-design da Anthropic:

npx skills add anthropics/skills --skill frontend-design

O que acontece por baixo:

1. O CLI detecta qual agente você está usando (baseado nos diretórios do projeto)
2. Baixa a skill do repositório GitHub anthropics/skills
3. Coloca o arquivo SKILL.md no diretório correto:
   • Claude Code: .claude/skills/
   • Cursor: .cursor/skills/
   • Kiro: .kiro/skills/
   • Copilot: .github/skills/
4. Na próxima interação, seu agente carrega a skill automaticamente

Para confirmar que funcionou:

npx skills list

Você verá algo como:

Installed skills:
  frontend-design (anthropics/skills) [project]

Navegando o Diretório

Acesse skills.sh no navegador. A interface é minimalista — um leaderboard com três abas:

• All Time — ranking por total de instalações (91.000+ skills)
• Trending (24h) — skills ganhando tração nas últimas 24 horas
• Hot — crescimento sustentado na última semana

Você também pode buscar diretamente pelo campo de pesquisa no topo. A busca funciona por nome da skill, nome do repositório ou autor.

Busca interativa via CLI

Se preferir não sair do terminal:

npx skills find

Isso abre uma busca interativa. Ou busque diretamente:

npx skills find typescript
npx skills find react testing
npx skills find security

Uso Intermediário: Instalando um pacote completo

Muitos autores publicam múltiplas skills em um único repositório. Por exemplo, o Matt Pocock mantém um pacote com skills de produtividade:

# Listar skills disponíveis no repo antes de instalar
npx skills add mattpocock/skills --list

Output:

Available skills in mattpocock/skills:
  - grill-me
  - tdd
  - diagnose
  - improve-codebase-architecture
  - to-prd
  - to-issues
  - zoom-out
  - triage
  - write-a-skill
  - setup-matt-pocock-skills
  - caveman
  - grill-with-docs

Para instalar skills específicas:

npx skills add mattpocock/skills --skill tdd --skill diagnose

Para instalar todas de uma vez:

npx skills add mattpocock/skills --all

Escopo: Projeto vs Global

Skills podem ser instaladas em dois escopos:

Projeto (padrão) — ficam no diretório do projeto, commitadas com o repo, compartilhadas com o time:

npx skills add vercel-labs/agent-skills --skill vercel-react-best-practices

Global — disponíveis em todos os projetos do seu usuário:

npx skills add -g vercel-labs/agent-skills --skill web-design-guidelines

A regra prática: skills específicas de stack (React, Rails, etc.) vão no projeto. Skills genéricas de produtividade (TDD, debugging, etc.) vão no global.

Configuração Avançada

Instalação sem prompts (CI-friendly)

Para automação e scripts:

npx skills add vercel-labs/agent-skills --skill frontend-design -g -y

O -y pula todas as confirmações interativas.

Instalação de fontes diversas

O CLI aceita múltiplas fontes além do shorthand GitHub:

# URL completa do GitHub
npx skills add https://github.com/vercel-labs/agent-skills

# Path direto para uma skill específica dentro do repo
npx skills add https://github.com/vercel-labs/agent-skills/tree/main/skills/web-design-guidelines

# URL do GitLab
npx skills add https://gitlab.com/org/repo

# Qualquer URL git
npx skills add [email protected]:vercel-labs/agent-skills.git

# Path local (para desenvolvimento)
npx skills add ./my-local-skills

Gerenciamento de skills instaladas

# Listar todas as skills instaladas
npx skills list

# Verificar atualizações disponíveis
npx skills check

# Atualizar skills
npx skills update

# Remover uma skill específica
npx skills remove web-design-guidelines

# Remover interativamente
npx skills remove

Criando uma skill do zero

O CLI tem um scaffold para iniciar:

npx skills init minha-skill

Isso cria a estrutura:

minha-skill/
└── SKILL.md

O SKILL.md mínimo precisa de:

---
name: minha-skill
description: Faz X para projetos Y. Use quando o usuário pedir X ou mencionar Y.
---

# Instruções

(Seus passos, restrições e exemplos aqui.)

Deep Dive

Arquitetura interna: como skills funcionam

Uma skill não é um plugin compilado. Não tem binários, não tem dependências de runtime, não tem vendor lock-in. É um diretório contendo um arquivo Markdown e, opcionalmente, scripts auxiliares.

Estrutura de uma skill

minha-skill/
├── SKILL.md          # Instruções principais (obrigatório)
├── scripts/          # Automação opcional
│   └── setup.sh
├── references/       # Docs, checklists, templates
│   └── checklist.md
└── assets/           # Configs de exemplo, diagramas
    └── example.tsx

O SKILL.md é o que seu agente lê. O corpo é Markdown livre, mas a estrutura recomendada é:

1. O que a skill faz
2. Quando usar (e quando NÃO usar)
3. Inputs necessários
4. Procedimento passo-a-passo
5. Validação — “como saber que terminou”
6. Modos de falha comuns e correções

Progressive disclosure: como evita bloat de contexto

Skills são projetadas para não carregar tudo de uma vez:

1. Metadata (name + description) — disponível imediatamente para o agente decidir se é relevante
2. Instruções completas (corpo do SKILL.md) — carregadas apenas quando o agente ativa a skill
3. Recursos (scripts/references/assets) — carregados apenas se a skill instrui o agente a usá-los

Isso significa que ter 50 skills instaladas não polui seu contexto. O agente só carrega o que precisa, quando precisa.

A description é o trigger

A maioria dos agentes decide se ativa uma skill baseado na description do frontmatter. Por isso, a description não é um título — é uma regra de roteamento:

Ruim:

description: Ajuda com PDFs.

Bom:

description: Extrai texto e tabelas de PDFs, preenche formulários, mescla documentos. Use quando o usuário mencionar PDFs, forms, scanning ou extração de documentos.

Publicando suas próprias skills

Aqui está a parte que surpreende: não existe comando de publicação. O processo é:

1. Crie sua skill em um repositório GitHub
2. Garanta que o SKILL.md tem frontmatter válido (name + description)
3. Compartilhe o repositório
4. Quando pessoas instalam via npx skills add, a skill aparece automaticamente no skills.sh via telemetria de instalação

Não tem formulário de submissão, não tem review queue, não tem aprovação. É completamente descentralizado.

O que incluir em um repo público de skills

No mínimo:

• Pasta(s) de skill com SKILL.md

Fortemente recomendado:

• README.md explicando o que as skills fazem e como instalar
• Informação clara de licença
• Notas de segurança se existirem scripts

Validação antes de publicar

Use a skill write-a-skill do Matt Pocock para validar sua skill antes de publicar:

npx skills add mattpocock/skills --skill write-a-skill

Depois peça ao seu agente: “Valide minha skill em ./minha-skill seguindo as melhores práticas.”

Segurança e auditorias

Desde fevereiro de 2026, o skills.sh conta com auditorias automatizadas de segurança em parceria com Gen, Socket e Snyk. O sistema funciona assim:

• Resultados transparentes — auditorias aparecem publicamente na página de cada skill
• Proteção do leaderboard — skills flagradas como maliciosas são automaticamente escondidas do ranking e da busca
• Validação na instalação — a partir da versão [email protected], o CLI exibe resultados de auditoria e níveis de risco antes da instalação

Mais de 60.000 skills já foram auditadas por esses parceiros independentes.

Boas práticas de segurança

Trate skills como código:

• Leia antes de instalar — especialmente o SKILL.md e qualquer coisa em scripts/
• Prefira skills de vendors verificados — Vercel, Anthropic, Microsoft, Supabase
• Fixe em repos conhecidos — revise diffs quando atualizar
• Cuidado com scripts — eles podem executar comandos no seu sistema

Integração com agentes

O skills.sh suporta oficialmente 19+ agentes. Aqui está como funciona com os principais:

Claude Code

Skills são instaladas em .claude/skills/ (projeto) ou ~/.claude/skills/ (global). O Claude Code carrega automaticamente skills relevantes baseado na description.

npx skills add anthropics/skills --skill frontend-design
# Instalado em .claude/skills/frontend-design/SKILL.md

Cursor

Skills vão para .cursor/skills/. O Cursor lê skills como contexto adicional nas sessões de chat e composição.

npx skills add vercel-labs/agent-skills --skill vercel-react-best-practices
# Instalado em .cursor/skills/vercel-react-best-practices/SKILL.md

Kiro CLI / Kiro IDE

Skills são instaladas em .kiro/skills/. O Kiro usa a description para decidir quando ativar cada skill durante a execução.

npx skills add mattpocock/skills --skill tdd
# Instalado em .kiro/skills/tdd/SKILL.md

GitHub Copilot

Skills vão para .github/skills/. O Copilot em Agent Mode carrega skills como instruções adicionais.

Portabilidade real

Uma skill criada para o Claude Code funciona sem alteração no Cursor, Kiro, Copilot, Antigravity, OpenCode, Codex e mais de 30 outras plataformas. Isso porque o padrão é aberto — um arquivo Markdown com frontmatter YAML. Qualquer agente que leia de um diretório de skills padrão é compatível.

Skills vs AGENTS.md: quando usar cada um

A dúvida mais comum: “Devo colocar isso numa skill ou no AGENTS.md?”

Exemplos para AGENTS.md: regras de segurança, formatação de código, “sempre use TypeScript strict”, “nunca bypass auth”.

Exemplos para skills: deploy para Vercel, análise de CSV, escrever PRD, review de performance React.

Top skills que vale a pena instalar

Baseado no leaderboard e na qualidade verificada:

O ecossistema além do skills.sh

O skills.sh não existe isolado. Ele faz parte de um ecossistema crescente:

• officialskills.sh — 581 skills oficiais de 48 dev teams (Microsoft, Anthropic, Cloudflare, etc.)
• agentskill.sh — marketplace com 107K+ skills e bundles
• skillsmp.com — busca inteligente com filtro por ocupação
• skillscatalog.ai — catálogo certificado com security scanning
• skillsdirectory.com — diretório verificado focado em Claude

Se você quer ir além de consumir skills e começar a criar, publicar e monetizar as suas, o skilldev.pro é o próximo passo — um marketplace dedicado onde skills viram produtos.

Prós e Contras

Prós

• Instalação com um comando — npx skills add é genuinamente mágico. Sem config, sem setup, funciona em segundos
• Agnóstico de agente — a mesma skill funciona em 19+ agentes. Você não fica preso a um vendor
• Gratuito e aberto — sem paywall, sem limites, baseado em GitHub. A infraestrutura é da Vercel mas o conteúdo é da comunidade
• Ecossistema massivo — 91.000+ skills significa que provavelmente já existe algo para o que você precisa
• Auditorias de segurança — parceria com Gen, Socket e Snyk dá uma camada de confiança que outros diretórios não têm
• Progressive disclosure — skills não poluem contexto. O agente carrega só o que precisa, quando precisa
• Publicação sem fricção — coloque num repo GitHub e pronto. Sem burocracia, sem aprovação

Contras

• Sem controle de qualidade na entrada — qualquer pessoa publica qualquer coisa. Estimativas da comunidade sugerem que ~80% das skills são genéricas ou de baixa qualidade
• Ranking por instalações é gamificável — popularidade ≠ qualidade. Skills virais podem ser mediocres
• Política de privacidade opaca — o CLI coleta telemetria anônima (contagem de instalações) mas não detalha retenção de dados ou uso para treinamento de modelos
• Sem features enterprise — sem SSO, sem audit logs, sem controle de acesso por time
• Ruído no diretório — encontrar skills de qualidade exige curadoria manual. A busca é básica
• Scripts podem ser perigosos — skills com scripts/ executam comandos no seu sistema. Requer vigilância

Veredicto

Para quem é ideal:

• Desenvolvedores que já usam agentes de codificação e querem especializá-los
• Times que precisam padronizar comportamento de agentes entre membros
• Quem quer experimentar skills sem compromisso (é grátis, é reversível)
• Criadores que querem distribuir skills para a comunidade sem fricção

Para quem NÃO é ideal:

• Empresas com requisitos de compliance rígidos (falta política de privacidade clara)
• Quem busca um catálogo curado e confiável sem precisar filtrar (prefira officialskills.sh)
• Iniciantes que ainda não usam agentes de codificação (primeiro aprenda o agente, depois especialize com skills)

O skills.sh é infraestrutura de primeira linha com curadoria de segunda. A arquitetura é sólida, a experiência de instalação é impecável, e o ecossistema é o maior do mercado. Mas você precisa saber filtrar — foque em skills de vendors verificados (Vercel, Anthropic, Microsoft, Supabase) e autores reconhecidos (Matt Pocock, pbakaus, coreyhaines31) e ignore o ruído.

Se você quer não apenas consumir skills mas também criar e publicar as suas — transformando conhecimento procedural em produto — o skilldev.pro é onde essa jornada continua.