npx skills

Início rápido

O comando npx skills gerencia as skills usadas pelos seus agentes de código. Você informa o repositório ou a pasta de origem e escolhe quais skills instalar e quais agentes vão usá-las. A instalação padrão vale para o projeto atual. Com --global, as skills ficam na pasta do seu usuário e podem ser usadas em outros projetos.

Este manual descreve o pacote skills na versão 1.7.6. A documentação da branch main pode incluir alterações ainda não publicadas no npm. Para executar a versão descrita aqui, use npx skills@1.7.6 no lugar de npx skills nos exemplos.

Prepare o terminal

Você precisa do Node.js 22.20.0 ou superior para executar a versão 1.7.6. O npm inclui o comando npx. Instale também o Git se for usar repositórios que exigem clonagem. Para instalar uma skill apenas no projeto, abra o terminal na pasta desse projeto.

1
node --version
2
npm --version
3
git --version
4
npx skills@1.7.6 --version

O comando abaixo consulta as skills disponíveis no repositório oficial de exemplos da Vercel. --list faz a consulta sem instalar as skills nos agentes.

1
npx skills add vercel-labs/agent-skills --list

Depois de conferir os nomes, instale uma skill para o agente que você utiliza. Este exemplo seleciona web-design-guidelines e o Codex, no projeto atual.

1
npx skills add vercel-labs/agent-skills \
2
  --skill web-design-guidelines \
3
  --agent codex
4
npx skills list --agent codex

Na primeira execução, o npm pode pedir confirmação para baixar o pacote skills. Durante a instalação, você escolhe as skills, os agentes, o escopo e o uso de cópias ou links simbólicos. Depois, confira como o seu agente carrega as skills instaladas. Alguns agentes podem exigir que você reabra a sessão.

Exemplos de uso

Instalar a mesma skill para mais de um agente

Passe os nomes dos agentes depois de --agent. O exemplo instala a mesma skill no projeto para Claude Code e Codex, sem responder às perguntas da CLI.

1
npx skills add vercel-labs/agent-skills \
2
  --skill web-design-guidelines \
3
  --agent claude-code codex \
4
  --yes

Usar a skill em vários projetos

A instalação global permite usar a skill em diferentes projetos com o mesmo usuário do sistema. Cada agente tem uma pasta própria ou compartilha a pasta de skills. Consulte os caminhos na seção Agentes e diretórios.

1
npx skills add vercel-labs/agent-skills \
2
  --skill web-design-guidelines \
3
  --agent claude-code \
4
  --global
5
npx skills list --global --agent claude-code

Conferir uma atualização antes de aplicar

O comando check consulta as atualizações disponíveis. O comando update reinstala as skills que têm atualizações. Nos exemplos abaixo, --project limita as duas ações ao projeto atual.

1
npx skills check --project
2
npx skills update --project
3
npx skills list

Experimentar uma skill sem instalação permanente

O comando use prepara os arquivos em uma pasta temporária e gera um prompt. Ao receber --agent codex, ele abre o Codex com esse prompt. Para usar essa opção, o executável codex precisa estar instalado no computador.

1
npx skills use vercel-labs/agent-skills@web-design-guidelines --agent codex

Preparar uma instalação sem perguntas

Os dois --yes pertencem a programas diferentes. O primeiro autoriza o npm a obter o pacote da CLI. O segundo responde às confirmações de instalação feitas por skills.

1
npx --yes skills@1.7.6 add vercel-labs/agent-skills \
2
  --skill web-design-guidelines \
3
  --agent codex \
4
  --yes

Remover apenas de um agente

Informe a skill antes das opções que aceitam vários valores. Assim, o nome da skill não é interpretado como outro nome de agente.

1
npx skills remove web-design-guidelines --agent claude-code
2
npx skills list --agent claude-code

Sintaxe, versões e aliases

A estrutura geral é npx skills <comando> [argumentos] [opções]. Os sinais < > indicam um valor obrigatório e [ ] indicam algo opcional nas descrições de sintaxe. Não digite esses delimitadores no terminal. Nomes como minha-skill, equipe/repositorio e example.com são exemplos que você deve substituir.

Na versão 1.7.6, install e i são aliases de add. Para restaurar as skills registradas em skills-lock.json, use experimental_install. Essa relação mudou na branch de desenvolvimento, mas os exemplos deste manual seguem a versão publicada.

Ajuda e versão

1
npx skills --help
2
npx skills add --help
3
npx skills remove --help
4
npx skills --version
5
npx skills@1.7.6 --help

A maioria dos subcomandos mostra a ajuda geral. O comando remove tem uma ajuda própria, enquanto check funciona na versão 1.7.6 mesmo sem aparecer na ajuda principal. Confira a grafia das opções, pois alguns comandos ignoram opções desconhecidas sem exibir erro.

Argumentos com vários valores

--agent e --skill em add consomem os valores seguintes até encontrar outra opção. Coloque a origem primeiro. Você pode repetir essas flags ou passar uma sequência de nomes. A exceção é use, que aceita somente uma skill e um agente.

1
npx skills add equipe/repositorio \
2
  --skill primeira-skill segunda-skill \
3
  --agent codex claude-code
4
npx skills add equipe/repositorio \
5
  --skill primeira-skill \
6
  --skill segunda-skill \
7
  --agent codex

Use aspas em nomes com espaços e no curinga '*', para que o shell não substitua o asterisco pelos arquivos da pasta. Nos exemplos de Bash e zsh, as aspas simples também preservam JSON e fragmentos de URL.

add

O comando add instala skills de um repositório, de uma pasta local ou de outra origem compatível. Para consultar as skills disponíveis sem instalá-las, acrescente --list. A instalação é local por padrão, na pasta do projeto onde você executou o comando.

1
npx skills add <origem...> [opções]

Parâmetros de add

Exemplos de add

1
# 1. Consultar o conteúdo antes de instalar
2
npx skills add vercel-labs/agent-skills --list
3

4
# 2. Instalar uma skill para o Codex no projeto
5
npx skills add vercel-labs/agent-skills \
6
  --skill web-design-guidelines \
7
  --agent codex
8

9
# 3. Instalar globalmente para o Claude Code
10
npx skills add vercel-labs/agent-skills \
11
  --skill web-design-guidelines \
12
  --agent claude-code \
13
  --global
14

15
# 4. Instalar todas as skills somente para o Cursor
16
npx skills add equipe/repositorio --skill '*' --agent cursor --yes
17

18
# 5. Copiar uma skill local para dois agentes
19
npx skills add ./minha-skill --agent codex claude-code --copy --yes
20

21
# 6. Obter resultado legível por automações
22
npx skills add vercel-labs/agent-skills \
23
  --skill web-design-guidelines \
24
  --agent codex \
25
  --json \
26
  --yes
27

28
# 7. Procurar também fora das pastas habituais
29
npx skills add equipe/repositorio --full-depth --list
30

31
# 8. Associar metadados de uma instalação automatizada
32
npx skills add ./minha-skill \
33
  --agent codex \
34
  --yes \
35
  --metadata '{"origem":"setup-equipe"}'
36

37
# 9. Selecionar um subagente de um projeto Eve
38
npx skills add ./minha-skill --subagent revisor --yes

Arquivos e saída

No modo de links simbólicos, a CLI mantém os arquivos compartilhados em .agents/skills/ no projeto ou em ~/.agents/skills/ na instalação global. As pastas dos agentes apontam para esses arquivos. Agentes que já leem a pasta compartilhada dispensam um link adicional. Se o sistema não permitir links simbólicos, use --copy para gravar cópias nos destinos dos agentes.

Uma instalação pode substituir os arquivos de outra skill com o mesmo nome. Confira as alterações locais que deseja preservar. Depois de instalar, execute list no mesmo escopo e abra o SKILL.md na pasta indicada.

A saída JSON informa o resultado de cada instalação pelo campo status, com os valores installed, skipped ou failed. Conforme o resultado, o item também pode incluir name, source, ref, hash, path, scope, agents, mode, security, reason e error. Esses campos são opcionais. Na versão 1.7.6, as origens well-known não aceitam add --json.

Origens e versões das skills

A versão da CLI e a revisão da skill são independentes. npx skills@1.7.6 seleciona o pacote gerenciador. O argumento depois de add seleciona o conteúdo que será instalado.

Fixar branch, tag ou commit

Na 1.7.6, use um fragmento #referencia para uma revisão Git. @nome no formato abreviado seleciona uma skill, não uma versão. O exemplo abaixo usa um repositório e uma tag ilustrativos.

1
npx skills add 'equipe/repositorio#v1.2.3' --skill minha-skill --agent codex
2
npx skills add 'equipe/repositorio#main@minha-skill' --agent codex
3
npx skills add 'https://github.com/equipe/repositorio/tree/v1.2.3/skills/minha-skill' \
4
  --agent codex

Para instalar o conteúdo de um commit específico, informe seu SHA completo, com 40 caracteres. A clonagem tenta primeiro encontrar uma branch ou tag com a referência fornecida. Uma tag pode ser movida para outro commit no repositório de origem, por isso o SHA completo identifica a revisão com mais precisão.

Downloads e Notion

O download direto aceita um SKILL.md ou um arquivo compactado nos formatos .zip, .tar, .tar.gz e .tgz. A URL não precisa terminar com uma extensão. Por padrão, o download aceita até 10 MiB. O conteúdo extraído pode ter até 25 MiB e mil arquivos. A seção Variáveis de ambiente explica como ajustar esses limites.

1
npx skills add https://example.com/minha-skill.zip --agent codex
2
npx skills add notion
3
npx skills add https://www.notion.so/ID-DA-PAGINA

Os exemplos do Notion exigem que o executável ntn esteja no PATH e que você tenha feito a autenticação com ntn login. Uma origem aceita por add pode não ser compatível com check, update ou a restauração na versão 1.7.6. Confira a origem registrada pela CLI. Se a atualização não for suportada, reinstale a skill com add.

use

O comando use prepara uma skill para uso temporário, sem registrá-la como instalação permanente no projeto. Ele baixa ou copia os arquivos para uma pasta temporária e gera um prompt com as instruções do SKILL.md e os caminhos dos arquivos auxiliares.

1
npx skills use <origem> [--skill <nome>] [--agent <agente>] [--full-depth]

Na versão 1.7.6, use --agent pode abrir o Claude Code, o Codex ou o Sarvam Code. Os executáveis desses agentes precisam estar instalados. O comando aceita apenas um agente por execução e não aceita o curinga '*'. Já add instala skills para uma lista maior de agentes.

Exemplos de use

1
# 1. Imprimir o prompt no terminal
2
npx skills use vercel-labs/agent-skills@web-design-guidelines
3

4
# 2. Selecionar a skill por opção
5
npx skills use vercel-labs/agent-skills --skill web-design-guidelines
6

7
# 3. Abrir o Codex com a skill
8
npx skills use vercel-labs/agent-skills@web-design-guidelines --agent codex
9

10
# 4. Abrir o Claude Code com a skill
11
npx skills use vercel-labs/agent-skills@web-design-guidelines \
12
  --agent claude-code
13

14
# 5. Preparar o prompt de uma skill local
15
npx skills use ./minha-skill > prompt-da-skill.txt
16

17
# 6. Procurar uma skill fora das pastas convencionais
18
npx skills use equipe/repositorio --skill minha-skill --full-depth

O prompt pode conter caminhos de uma pasta temporária deste computador. Salvar esse texto em um arquivo não transforma os arquivos auxiliares em conteúdo portátil. Para uso recorrente ou compartilhado com a equipe, prefira uma instalação gerenciada por add.

list

O comando list mostra as skills instaladas, suas pastas e os agentes associados. Sem opções, ele consulta o projeto atual. Com --global, consulta as instalações do seu usuário. A listagem não altera os arquivos nem executa as instruções das skills.

1
npx skills list [--global] [--agent <nomes...>] [--json]

Exemplos de list

1
# 1. Ver as skills do projeto
2
npx skills list
3

4
# 2. Consultar as instalações do usuário
5
npx skills list --global
6

7
# 3. Filtrar pelo Claude Code
8
npx skills list --agent claude-code
9

10
# 4. Consultar dois agentes
11
npx skills ls --agent codex cursor
12

13
# 5. Exportar a lista do projeto
14
npx skills list --json > skills-do-projeto.json
15

16
# 6. Exportar as skills globais de um agente
17
npx skills ls --global --agent codex --json

Se a lista estiver vazia, confira a pasta do terminal e compare os resultados de list e list --global. A skill pode estar instalada em outro projeto ou no escopo global. Essa conferência ajuda a localizar a instalação sem reinstalar os arquivos.

find

O comando find pesquisa skills no catálogo remoto. Sem um termo de busca, ele abre a seleção interativa quando o terminal permite essa interação. Com um termo, mostra as skills encontradas e os comandos de instalação.

1
npx skills find [consulta...] [--owner <usuario>]

Exemplos de find

1
# 1. Abrir a pesquisa interativa
2
npx skills find
3

4
# 2. Procurar skills de TypeScript
5
npx skills find typescript
6

7
# 3. Pesquisar por mais de uma palavra
8
npx skills find "react performance"
9

10
# 4. Restringir a uma organização
11
npx skills find react --owner vercel-labs
12

13
# 5. Usar o alias de pesquisa
14
npx skills search accessibility
15

16
# 6. Usar a opção no formato com sinal de igual
17
npx skills find testing --owner=vercel-labs

A consulta depende de rede. Encontrar uma skill não equivale a instalá-la, embora a interface interativa possa encaminhar a seleção para a instalação. Para listar o conteúdo de um repositório específico, use add <origem> --list, não find <origem>.

check

O comando check consulta as atualizações das skills registradas sem reinstalar os arquivos. Ele aceita as opções de escopo e seleção de update, embora não apareça na ajuda principal da versão 1.7.6.

1
npx skills check [nomes...] [--global] [--project] [--yes]

Exemplos de check

1
# 1. Escolher o escopo interativamente
2
npx skills check
3

4
# 2. Conferir somente o projeto
5
npx skills check --project
6

7
# 3. Conferir somente o usuário
8
npx skills check --global
9

10
# 4. Conferir uma skill específica
11
npx skills check web-design-guidelines --project
12

13
# 5. Conferir os dois escopos sem perguntas
14
npx skills check --project --global --yes

Quando encontra atualização, check termina com código de saída 1. Portanto, esse resultado não significa necessariamente erro de conexão ou falha de execução. Em scripts, leia também a saída para distinguir atualização disponível de uma falha. Ausência de terminal interativo também ativa a seleção automática de escopo.

update

O comando update consulta as origens registradas e reinstala as skills que têm atualizações. Você pode informar os nomes das skills ou atualizar todas as instalações de um escopo. Ele atualiza as skills, não o pacote npm skills.

1
npx skills update [nomes...] [--global] [--project] [--yes]

Quando você informa nomes e usa -g -p juntos, a versão 1.7.6 procura essas skills no escopo global. Para atualizar skills específicas nos dois escopos, execute o comando uma vez com -p e outra com -g.

Exemplos de update

1
# 1. Escolher o escopo na interface
2
npx skills update
3

4
# 2. Atualizar todas as skills do projeto
5
npx skills update --project
6

7
# 3. Atualizar todas as skills do usuário
8
npx skills update --global
9

10
# 4. Atualizar somente uma skill local
11
npx skills update web-design-guidelines --project
12

13
# 5. Atualizar dois nomes específicos
14
npx skills update primeira-skill segunda-skill --project
15

16
# 6. Consultar automaticamente o escopo do ambiente
17
npx skills upgrade --yes

A atualização depende da origem registrada durante a instalação. Uma skill copiada manualmente pode não ter esse registro. A reinstalação também pode substituir alterações locais, então compare os arquivos do projeto depois de atualizar. Para skills fornecidas por dependências npm, atualize o pacote correspondente e execute experimental_sync.

remove

O comando remove apaga skills instaladas ou remove sua associação com determinados agentes. Sem nomes, ele pode abrir uma seleção interativa. A remoção vale para o projeto atual por padrão. Para remover uma instalação global, acrescente --global.

1
npx skills remove [nomes-ou-origem...] [opções]

Exemplos de remove

1
# 1. Abrir a seleção interativa
2
npx skills remove
3

4
# 2. Remover uma skill local
5
npx skills remove web-design-guidelines
6

7
# 3. Remover somente o vínculo com o Claude Code
8
npx skills remove web-design-guidelines --agent claude-code
9

10
# 4. Remover uma instalação global
11
npx skills rm web-design-guidelines --global
12

13
# 5. Remover as skills da origem exata registrada no projeto
14
npx skills remove equipe/repositorio
15

16
# 6. Remover todas as skills de um agente, com confirmação
17
npx skills remove --skill '*' --agent cursor
18

19
# 7. Remover todas as skills do projeto, sem confirmação
20
npx skills remove --all

O último exemplo é uma remoção em lote. Confira primeiro npx skills list no mesmo diretório. A CLI também atualiza os registros pertinentes e considera se outros agentes ainda usam o conteúdo compartilhado. Para conferir o resultado, repita list com os mesmos filtros e escopo.

init

O comando init cria um modelo de SKILL.md. Sem um nome, grava o arquivo na pasta atual e usa o nome dessa pasta no frontmatter. Se você informar um nome, ele cria uma subpasta com esse nome e grava o arquivo nela. Um SKILL.md existente é preservado.

1
npx skills init [nome]

Exemplos de init

1
# 1. Criar o modelo na pasta atual
2
npx skills init
3

4
# 2. Começar uma skill de revisão
5
npx skills init revisao-de-codigo
6

7
# 3. Criar uma skill dentro da pasta skills do repositório
8
cd skills
9
npx skills init documentacao-de-api

Escolha o exemplo que corresponde à pasta onde deseja criar a skill. Depois, edite as instruções do SKILL.md e teste a instalação com add ./caminho-da-skill. O comando init cria o modelo local, mas não publica o repositório nem instala a skill nos agentes.

experimental_sync

O comando experimental_sync instala as skills fornecidas pelas dependências npm do projeto ou declaradas no campo skills do package.json. Ele prepara a pasta compartilhada, cria os destinos dos agentes selecionados e registra as origens em skills-lock.json.

1
npx skills experimental_sync [opções]

O comando lê dependencies, devDependencies, optionalDependencies e peerDependencies. Nos pacotes, reconhece SKILL.md na raiz, skills/<nome>/SKILL.md e dist/skills/<nome>/SKILL.md. Instale as dependências antes de sincronizar.

Exemplos de experimental_sync

1
# 1. Simular a sincronização
2
npx skills experimental_sync --dry-run
3

4
# 2. Sincronizar para o Claude Code sem perguntas
5
npx skills experimental_sync --agent claude-code --yes
6

7
# 3. Incluir os pacotes de um workspace
8
npx skills experimental_sync --recursive --yes
9

10
# 4. Incluir somente um pacote instalado
11
npx skills experimental_sync --include 'agent-browser' --yes
12

13
# 5. Excluir uma skill de um pacote
14
npx skills experimental_sync --exclude 'meu-pacote#minha-skill' --yes
15

16
# 6. Preservar skills antigas e ignorar origens remotas
17
npx skills sync --no-cleanup --no-remote --yes
18

19
# 7. Conferir o conteúdo contra o arquivo de controle
20
npx skills experimental_sync --frozen-lockfile --yes

O campo skills do package.json

Um projeto ou pacote pode declarar um array de origens. Uma entrada npm: aponta para um pacote já instalado. As demais entradas podem apontar para origens Git. Um pacote com esse campo pode distribuir um conjunto de skills.

1
{
2
  "skills": [
3
    "npm:agent-browser",
4
    "vercel-labs/agent-skills@web-design-guidelines"
5
  ],
6
  "scripts": {
7
    "prepare": "skills experimental_sync -y"
8
  }
9
}

O exemplo de prepare pressupõe que o pacote skills esteja nas dependências do projeto. Ele executa a sincronização durante os eventos do npm que chamam esse script. Você também pode chamar npx skills experimental_sync -y separadamente, sem alterar scripts existentes.

Se uma skill já foi instalada por add, experimental_sync preserva essa instalação quando encontra outra com o mesmo nome. Skills incluídas diretamente em um pacote têm prioridade sobre as declaradas por uma origem Git. Se dois pacotes fornecerem o mesmo nome, use --exclude para escolher qual ignorar. A sincronização também preserva pastas e links que não criou.

Com --frozen-lockfile, uma diferença de pacote, versão ou conteúdo encerra a sincronização com código 1 sem atualizar skills-lock.json. Nos filtros de origens remotas, informe o nome do pacote que declarou a skill. O valor . identifica uma declaração no próprio projeto. Para o Eve, a CLI cria cópias porque precisa adaptar o frontmatter.

experimental_install

O comando experimental_install restaura no projeto as skills registradas em skills-lock.json. Na versão 1.7.6, ele grava os arquivos em .agents/skills/ e não cria links para as pastas específicas dos agentes. Se o seu agente lê outra pasta, a restauração sozinha não disponibiliza a skill nesse destino.

1
npx skills experimental_install [opções]

Exemplos de experimental_install

1
# 1. Conferir o que seria restaurado
2
npx skills experimental_install --dry-run
3

4
# 2. Restaurar as skills ausentes
5
npx skills experimental_install
6

7
# 3. Reinstalar também as skills presentes
8
npx skills experimental_install --force
9

10
# 4. Exigir o conteúdo registrado no arquivo de controle
11
npx skills experimental_install --frozen-lockfile
12

13
# 5. Permitir atualização do arquivo de controle
14
npx skills experimental_install --no-frozen-lockfile

Para restaurar skills fornecidas por pacotes npm, instale primeiro as dependências do projeto. O comando não baixa esses pacotes. Uma skill já presente é preservada, a menos que você use --force. Com --frozen-lockfile, a ausência de um skills-lock.json preenchido ou uma diferença nos hashes encerra a execução com código 1.

A restauração pode instalar algumas skills e falhar em outras. Leia o resumo e execute list para conferir quais ficaram disponíveis. Os comandos com prefixo experimental_ podem mudar de nome, opções ou comportamento em versões posteriores.

Escopos, pastas e arquivos de controle

A instalação local pertence ao diretório no qual você executa o comando. A instalação global pertence ao usuário do sistema. Manter ambas pode ser útil, mas consultar uma não mostra automaticamente a outra.

O arquivo skills-lock.json registra as skills do projeto. Já .skill-lock.json guarda o estado global da CLI. Eles têm funções e formatos diferentes, portanto renomear um para substituir o outro não repara a instalação. Alterar manualmente o número da versão do formato também não converte os registros.

Links simbólicos e cópias

Um link simbólico permite que vários agentes apontem para o mesmo conteúdo. Ao atualizar a pasta compartilhada, os links passam a enxergar os arquivos novos. Com cópias, cada destino tem seus próprios arquivos. Use --copy quando precisar desse comportamento ou quando a criação de links não funcionar no ambiente.

Para conferir uma instalação no projeto:

1
npx skills list
2
npx skills list --agent claude-code
3
npx skills list --json

Confira as alterações em skills-lock.json e nas pastas de skills antes de compartilhar o projeto. Leia também os scripts incluídos nas skills que pretende usar. O gerenciador instala esses arquivos, mas cabe a você conferir o que eles executam.

Agentes e diretórios

A tabela registra os identificadores aceitos por --agent na versão documentada. Um agente aceitar a instalação não significa que implemente todos os recursos de outro agente, como hooks ou execução em contexto separado. use --agent tem uma lista menor: Claude Code, Codex e Sarvam Code.

Os caminhos da tabela são os padrões da versão documentada. As configurações do sistema ou do agente podem alterar a pasta global. O símbolo ~ representa a pasta do seu usuário. O Eve aceita apenas instalações no projeto.

Criar e distribuir uma skill

Uma skill reúne suas instruções em um arquivo SKILL.md e pode incluir arquivos auxiliares na mesma pasta. No início do arquivo, o frontmatter YAML informa o nome e a descrição. O texto seguinte explica quando usar a skill, quais informações ela recebe e como executar o trabalho.

1
---
2
name: revisao-de-api
3
description: Revisa endpoints HTTP, validações de entrada e respostas de erro de uma API.
4
---
5

6
# Revisão de API
7

8
## Quando usar
9

10
Use esta skill para revisar endpoints novos ou alterados antes da publicação.
11

12
## Instruções
13

14
1. Leia as rotas e identifique os métodos HTTP disponíveis.
15
2. Confira a validação das entradas e os códigos de resposta.
16
3. Relate os arquivos afetados e proponha correções para os problemas encontrados.

Os campos name e description são obrigatórios para que a CLI encontre a skill. Se ela for de uso interno, configure metadata.internal: true. A variável INSTALL_INTERNAL_SKILLS permite incluir essas skills na busca.

Organização do repositório

O gerenciador procura o arquivo SKILL.md na raiz do repositório e em skills/, incluindo pastas como skills/.curated/, skills/.experimental/ e skills/.system/. Também consulta as pastas de skills dos agentes e as declarações de .claude-plugin/marketplace.json e .claude-plugin/plugin.json.

Na versão 1.7.6, a busca nas pastas de catálogo percorre até três níveis. Quando encontra um SKILL.md, ela não continua nas subpastas daquela skill. A opção --full-depth amplia a procura. Se os locais habituais não contiverem skills, a CLI também pode procurar nas demais subpastas.

Para cadastrar pastas adicionais, crie skills.sh.json na raiz do repositório:

1
{
2
  "$schema": "https://skills.sh/schemas/skills.sh.schema.json",
3
  "paths": ["./tools/skills"]
4
}

Cada entrada precisa começar com ./ e apontar para uma subpasta do repositório. O diretório raiz e caminhos fora do repositório são ignorados. Os caminhos adicionais complementam os locais habituais, com a mesma busca até três níveis. Se duas skills têm o mesmo nome, apenas a primeira descoberta é mantida.

Você pode compartilhar o repositório no GitHub ou em outro servidor Git e fornecer o comando add para a pasta correspondente. init não faz essa publicação. Confira o conteúdo com add ./pasta --list e depois instale em um projeto de teste antes de distribuir.

Repositórios privados e autenticação

Para instalar de um repositório privado, a CLI usa a autenticação disponível para a URL. Configure o Git, o GitHub CLI ou o SSH antes de instalar. Evite colocar credenciais na própria URL, porque comandos podem permanecer no histórico do terminal.

1
npx skills add equipe/repositorio-privado --skill minha-skill --agent codex
2
npx skills add git@github.com:equipe/repositorio-privado.git --agent codex
3
npx skills add ssh://git@git.example.com/equipe/repositorio.git --agent codex

Ao clonar uma origem do GitHub por HTTPS ou pelo nome abreviado, a CLI tenta as credenciais configuradas no Git. Se a tentativa falhar e houver uma sessão autenticada no GitHub CLI, ela pode tentar gh repo clone e depois SSH. Para consultas à API, a autenticação pode usar GITHUB_TOKEN, GH_TOKEN ou o GitHub CLI, conforme a função executada.

Você não precisa definir essas variáveis se a autenticação existente já permite acessar o repositório. Quando precisar de um token, configure-o como segredo do ambiente. Não o grave no repositório nem na URL de instalação. A variável GH_HOST pode direcionar nomes abreviados para o GitHub Enterprise. Uma URL completa informa o servidor diretamente.

Variáveis de ambiente

As variáveis abaixo ajustam a busca, a instalação e a comunicação com os serviços externos. Os valores padrão correspondem à versão 1.7.6. As variáveis de serviço e de depuração podem mudar entre versões, então confira a implementação se você usa outra versão da CLI.

O modo de integração contínua (CI) também reconhece GITHUB_ACTIONS, GITLAB_CI, CIRCLECI, TRAVIS, BUILDKITE, JENKINS_URL e TEAMCITY_VERSION. Até o texto false é tratado como um valor não vazio. Para desativar essa detecção, remova a variável. Se precisar permitir alterações no arquivo de controle durante a execução, use --no-frozen-lockfile.

Bash e zsh

1
DISABLE_TELEMETRY=1 npx skills list
2
INSTALL_INTERNAL_SKILLS=1 npx skills add equipe/repositorio --list
3
SKILLS_CLONE_TIMEOUT_MS=600000 npx skills add equipe/repositorio --list

PowerShell

1
$env:DISABLE_TELEMETRY = '1'
2
npx skills list
3
Remove-Item Env:DISABLE_TELEMETRY

Prompt de Comando do Windows

1
set DISABLE_TELEMETRY=1
2
npx skills list
3
set DISABLE_TELEMETRY=

A CLI possui também variáveis usadas para detectar agentes e localizar suas configurações. Elas pertencem aos ambientes desses agentes e não são parâmetros universais de instalação. Prefira --agent para tornar explícito o destino no comando.

Automação com JSON e integração contínua

Para repetir uma instalação em uma automação, fixe a versão da CLI e informe as skills, os agentes e o escopo. O primeiro --yes, logo depois de npx, autoriza o download do pacote. O segundo, depois das opções de skills, confirma a instalação das skills.

1
npx --yes skills@1.7.6 add vercel-labs/agent-skills \
2
  --skill web-design-guidelines \
3
  --agent codex \
4
  --yes \
5
  --json
6
npx --yes skills@1.7.6 list --json

Os comandos add --json e list --json retornam os resultados em JSON. Os demais comandos não oferecem necessariamente essa opção. Ao salvar a saída em um arquivo, confira também o código de saída para saber se a execução terminou com alguma falha.

Restaurar as skills na integração contínua

Depois de instalar as dependências do projeto, restaure as skills e sincronize as fornecidas por pacotes. O exemplo supõe que o projeto já tenha um skills-lock.json compatível e dependências npm registradas.

1
npm ci
2
npx --yes skills@1.7.6 experimental_install --frozen-lockfile
3
npx --yes skills@1.7.6 experimental_sync --frozen-lockfile --agent codex --yes

O modo congelado recusa conteúdo que não corresponde ao registro. Ele não deve ser desativado apenas para esconder uma diferença: primeiro reproduza a atualização localmente, confira os arquivos e publique o registro atualizado no projeto. Uma skill de origem Git sem revisão fixa ainda depende do conteúdo disponível na origem para a restauração.

Códigos de saída

O código de saída precisa ser interpretado junto com a mensagem exibida pelo comando. Como check também retorna 1 quando encontra atualizações, esse valor sozinho não informa a causa do resultado. Em uma automação, confira os resultados individuais e trate o cancelamento de uma execução interativa sem presumir que a instalação foi concluída.

Solução de problemas

O terminal não encontra npx

Confira a instalação de Node.js e npm e abra uma nova sessão de terminal depois de ajustar o PATH. Verifique as versões com node --version e npm --version. O requisito desta referência é Node.js 22.20.0 ou superior.

A CLI informa que nenhuma skill foi encontrada

Use add <origem> --list. Confira se a pasta contém SKILL.md, se o YAML possui name e description e se você apontou para a branch e a subpasta corretas. Para uma organização fora das pastas habituais, consulte --full-depth e skills.sh.json.

A instalação aparece, mas o agente não usa a skill

Execute list e list --global para localizar a instalação, depois confira a pasta usada pelo agente. O agente precisa reconhecer o formato e os recursos da skill. O comando list apenas consulta os arquivos instalados. O agente carrega e executa as instruções.

O link simbólico não pode ser criado

Verifique as permissões de escrita e as condições do sistema para criar links. Refaça uma instalação de teste com --copy quando precisar de cópias independentes. Depois, confira o destino do agente e o conteúdo do SKILL.md.

O repositório privado retorna erro de acesso

Teste a autenticação Git ou SSH para a mesma URL, sem expor tokens no terminal. Se utiliza GitHub CLI, confira gh auth status. Um token sem acesso ao repositório não é corrigido pela opção --yes.

O nome da skill foi interpretado como agente

Opções como --agent leem uma lista de valores. Coloque os argumentos posicionais antes delas ou use --skill para separar explicitamente os grupos.

1
npx skills remove minha-skill --agent claude-code
2
npx skills remove --skill minha-skill --agent claude-code

O comando pede confirmação na integração contínua

Informe as opções exigidas pelo comando para executar sem perguntas. Em add, selecione as skills e os agentes e acrescente --yes. Em update e check, informe o escopo. O comando experimental_install aceita outro conjunto de opções. Para autorizar o download do próprio pacote da CLI, use npx --yes.

O JSON não veio no formato esperado

Use add --json --yes ou list --json. Não combine add --json com --list. Na versão documentada, well-known não aceita a saída JSON de instalação. Separe a saída padrão (stdout) das mensagens de erro (stderr) e confira o código de saída antes de processar o arquivo.

O comando check terminou com código 1

Leia a saída. Atualização disponível também produz esse código. A verificação não deve ser interpretada como uma falha genérica sem examinar quais skills foram marcadas e se houve erro de rede ou de autenticação.

A restauração falhou com --frozen-lockfile

Confira se skills-lock.json existe, se não tem marcadores de conflito Git e se foi gerado por uma versão compatível. Compare a revisão da origem, as dependências instaladas e os hashes. Atualize as skills localmente e confira as alterações em skills-lock.json. Depois, use esse arquivo na integração contínua.

Uma flag da documentação online não funciona

Compare npx skills --version com a versão desta referência e com o commit da documentação consultada. A ajuda e o README da branch main podem mudar antes da próxima publicação no npm. install sem origem e os vínculos de experimental_install são exemplos de comportamentos que diferem entre a 1.7.6 e alterações posteriores.

Fontes e atualização deste manual

Esta página é uma referência em Português do Brasil mantida pela Promovaweb. O projeto skills pertence à Vercel. A revisão usa o pacote npm 1.7.6, seu --help e o commit 7a5e920bead4b1039a6d6df5d7e1163b7b09423a. Os exemplos com origens ilustrativas não representam repositórios testados.

• Pacote skills no npm.
• Referência oficial de comandos nessa versão.
• Agentes e diretórios.
• Criação e descoberta de skills.
• Configuração e telemetria.
• Diretório público skills.sh.

Para escolher uma skill e aplicar esses comandos, volte ao catálogo da Promovaweb. As fichas apresentam a origem, a finalidade e os comandos correspondentes a cada skill.