🦜 polyskill — skills cross-runtime

Spec aberta originada na Anthropic e adotada por 40+ ferramentas. Define o formato canônico de skill: arquivo SKILL.md, frontmatter com name e description, corpo markdown, convenção de pastas scripts/, references/, assets/.

É o denominador comum real. Tudo que você escreve dentro dessa spec funciona em qualquer runtime compatível. Tudo fora vira amarra a um runtime só.

Os 4 pilares (SKILL.md, name, description, body), convenção de pastas, compromisso aberto, agentskills.io como autoridade.

Você cria uma skill no Claude. Copia/adapta pro Codex. Funciona. Uma semana depois, melhora a do Claude. Esquece de propagar. Depois melhora a do Codex. Esquece. Em um mês são duas skills DIFERENTES, e ninguém sabe qual está certa.

Sem entender a dor, polyskill parece overkill. Quem já sofreu drift de skill (ou pior, perdeu uma versão) entende o valor imediatamente.

Drift orgânico, fork acidental, fonte de verdade ambígua, custo cognitivo de "qual versão é a boa", quebra de funcionalidade silenciosa.

Você escreve a skill UMA vez no formato canônico portable (definition.md). O polyskill compila pra dist/claude/ e dist/codex/, cada um otimizado pro runtime alvo. Como Babel/TypeScript pra skills.

Esse é o "aha moment". Uma vez que clica que a skill é fonte e os dois outputs são gerados, todo o resto do polyskill faz sentido.

Source canônico, build artifacts (dist/), compilação seletiva por target, otimização por runtime (truncar description, reescrever injeção).

(1) IR — Representação Interna neutra, sem amarras de runtime; (2) Adapters — 1 arquivo TypeScript por runtime, sabe ler E escrever o formato dele; (3) CLI — orquestra os adapters pelo registry.

Adicionar runtime novo é literalmente um arquivo: o adapter. Entendendo isso, você sabe que Gemini, Cursor, Copilot são "só" novos adapters — não rewrite do polyskill.

Compilador frontend/middle/backend, plugin via registry, interface Adapter (parse, emit, validate), separação de concerns.

Adapter "lê E escreve". Você pode importar uma skill existente do Claude (--from claude), virar portable, daí emitir pros dois. Mesma coisa começando do Codex (--from codex).

Você não precisa começar do zero. Tem uma skill de Claude que adora? Importa, gera portable, daí emite. Tem uma do Codex? Mesma coisa pelo outro lado.

Bidirecionalidade obrigatória do adapter, lossy vs lossless, suporte a scripts/, references/, assets/ em todas direções.

Toda vez que faz build, polyskill calcula hash dos arquivos gerados. No build seguinte, se algum arquivo de alvo foi editado à mão, o build aborta com erro. Você decide: --force (sobrescreve) ou polyskill reconcile (inspeciona o drift).

Sem isso, você ajustaria à mão um output do Claude pra um caso específico, faria build no dia seguinte, perderia o ajuste. Drift policy é a apólice.

Hash de arquivo, detecção de modificação fora-da-banda, opt-in pra sobrescrever (--force), reconcile interativo, princípio "no silent loss".

O próprio polyskill vem como skill instalável nos dois runtimes. Você invoca em linguagem natural: /polyskill converte minha skill x pra funcionar nos dois (Claude) ou $polyskill converte ... (Codex). A skill chama o CLI por baixo.

Você nunca decora flag. Pede em PT-BR, a skill traduz pra polyskill import --from claude, polyskill build, etc.

Skill como wrapper de CLI, NL interface, Caminho A (drag&drop sem CLI) vs Caminho B (fonte + CLI), dogfooding.

A: copia skill/dist/claude/polyskill pra ~/.claude/skills/ e skill/dist/codex/polyskill pra ~/.agents/skills/. Funciona como skill. B: clona repo, npm install && npm run build && npm link, ganha o CLI completo.

Caminho A só roda a skill — sem CLI, alguns comandos quebram. Caminho B é completo. Pra construir suas próprias skills cross-runtime, B é obrigatório.

Bundle pré-buildado vs source, npm link, validação com polyskill --version e polyskill detect.

Comando que cria um workspace de skill com a estrutura portable: definition.md (frontmatter YAML + body), pastas scripts/, references/, assets/, e config do build.

Skill nova começa aqui. Você nunca cria SKILL.md à mão — cria definition.md uma vez, polyskill cuida do resto.

Estrutura inicial, definition.md vs SKILL.md, frontmatter mínimo, edição interativa do body.

Aponta pra uma skill existente em qualquer runtime e gera o workspace portable equivalente. Funciona nos dois sentidos: --from claude pega de .claude/skills/, --from codex pega de .agents/skills/.

Você tem 10 skills do Claude que adora. Importa cada uma com um comando, daí roda build e ganha versão Codex de cada. Reverse engineering grátis.

Importação preserva scripts/references/assets, normalização do frontmatter, conversão de injeção dinâmica em prosa quando vier do Claude.

Gera dist/claude/<skill>/SKILL.md e dist/codex/<skill>/SKILL.md (+ sidecar agents/openai.yaml quando há branding ou MCP deps). É o passo de compilação.

É o comando que você roda toda vez que edita definition.md. Pode (e deve) ir num watch ou pre-commit hook.

Cache de hash, flag --force pra sobrescrever drift, dist como output gitignorável (mas o repo do polyskill commita pra ilustrar).

Combina build + copy pros diretórios canônicos: ~/.claude/skills/<skill> e ~/.agents/skills/<skill>. Skill fica instantaneamente disponível nos dois runtimes.

É o comando do "deploy local". Editou, testa rodando install, invoca no terminal do Claude OU do Codex, sem mexer manualmente em pastas.

Reload automático (Claude) vs refresh manual (Codex), idempotência, escopo (global vs projeto), uninstall (rm direto da pasta).

detect diz quais runtimes estão na máquina; status diz quais alvos estão em sync com o último build; adapters lista os adapters instalados (hoje: portable, claude, codex).

Pra debug. Skill não dispara? Roda detect pra ver se o runtime está visível. Build estranho? status mostra o que está dessincronizado.

Comandos read-only, parseable pra script, output JSON quando --json, troubleshooting sem editar nada.

validate roda linter por adapter (regras por alvo: limite de description no Codex, sintaxe de injeção no Claude, etc.). reconcile compara dist/ com os diretórios instalados e mostra divergências, oferecendo merge guiado.

Validate roda no CI antes de merge. Reconcile resolve a situação real "alguém editou à mão fora do polyskill".

Regras por adapter, exit code 0 vs 1 pra CI, drift report interativo, decisão "manter override / sobrescrever / fundir".