DariyXYZ/codex-skill-toolkit-for-claude

Kit de Ferramentas de Skill: Claude para Codex

Propósito

Gerencie todo o ciclo de vida de migração de skills do Claude para o Codex:

• Inspecionar um repositório GitHub ou pasta local de skill
• Inspecionar snippets de shell que criam manualmente .claude/skills/<nome>/skill.md
• Escolher a rota segura mais curta: instalação direta ou migração
• Classificar a dica de instalação que o usuário encontrou em um tutorial do Claude
• Pontuar compatibilidade, risco de dependência e nível de instalação antes de agir
• Reescrever metadados críticos para descoberta quando necessário
• Validar que o Codex pode realmente descobrir o resultado
• Empacotar o skill finalizado para reutilização ou publicação no GitHub

Use este skill tanto para instalações avulsas quanto para construir um porte portátil, polido e nativo do Codex.

Acionamento Automático

Ative quando a solicitação incluir ideias como:

• instalar este skill do Claude no Codex
• migrar este skill do Claude Code
• portar este skill para o Codex
• adaptar este skill para o Codex
• este comando mkdir/printf .claude/skills/.../skill.md realmente instalará um skill
• por que este skill instalado não está aparecendo
• empacotar este skill migrado para o GitHub
• revisar se este skill do Claude funcionará no Codex

Trate os seguintes como sinais diretos orientados ao Claude, mesmo que o usuário diga apenas "instale este skill" e cole um link:

• URLs do GitHub ou referências owner/repo sob anthropics/, especialmente anthropics/skills
• URLs, nomes de repositórios ou texto que mencionem Claude, Claude Code, Anthropic ou anthropics
• caminhos ou snippets contendo .claude/skills, .claude-plugin, skill.json ou marketplace.json
• comandos como /plugin marketplace add, /plugin install ou /plugin add
• fluxos de upload ZIP específicos do Claude ou referências à API Skills

Quando algum desses marcadores estiver presente, use este skill primeiro antes de depender da instalação direta bruta.

Seleção Rápida de Rota

Escolha a rota mais curta que ainda seja confiável.

1. Se o repositório já contiver um SKILL.md limpo e a estrutura de pastas for óbvia, instale a pasta exata do skill primeiro, depois valide a descoberta.
2. Se o repositório contiver layouts específicos de plataforma, como .claude/skills, .claude-plugin ou skill.json, inspecione esses sinais antes de decidir que não é instalável.
3. Se o usuário fornecer um snippet de shell que cria .claude/skills/<nome>/skill.md, trate-o como um scaffold local e inspecione a pasta gerada antes de considerá-lo instalado.
4. Se o repositório for específico do Claude, ambíguo, multi-skill ou ainda usar suposições exclusivas do Claude, migre antes de declarar sucesso.
5. Se a tarefa for apenas avaliação, inspecione o repositório e explique a compatibilidade sem instalar nada.
6. Se o usuário quiser um artefato compartilhável, construa um pacote nativo do Codex limpo, com estrutura mínima e notas de validação.

Use scripts/inspect_skill_repo.py quando uma pasta local estiver disponível e a estrutura do repositório não for óbvia. Use scripts/check_skill_md.py quando precisar de uma verificação determinística de frontmatter ou problemas de BOM. Use scripts/classify_install_hint.py quando o usuário colar um comando de tutorial do Claude ou snippet de instalação e você precisar mapeá-lo para uma rota do Codex. Use scripts/trigger_score.py quando a instalabilidade parecer boa, mas você precisar saber se o skill realmente corresponderá bem a prompts reais do usuário. Use scripts/generate_install_report.py para deixar para trás uma análise Markdown legível após cada revisão de instalação. Use scripts/install_skill_flow.py quando quiser um seletor de rota semiautomático que também possa copiar um skill local escolhido para o Codex.

Fluxo de Trabalho Principal

1. Inspecione a origem. Leia a estrutura do repositório, localize skills/, SKILL.md, scripts auxiliares e quaisquer suposições de empacotamento exclusivas do Claude.

2. Decida a rota. Use references/compatibility-matrix.md para decidir entre instalação direta, adaptação leve ou migração completa. Se o usuário copiou um comando de tutorial, normalize-o primeiro com references/install-route-adaptation.md.

3. Execute a menor mudança viável.

• Instalação direta se a origem já for amigável ao Codex.
• Reescreva SKILL.md e arquivos de suporte se a qualidade da descoberta ou dos triggers for fraca.
• Divida orientações longas em references/ ao construir um porte durável para o Codex.
• Use a pontuação de compatibilidade e o nível de instalação para explicar por que uma rota é segura ou arriscada.
• Gere um relatório de instalação sempre que o resultado for revisado depois, compartilhado ou usado como registro de migração.

4. Valide, não suponha. Sempre verifique:

• se a pasta do skill existe onde pretendido
• se SKILL.md é amigável ao parser
• se o arquivo está em UTF-8 sem BOM
• se codex debug prompt-input expõe o skill quando o destino é uma instalação ativa do Codex

5. Empacote de forma limpa quando solicitado. Para GitHub ou compartilhamento, mantenha uma pasta canônica de skill com:

• SKILL.md
• agents/openai.yaml quando útil
• references/ apenas para material que vale a pena carregar sob demanda
• scripts/ apenas para helpers determinísticos

Caminho Rápido para Repositórios de Skill no GitHub

Quando o usuário fornecer um repositório GitHub ou URL de skill:

1. Inspecione primeiro a raiz do repositório e skills/.
2. Inspecione também .claude/skills, skill.json na raiz e .claude-plugin/plugin.json antes de decidir que o repositório é apenas documentação ou um catálogo.
3. Se o repositório, proprietário, caminho ou texto ao redor carregar sinais orientados ao Claude, como anthropics/skills, Claude, Anthropic ou .claude/*, permaneça no fluxo deste kit de ferramentas mesmo quando o caminho do skill parecer óbvio.
4. Instale a pasta exata do skill, não o repositório inteiro, quando o caminho de destino for claro.
5. Leia o SKILL.md instalado imediatamente após a instalação.
6. Pare se a descoberta já estiver limpa e a qualidade do trigger for aceitável.
7. Mude para migração se o skill instalado estiver invisível, com nome vago, malformado, descrito de forma fraca ou ainda exclusivo do Claude.

Tenda a instalações exatas com --repo mais --path quando você puder inferir o caminho com confiança.

Caminho Rápido para Snippets de Shell Locais do Claude

Quando o usuário fornecer um snippet de shell como mkdir ... .claude/skills/... && printf ... > skill.md:

1. Trate-o como um scaffold local, não como prova de que um skill publicado foi instalado.
2. Inspecione a pasta gerada diretamente.
3. Normalize skill.md ou Skill.md para SKILL.md.
4. Converta seções de metadados em Markdown para frontmatter YAML quando necessário.
5. Somente após a normalização você deve afirmar que o skill está pronto para o Codex.

Regras de Migração

Quando a migração for necessária:

1. Preserve o comportamento, não o empacotamento original.
2. Reescreva o frontmatter para que name e description expressem claramente tanto a função quanto as frases de trigger.
3. Mantenha o corpo conciso e operacional.
4. Mova playbooks longos, mapeamentos e solução de problemas para references/.
5. Evite aliases duplicados, a menos que haja um motivo real de descoberta.

Para a sequência completa, leia references/migration-playbook.md.

Regras de Descoberta

• Trate "instalado no disco, mas ausente em codex debug prompt-input" como uma instalação falha.
• Salve SKILL.md como UTF-8 sem BOM.
• Prefira uma pasta canônica por skill.
• Mantenha o frontmatter simples.
• Faça a description rica em triggers o suficiente para que o Codex possa corresponder à formulação real do usuário.

Se a descoberta estiver quebrada, use references/discovery-troubleshooting.md.

Regras de Empacotamento

Ao construir um porte portátil nativo do Codex:

• publique a própria pasta canônica do skill
• evite arquivos de documentação extras, a menos que o usuário explicitamente queira documentação voltada ao repositório
• mantenha os scripts auxiliares genéricos e determinísticos
• não envie variantes migradas duplicadas do mesmo skill
• se um repositório contiver múltiplos skills, empacote cada um como uma pasta de skill distinta

Validação Necessária

Antes de considerar a migração concluída, verifique:

• scripts/check_skill_md.py <caminho-para-skill-md> não relata problemas bloqueantes
• scripts/inspect_skill_repo.py <caminho-para-pasta-do-skill> mostra a estrutura esperada
• a pontuação de compatibilidade, o perfil de dependência e o nível de instalação são sensatos para a rota escolhida
• a qualidade do trigger é boa o suficiente para prompts realistas, ou o relatório explica claramente por que o polimento da migração ainda é necessário
• codex debug prompt-input mostra o skill quando instalado em um diretório de skills ativo do Codex

Guia de Referência

Leia apenas o que for necessário:

• references/migration-playbook.md para a sequência completa de migração
• references/compatibility-matrix.md para seleção de rota
• references/install-route-adaptation.md para traduzir tutoriais de instalação do Claude em ações do Codex
• references/install-workflow.md para o padrão de instalador semiautomático
• references/discovery-troubleshooting.md para análise de falhas