⚡ CLI na Prática

O shorthand owner/repo é a forma mais simples de instalar skills. npx skills add vercel-labs/agent-skills instala todas as skills do repositório detectando automaticamente os agentes presentes.

É o comando que você vai usar 90% das vezes. Entender o shorthand abre a porta para o ecossistema inteiro de skills públicas no GitHub.

owner/repo · GitHub API · detecção automática · confirmação interativa · -y para pular confirmação

Além do shorthand, o CLI aceita: URL completa do GitHub, URL de skill específica (path até o arquivo), path local (./meu-projeto) e repositórios GitLab/Bitbucket.

Diferentes cenários exigem diferentes fontes. Skills internas usam path local. Skills de um branch específico usam URL com /tree/branch-name.

URL completa · path local ./ · skill específica /tree/main/skills/nome · branches e tags

A flag -g (--global) instala skills em ~/[agente]/skills/ em vez de ./[agente]/skills/. Skills globais ficam disponíveis em TODOS os projetos no seu sistema.

Skills de preferências pessoais (estilo de código, idioma de resposta, ferramentas favoritas) devem ser globais. Skills de projeto devem ser locais e comitadas.

~/.claude/skills/ · global vs projeto · preferências pessoais · não versionar no Git · disponibilidade universal

A flag -a (--agent) especifica para qual agente instalar: -a claude, -a cursor, -a copilot. Pode-se passar múltiplos: -a claude,cursor.

Útil quando você quer instalar para um agente que não foi detectado automaticamente, ou quando quer instalar apenas para um agente específico.

-a claude · -a cursor,copilot · múltiplos agentes · override de detecção automática

A flag -s (--skill) instala apenas skills específicas de um repositório: -s react-best-practices instala só essa skill, mesmo que o repo tenha 30 outras.

Repositórios grandes como vercel-labs/agent-skills têm muitas skills. Instalar apenas o necessário mantém o projeto limpo e o agente focado.

-s skill-name · múltiplas skills (-s a,b,c) · instalação seletiva · --list para ver disponíveis antes de instalar

--all instala para todos os agentes (sem detecção). -y (--yes) pula as confirmações interativas. Combinados, permitem instalação totalmente não-interativa em scripts.

CI/CD pipelines precisam de instalação automática. npx skills add --all -y vercel-labs/agent-skills funciona perfeitamente em GitHub Actions.

--all · -y · CI/CD · GitHub Actions · scripts de setup · onboarding automatizado

npx skills find [query] busca skills no diretório skills.sh por keyword. Sem query, abre uma interface interativa estilo fzf para navegar todas as skills disponíveis.

A descoberta é o ponto de entrada para o ecossistema. Antes de criar uma skill, verifique se já existe uma que atenda sua necessidade.

busca por keyword · interface fzf · skills.sh API · filtragem por agente · preview de descrição

npx skills list exibe todas as skills instaladas, separadas por escopo (projeto e global) e por agente. Mostra nome, origem e método (symlink ou copy).

Auditar o que está instalado é essencial para manter o agente focado. Skills obsoletas devem ser removidas; skills desatualizadas devem ser atualizadas.

inventário · escopo projeto/global · agente por agente · -p para projeto · -g para global · método de instalação

npx skills update atualiza todas as skills. npx skills update react-best-practices atualiza apenas uma skill específica. Funciona com symlinks e cópias.

Skills evoluem. A comunidade melhora skills populares com novas best practices. Manter atualizado garante que você sempre usa as instruções mais eficazes.

update individual vs todas · -g para global · git pull para symlinks · substituição para cópias

As flags -g (global) e -p (project) filtram os comandos list e update para operar apenas no escopo desejado. Sem flag, operam em ambos os escopos.

Em máquinas com muitas skills globais e de projeto, filtrar por escopo evita atualizar inadvertidamente skills que não devem ser tocadas.

-g lista só globais · -p lista só projeto · combinado com update · separação de responsabilidades

Symlink (padrão) cria links simbólicos apontando para a skill na fonte canônica. Copy (--copy) cria cópias independentes. Symlinks são mais eficientes; cópias são mais portáveis.

Sistemas Windows, alguns CIs e filesystems remotos podem não suportar symlinks. Nesse caso, use --copy. Para desenvolvimento local, symlinks são sempre melhores.

symlink · --copy · source única · atualização automática vs manual · compatibilidade de filesystem

Combinando os três comandos: find para descobrir, add para instalar, list para auditar, update para manter atualizado. Um fluxo completo de gerenciamento de skills.

Entender o fluxo completo transformar o CLI em uma ferramenta poderosa de gestão de conhecimento do agente, não apenas um instalador.

fluxo find → add → list → update · rotina de manutenção · auditoria periódica · gestão de conhecimento

npx skills remove sem argumento abre seleção interativa das skills instaladas. Com nome, remove diretamente: npx skills remove react-best-practices.

Skills obsoletas ocupam espaço e podem confundir o agente com instruções desatualizadas. Limpeza regular é boa prática.

remoção interativa · remoção por nome · symlinks removidos · cópias deletadas · confirmação antes de remover

Use -g para remover skills globais e -p para skills de projeto. Sem flag, o CLI pergunta de qual escopo remover se a skill existir em ambos.

Uma skill pode estar instalada tanto globalmente quanto no projeto. Especificar o escopo evita remover acidentalmente do lugar errado.

-g para global · -p para projeto · ambos escopos · remoção seletiva · evitar remoção acidental

npx skills init [name] cria um arquivo SKILL.md com o template básico pré-preenchido: frontmatter com name e description, e seções When to Use e Steps.

O init garante que você parte com a estrutura correta. Nada de inventar o formato — o template segue a especificação oficial do agentskills.io.

template pré-preenchido · nome do arquivo · pasta skills/ · estrutura oficial · ponto de partida

O init gera: frontmatter com name preenchido, placeholder para description, corpo com # título, ## When to Use com exemplos e ## Steps com passos numerados.

Conhecer o template facilita o preenchimento. Os placeholders indicam exatamente o que deve ir em cada campo.

placeholders · estrutura completa · campos a preencher · seções opcionais comentadas · exemplos nos placeholders

Após criar uma skill com init, instale-a localmente: npx skills add ./skills/minha-skill.md ou npx skills add ./meu-projeto. O agente carregará a skill para testes.

Testar localmente antes de publicar evita distribuir skills com bugs. A instalação por path local é o ciclo de desenvolvimento padrão.

path local · ./ · teste antes de publicar · ciclo de desenvolvimento · validação de comportamento

O fluxo completo: npx skills init → editar description e corpo → npx skills add ./ → testar com o agente → criar repositório GitHub → publicar para a comunidade.

Entender o fluxo completo habilita você a contribuir com a comunidade. Skills públicas de qualidade aparecem no skills.sh e beneficiam outros desenvolvedores.

init → editar → add local → testar → GitHub → publicar · contribution → skills.sh listing