@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

Dentro do shell, digite / para ver os comandos disponíveis.

Fluxo básico

| Comando | Uso | |---------|-----| | /setup | Configura ou troca o repositório de skills | | /list | Lista as stacks disponíveis | | /link | Linka skills no projeto atual | | /update | Atualiza skills já linkadas em um projeto | | /unlink | Remove as skills linkadas | | /projects | Painel global: skills por projeto e aplicação em massa | | /describle | Resume as skills de uma stack, basic ou all | | /history | Mostra as últimas versões do CLI |

skills doctor <path> verifica a consistência de um projeto linkado — disponível fora do shell interativo.

No shell interativo

O shell tem autocomplete e navegação rápida:

• Digite / para ver os comandos principais. Comece a digitar e o filtro fuzzy completa (/prj encontra /projects).
• ↑↓ 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.

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.

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.