Communitygithub.com

xFurti/skillctl

Gerenciador de pacotes universal para Skills de Agentes — manifesto, lockfile, sincronização multi-agente (Cursor, Claude, Codex, Gemini). Requer Node ≥22.13.

O que é skillctl?

skillctl é uma ferramenta de linha de comando que funciona como um gerenciador de pacotes universal para skills de agentes de IA, como Claude Code, Cursor, Codex e Gemini. Ele centraliza o armazenamento de skills em um diretório canônico `~/.skillctl/skills/` e, através do comando `sync`, cria links simbólicos nos diretórios de cada agente, eliminando a necessidade de cópias manuais e garantindo consistência entre ferramentas. A ferramenta suporta especificadores portáteis (como `file:./caminho`, `github:`, `npm:`) e gera um manifesto (`agent-skills.json`) e um lockfile (`agent-skills.lock`) que podem ser versionados em git para reprodutibilidade em equipe. Comandos como `import from-project` ou `from-npx` facilitam a migração de skills já existentes, enquanto `doctor`, `audit` e `--frozen` garantem a integridade do ambiente, especialmente em pipelines de CI.

Funciona com✓Claude Code✓Codex CLI✓Cursor✓Gemini CLI✓OpenCode
npx skills add xFurti/skillctl

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

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

  1. Repositório canônico único — as skills residem em ~/.skillctl/skills/<nome>/; os agentes recebem links simbólicos via sync.
  2. Compromisso manifesto + lock — mantenha agent-skills.json e agent-skills.lock no git para reprodutibilidade em equipe.
  3. Apenas especificadores portáteis — use file:./<caminho>, local:imported/<nome>, github:, npm: ou skills.sh/; nunca comprometa caminhos absolutos de diretórios home.
  4. Instale antes de sincronizar — install materializa o repositório; sync apenas recria os links dos agentes.
  5. Verifique após alterações — execute skillctl doctor (e skillctl audit em CI).
  6. Prefira importação em vez de cópia manual — use import from-project ou import from-npx em vez de duplicar pastas de skills.

Árvore de decisão

SituaçãoComando
Novo projeto, sem manifestoskillctl init ou skillctl init --with-skill
Adicionar uma skill remota ou localskillctl add <especificador> depois skillctl install
Skills já existentes em .claude/skills, .codex/skills, etc.skillctl import from-project
Migrando de npx skillsskillctl import from-npx
Re-ligar apenas (lock inalterado)skillctl sync
Rebuscar de upstreamskillctl update ou skillctl update <nome>
Instalação reproduzível em CIskillctl install --frozen depois skillctl audit --strict
Caminhos não portáteis no lockskillctl 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, canonicalPath absoluto de outra máquina.
  • Se doctor avisar sobre caminhos não portáteis, execute skillctl install para reescrever o lock a partir do manifesto.

Modos de falha

SintomaAção
canonical path missingskillctl install
Inconsistência de integridadeskillctl update <nome> ou skillctl install
Falha no link simbólico (Windows)doctor nota; configurar defaultMode: copy
Nenhum agente vinculadoskillctl sync; ativar agentes em ~/.skillctl/config.json
Frozen install failedRepositório fora de sincronia; execute install sem --frozen

Referências

Habilidades Relacionadas