@macrex/skills-cli

CLI para conectar skills de IA aos seus projetos.

Funciona com Claude Code, Codex CLI, Gemini CLI, Antigravity e VS Code Copilot Chat.

Instalação

npm install -g @macrex/skills-cli

Uso rápido

1. Rode skills.
2. Na primeira execução, configure o caminho do seu repositório de skills.
3. Use o shell para listar stacks e linkar no projeto atual.

skills

O shell abre com o Skilly (✦), o mascote do CLI, junto da versão, do hub de skills e do diretório atual. Digite / para ver os comandos disponíveis.

Fluxo básico

| Comando | O que faz | | :--- | :--- | | /setup | Configura ou troca o repositório de skills | | /find | Busca e instala skills do diretório global na comunidade | | /list | Lista as stacks disponíveis | | /add | Importa novas stacks a partir de um repositório Git ou do GitHub | | /link | Linka skills no projeto atual | | /re-link | Atualiza (re-linka) skills já linkadas em um projeto | | /projects | Painel global: skills por projeto e aplicação em massa | | /doctor | Diagnostica a integridade do projeto e aponta correções | | /describle | Resume as skills de uma stack, basic ou all |

/doctor roda tanto dentro do shell interativo quanto via skills doctor. Sem argumento, analisa a pasta atual; passe um caminho (skills doctor <path>) para verificar outro projeto. Fora do shell, sai com código 0 (ok) ou 1 (falhas), útil em scripts/CI.

No shell interativo

O shell tem uma caixa de input com borda arredondada, prompt > e um placeholder com a dica do momento. Autocomplete e navegação rápida:

• Digite / para ver os comandos principais. Comece a digitar e o filtro fuzzy completa (/prj encontra /projects); o item selecionado no dropdown é marcado com ❯.
• ↑↓ navegam o dropdown, Enter completa e executa, Tab apenas completa.
• O histórico de comandos é persistente entre sessões (navegável com ↑↓ na linha vazia).
• Comandos mais usados sobem no ranking do dropdown.
• ? com a linha vazia abre o painel de atalhos; Esc limpa a linha.
• Para sair, pressione Ctrl+C duas vezes (a primeira limpa a linha e avisa).

Buscando e importando Skills Globais

Se você não tiver a stack desejada no seu repositório local, utilize os comandos:

• /find <termo>: Abre uma pesquisa e um menu interativo para buscar skills no diretório da comunidade global. Ao selecionar, ela é automaticamente inspecionada e instalada no seu diretório skills-ia.
• /add <repo>: Baixa uma skill diretamente de um repositório git externo (ex: macrex/skills-ia-react) e adiciona ao seu hub.
• /update: Varre todas as suas skills (tanto as locais quanto as importadas de repositórios externos) para buscar atualizações com a última versão disponível em nuvem, oferecendo um menu seguro para upgrade.

Painel de projetos

/projects abre um painel com todos os projetos que têm skills linkadas, numa matriz projeto × skill que mostra o que está em dia, desatualizado ou ausente. A partir dele você pode entrar em um projeto, aplicar uma skill em todos os projetos de uma vez, ou atualizar os desatualizados em massa.

Diagnóstico (/doctor)

/doctor faz um checkup do projeto linkado e mostra cada item como ok, WARN ou FAIL, com a ação de correção sugerida. Ele valida:

• o hub .agents/skills/ e os symlinks de cada skill linkada;
• os arquivos e links gerenciados (registrados em .skills-ia.json);
• a fonte de skills configurada e a resolução de cada stack na origem.

Sem argumento, ele analisa a pasta atual. Dentro do shell ele apenas imprime o relatório; fora do shell (skills doctor [path]) ele também devolve um código de saída — 0 quando tudo está ok e 1 quando há falhas —, então dá para usar em scripts ou em CI.

Repositório de skills

O CLI espera um repositório com stacks e skills organizadas em pastas.

Exemplo mínimo:

meu-skills/
└── minha-stack/
    └── minha-skill/
        └── SKILL.md

Se o seu repositório também tiver recipes, o shell passa a expor esses comandos automaticamente.

Graphify

O CLI também dá suporte a um fluxo de mapa de repositório (grafo) com Graphify.

Use /graphify-ai no shell para ver como acionar a skill $graphify-ai, que gera o grafo local do repositório. Para enriquecer esse grafo com relações semânticas, use a skill $graphify-ai-semantic — /graphify-ai-semantic mostra como usá-la.

Mantendo o grafo atualizado

Para o grafo não ficar defasado conforme o projeto evolui, há dois modos:

• Automático — ao gerar o grafo, a skill $graphify-ai instala um git hook oficial do graphify. A partir daí, cada commit reconstrói o grafo estrutural (AST) de forma incremental e sem custo de API. O hook é local (.git/hooks/) e funciona mesmo com graphify-out/ no .gitignore.
• Sob demanda — invocar $graphify-ai para um rebuild completo e $graphify-ai-semantic para o enriquecimento semântico (relações INFERRED).

O modo automático cobre só o grafo estrutural. O enriquecimento semântico não roda no commit: rode $graphify-ai-semantic quando a documentação ou a arquitetura mudarem.

Solução de problemas

Agente de IA não responde no chat de um projeto

Sintoma: num projeto, o agente (Antigravity, e às vezes outras IAs) não responde nada no chat — ou nem inicia o turno, ou fica "gerando" e termina sem resposta. Em outros projetos o mesmo agente funciona normalmente.

Causa: o .git/config do projeto tem uma seção [extensions] com worktreeconfig = true. Isso costuma ser criado por ferramentas que usam git worktree (ex.: codex). A biblioteca git interna desses agentes (go-git) não suporta a extensão worktreeconfig e rejeita o repositório, então o agente não consegue resolver o contexto do workspace e não responde.

Diagnóstico:

1. Abra <projeto>/.git/config e procure uma seção [extensions].
2. Confirme nos logs do agente a mensagem: core.repositoryformatversion does not support extension: worktreeconfig seguida de failed to resolve workspace infos / workspace infos is nil. (No Antigravity: Help → Toggle Developer Tools, ou os logs em %APPDATA%\Antigravity\logs\<sessão>\ls-main.log.)

Correção (dentro da pasta do projeto):

git worktree prune                 # remove worktrees stale
git config --remove-section extensions

Depois reabra o projeto no agente. Se a ferramenta que criou o worktree rodar de novo, o problema pode voltar — basta repetir a correção.

Licença

MIT

Créditos

Este projeto usa Graphify como runtime upstream do fluxo de grafo local. Crédito ao projeto Graphify, ao autor Safi Shamsi e aos contribuidores do upstream: safishamsi/graphify e pacote PyPI graphifyy. O upstream publica licença MIT; esta integração mantém a atribuição ao projeto original.