repo-to-skill

CLI para gerar uma "skill" (mapa + chunks em markdown) a partir de um repositório TypeScript/JavaScript, tornando-o legível por IAs como Claude e Codex sem precisar carregar todos os arquivos.

O que é / Para que serve

repo-to-skill analisa um repositório TS/JS local e gera arquivos markdown estruturados que permitem que assistentes de IA entendam a base de código com eficiência:

• Menos tokens: apenas os arquivos relevantes, em chunks gerenciáveis.
• Sem envio para nuvem: toda a análise acontece localmente.
• Integração direta: instala referências em CLAUDE.md e AGENTS.md.

Requisitos

• Node.js 20 ou superior
• macOS ou Linux (Windows não suportado)

Como usar

Execute sem instalação global:

npx repo-to-skill

Ou instale globalmente:

npm install -g repo-to-skill
repo-to-skill

Primeiro uso (projeto sem skill gerada)

Ao rodar repo-to-skill pela primeira vez em um repositório:

1. O assistente interativo abre com um banner mostrando a versão.
2. Você escolhe o repositório: diretório atual ou informa um caminho.
3. O menu exibe:
   • Gerar skill — gera a skill e instala os targets escolhidos
   • Atualizar CLI — verifica e atualiza a ferramenta
   • Ajuda — exibe instruções
   • Sair
4. Escolha Gerar skill:
   • Selecione os targets (codex, claude ou ambos).
   • Escolha o modo de instalação (force / merge / skip).
   • Confirme o resumo.
5. O CLI executa:
   • Cria .repo-to-skill/
   • Gera a skill (index, mapa, chunks)
   • Instala os targets selecionados
   • Adiciona .repo-to-skill/ ao .gitignore do repositório automaticamente

Uso recorrente (skill já gerada)

Ao rodar repo-to-skill em um repositório já inicializado, o assistente vai direto para o menu de ações:

• Atualizar skill — atualiza incrementalmente com base nas mudanças desde a última geração
• Instalar target — instala referência da skill em CLAUDE.md ou AGENTS.md (targets já instalados aparecem desabilitados)
• Atualizar CLI — verifica se há nova versão no npm
• Ajuda
• Sair

Arquivos gerados

Todos os arquivos são criados dentro do repositório alvo:

.repo-to-skill/
├── manifest.json          # estado interno (não comitar)
└── out/
    ├── index.md           # índice da skill — carregue primeiro
    ├── repo.map.md        # inventário de todos os arquivos
    └── chunks/
        ├── chunk-001.md
        ├── chunk-002.md
        └── ...

O arquivo .repo-to-skill/ é adicionado automaticamente ao .gitignore do repositório na primeira execução.

Instalar targets

Os targets instalam uma referência da skill nos arquivos de contexto de IA:

| Target | Arquivo gerado | Usado por | |--------|---------------|-----------| | codex | AGENTS.md | OpenAI Codex / GPT com agentes | | claude | CLAUDE.md | Claude Code |

O bloco inserido indica onde o índice da skill está localizado. O AI pode então carregar os chunks sob demanda.

Modos de instalação:

• force — sobrescreve o arquivo existente
• merge — atualiza apenas o bloco gerenciado (preserva conteúdo fora do bloco)
• skip — não altera se o arquivo já existir

Atualizar a CLI

Via assistente interativo:

1. Escolha Atualizar CLI no menu.
2. O CLI verifica a versão mais recente no npm.
3. Se houver atualização, oferece executar npm install -g repo-to-skill@latest.

Ou diretamente:

npm install -g repo-to-skill@latest

Limitações

• Sistema operacional: macOS e Linux apenas. Windows não é suportado.
• Linguagem: repositórios TypeScript e JavaScript apenas.
• Sem rede durante geração: build e update são 100% offline. Apenas Atualizar CLI acessa a internet (npm registry).
• Lockfiles ignorados: pnpm-lock.yaml, yarn.lock, package-lock.json e npm-shrinkwrap.json são sempre excluídos da skill.
• Binários ignorados: imagens, PDFs, executáveis e outros binários são excluídos automaticamente.

Licença

MIT