# Guia Definitivo: skills.sh

> Aprenda a usar o skills.sh — o diretório aberto de skills para agentes de codificação. Instalação, publicação e curadoria.

Source: https://agentify.ia.br/blog/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 é:

- Você navega o diretório em [skills.sh](https://skills.sh)

- Encontra uma skill relevante

- Instala via CLI (`npx skills add`)

- O CLI detecta seu agente e coloca a skill no diretório correto

- 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

 Métrica Valor Skills indexadas 91.000+ Instalações totais (all-time) 385.000+ Agentes compatíveis 19+ Skill mais instalada find-skills (vercel-labs) — 1.5M installs Auditorias de segurança 60.000+ skills auditadas

### 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:

- O CLI detecta qual agente você está usando (baseado nos diretórios do projeto)

- Baixa a skill do repositório GitHub `anthropics/skills`

- Coloca o arquivo `SKILL.md` no diretório correto:

Claude Code: `.claude/skills/`

- Cursor: `.cursor/skills/`

- Kiro: `.kiro/skills/`

- Copilot: `.github/skills/`

- 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](https://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 git@github.com: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 é:

- O que a skill faz

- Quando usar (e quando NÃO usar)

- Inputs necessários

- Procedimento passo-a-passo

- Validação — “como saber que terminou”

- 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:

- **Metadata** (`name` + `description`) — disponível imediatamente para o agente decidir se é relevante

- **Instruções completas** (corpo do `SKILL.md`) — carregadas apenas quando o agente ativa a skill

- **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 é:

- Crie sua skill em um repositório GitHub

- Garanta que o `SKILL.md` tem frontmatter válido (`name` + `description`)

- Compartilhe o repositório

- 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 `skills@1.4.0`, 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?”

 Coloque no AGENTS.md quando… Coloque numa skill quando… Se aplica a quase toda tarefa É um workflow especializado Quer máxima confiabilidade (sem decisão de ativação) É usado ocasionalmente O agente nunca deve ignorar Quer que seja reutilizável entre repos/times

**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:

 Skill Autor Installs Para quê frontend-design anthropics/skills 418K+ Design de interfaces premium vercel-react-best-practices vercel-labs 403K+ Padrões React modernos web-design-guidelines vercel-labs 322K+ Guidelines de UI/UX tdd mattpocock/skills 112K+ Test-driven development diagnose mattpocock/skills 88K+ Debugging disciplinado supabase-postgres-best-practices supabase 169K+ Banco de dados Supabase shadcn shadcn/ui 144K+ Componentes shadcn/ui grill-me mattpocock/skills 151K+ Stress-test de planos

### O ecossistema além do skills.sh

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

- **[officialskills.sh](https://officialskills.sh)** — 581 skills oficiais de 48 dev teams (Microsoft, Anthropic, Cloudflare, etc.)

- **[agentskill.sh](https://agentskill.sh)** — marketplace com 107K+ skills e bundles

- **[skillsmp.com](https://skillsmp.com)** — busca inteligente com filtro por ocupação

- **[skillscatalog.ai](https://skillscatalog.ai)** — catálogo certificado com security scanning

- **[skillsdirectory.com](https://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](https://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](https://skilldev.pro) é onde essa jornada continua.

-->