O que skillctl faz?
Guia operacional para gerenciar Skills de Agentes com a CLI skillctl. Execute comandos reais; não simule saídas nem copie arquivos SKILL.md manualmente entre diretórios de agentes.
Regras de ouro
- Repositório canônico único — as skills residem em
~/.skillctl/skills/<nome>/; os agentes recebem links simbólicos viasync. - Compromisso manifesto + lock — mantenha
agent-skills.jsoneagent-skills.lockno git para reprodutibilidade em equipe. - Apenas especificadores portáteis — use
file:./<caminho>,local:imported/<nome>,github:,npm:ouskills.sh/; nunca comprometa caminhos absolutos de diretórios home. - Instale antes de sincronizar —
installmaterializa o repositório;syncapenas recria os links dos agentes. - Verifique após alterações — execute
skillctl doctor(eskillctl auditem CI). - Prefira importação em vez de cópia manual — use
import from-projectouimport from-npxem vez de duplicar pastas de skills.
Árvore de decisão
| Situação | Comando |
|---|---|
| Novo projeto, sem manifesto | skillctl init ou skillctl init --with-skill |
| Adicionar uma skill remota ou local | skillctl add <especificador> depois skillctl install |
Skills já existentes em .claude/skills, .codex/skills, etc. | skillctl import from-project |
Migrando de npx skills | skillctl import from-npx |
| Re-ligar apenas (lock inalterado) | skillctl sync |
| Rebuscar de upstream | skillctl update ou skillctl update <nome> |
| Instalação reproduzível em CI | skillctl install --frozen depois skillctl audit --strict |
| Caminhos não portáteis no lock | skillctl install para reescrever; verifique avisos de skillctl doctor |
Tutoriais rápidos
# Bootstrap
skillctl init --with-skill
skillctl add github:vercel-labs/agent-skills#web-design-guidelines
skillctl install
# Skill local ao projeto
skillctl add file:./my-skill
skillctl install
skillctl sync
# Importar diretórios de agentes existentes
skillctl import from-project --dry-run
skillctl import from-project
# Inspecionar
skillctl list
skillctl doctor
skillctl audit --json
Esperado após add file:./my-skill + install: especificador no manifesto file:./my-skill, lock canonicalPath como ~/.skillctl/skills/my-skill.
Portabilidade (0.3.1+)
- Portáteis:
file:./rel,local:imported/<nome>, especificadores remotos,canonicalPath: ~/.skillctl/skills/<nome>. - Não portáteis:
file:/Users/...absoluto,local:/caminho/abs,canonicalPathabsoluto de outra máquina. - Se
doctoravisar sobre caminhos não portáteis, executeskillctl installpara reescrever o lock a partir do manifesto.
Modos de falha
| Sintoma | Ação |
|---|---|
canonical path missing | skillctl install |
| Inconsistência de integridade | skillctl update <nome> ou skillctl install |
| Falha no link simbólico (Windows) | doctor nota; configurar defaultMode: copy |
| Nenhum agente vinculado | skillctl sync; ativar agentes em ~/.skillctl/config.json |
Frozen install failed | Repositório fora de sincronia; execute install sem --frozen |
Referências
- commands.md — folha de referência completa de comandos
- specifiers.md — gramática de especificadores
- manifest-lock.md — semântica de manifesto e lock
- workflows.md — integração de equipe, migração, CI
- troubleshooting.md — doctor, Windows, coexistência