cross-compatible-plugin

Skills que auditam e corrigem um plugin de agente para que um único repositório, sem código duplicado (DRY), funcione no GitHub Copilot CLI, no VS Code (agent plugins), no Claude Code e no OpenAI Codex.

Instalação

Clique no botão abaixo correspondente a sua edição do VS Code e confirme o prompt de instalação no editor.

imageInstalar Plugin de Chat no VS Code

imageInstalar Plugin de Chat no VS Code Insiders

Execução orquestrada

O slash command inicia o fluxo completo com um caminho opcional:

/plugin-cross ../meu-plugin
/plugin-cross

Sem caminho, o agente plugin-cross-orchestrator detecta a raiz mais provável no workspace e pede confirmação. Ele coordena as skills de auditoria, correção e badges, mas mantém aprovações separadas para aplicar correções, substituir duplicatas idênticas e alterar o README.

Como o plugin se comporta

O fluxo nunca altera arquivos sem aprovação explícita:

1. Auditoria (plugin-cross-audit): roda os três validadores e grava .compat-report.json.
2. Relatório e dry-run: mostra os findings por gravidade (error, warning, info) e as correções propostas.
3. Aprovação das correções: espera um "sim" explícito.
   • Sim: plugin-cross-fix move os arquivos para a fonte canônica e cria links relativos por arquivo.
   • Não: segue sem alterar os arquivos.
4. Reauditoria: executa novamente os validadores após a decisão.
5. Preview dos badges (readme-install-badge): confirma o repositório e mostra as alterações propostas para o README.
6. Aprovação do README: espera uma nova confirmação explícita.
   • Sim: adiciona os badges.
   • Não: segue sem alterar o README.
7. Relatório final: apresenta o estado resultante da execução.

O agente e o comando têm fontes canônicas em agents/ e commands/. Claude Code lê essas fontes; Copilot CLI e VS Code usam os links em com.github.copilot/.

Skills

Todas as regras ficam em lib/compat-rules.mjs, e o formato do relatório em lib/report.mjs.

Estrutura que o plugin valida

Cada conteúdo tem uma fonte canônica (arquivo real). Os outros clientes chegam a ela por symlinks relativos, um por arquivo:

Regras de compatibilidade aplicadas:

• Manifesto: plugin.json usa $schema Agent Plugins 1.0 e só os campos permitidos. O Claude ignora o $schema, e o Codex usa name, version e description.
• MCP: type explícito (stdio, streamable-http, sse). .mcp.json só vira link se não houver ${PLUGIN_ROOT} nem ${CLAUDE_PLUGIN_ROOT}, porque cada cliente só expande o próprio token.
• Hooks: formato do Claude (PascalCase + matcher), apenas com os eventos comuns: SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, PreCompact, SubagentStart, SubagentStop, Stop. O VS Code ignora matcher, então filtre também dentro do script.
• Agentes: name no frontmatter é obrigatório e igual ao nome do arquivo. Sem ele, o Claude nomeia o agente <id>.agent.
• Skills: name igual ao nome da pasta, em kebab-case.
• Instruções: CLAUDE.md e AGENTS.md na raiz do plugin não são carregados por nenhum cliente. Use uma skill.
• Removido: .plugin/plugin.json, o formato OpenPlugin legado, que conflita com o 1.0.

Guardrails

1. Nenhuma alteração sem o OK explícito do usuário. Os scripts de correção rodam em dry-run por padrão. plugin-cross-fix exige --apply --confirm.
2. Nunca sobrescreve e nunca apaga arquivos divergentes. Conflitos são reportados (código 5). Duplicatas byte a byte idênticas só viram link com --replace-identical.
3. Links sempre relativos, por arquivo e dentro da raiz do plugin. Links de pasta, absolutos ou que saem da raiz são erros.
4. Recusa cópias instaladas ou em cache (~/.vscode*/agent-plugins, ~/.copilot/installed-plugins, ~/.claude/plugins/cache, …): código 4. A auditoria dessas cópias é permitida, com aviso.
5. Revalida antes de agir. A correção confere o estado atual de cada caminho, então um relatório desatualizado não causa estragos.
6. Sem rede e sem prompts interativos. JSON no stdout, diagnósticos no stderr, --help em todos os scripts.
7. Pode rodar várias vezes. Uma segunda execução não faz nada.

Códigos de saída

Uso rápido

node skills/plugin-cross-audit/scripts/aggregate.mjs --root ../meu-plugin
node skills/plugin-cross-fix/scripts/fix.mjs --report ../meu-plugin/.compat-report.json
node skills/plugin-cross-fix/scripts/fix.mjs --report ../meu-plugin/.compat-report.json --apply --confirm
node skills/readme-install-badge/scripts/add-badge.mjs --root ../meu-plugin --apply

Requisitos: Node.js 18+. O git é opcional (usado para git mv e para detectar core.symlinks).

Limitações conhecidas

• tools no frontmatter: nomes como vscode/memory são do VS Code/Copilot. No Claude Code, tools funciona como allowlist, então o agente pode perder ferramentas. A skill avisa, mas não corrige.
• Codex: não lê os agentes e comandos Markdown deste plugin (usa TOML próprio para agentes). Manifesto e skills funcionam.
• Symlinks não documentados: nenhuma documentação cobre como o Codex trata um manifesto por link, nem como o Copilot e o VS Code tratam links ao instalar via git. Valide com uma instalação real.
• Windows: com core.symlinks=false, os links viram arquivos de texto (validate-links avisa).
• LSP: os formatos diferem por cliente, então este plugin não tenta unificá-los.

Desenvolvimento

node --test tests/*.test.mjs

Fontes

• Agent Plugins Specification 1.0.0 e mcp.schema.json
• Agent Skills specification e Using scripts in skills
• GitHub Copilot CLI plugin reference e hooks reference
• VS Code agent plugins
• Claude Code plugins
• OpenAI Codex plugins