🦜 polyskill — skills cross-runtime

Especificación abierta originada en Anthropic y adoptada por más de 40 herramientas. Define el formato canónico de Skill: archivo SKILL.md, frontmatter con name e description, cuerpo en Markdown, convención de carpetas scripts/, references/, assets/.

Es el denominador común real. Todo lo que escribas dentro de esta especificación funciona en cualquier runtime compatible. Todo lo que quede fuera te ata a un solo runtime.

Los 4 pilares (SKILL.md, name, description, body), la convención de carpetas, el compromiso abierto y agentskills.io como autoridad.

Creas una skill en Claude. La copias/adaptas para Codex. Funciona. Una semana después, mejoras la de Claude. Olvidas propagar los cambios. Luego mejoras la de Codex. Lo olvidas. En un mes, son dos skills DIFERENTES y nadie sabe cuál es la correcta.

Sin entender el problema, polyskill parece excesivo. Quien ya sufrió el drift de una skill (o, peor aún, perdió una versión) entiende su valor de inmediato.

Drift orgánico, fork accidental, fuente de verdad ambigua, costo cognitivo de «cuál versión es la buena», pérdida silenciosa de funcionalidad.

Escribes la skill UNA vez en el formato portable canónico (definition.md). El polyskill compila para dist/claude/ e dist/codex/, cada uno optimizado para el runtime de destino. Como Babel/TypeScript para skills.

Este es el «aha moment». Una vez que entiendes que la skill es la fuente y que se generan ambas salidas, todo lo demás de polyskill tiene sentido.

Source canónica, artefactos de compilación (dist/), compilación selectiva por target, optimización por runtime (truncar la descripción, reescribir la inyección).

(1) IR — Representación Interna neutral, sin ataduras de runtime; (2) Adaptadores — 1 archivo TypeScript por runtime, sabe leer Y escribir su propio formato; (3) CLI — orquesta los adapters mediante el registry.

Agregar un runtime nuevo literalmente requiere un archivo: el adaptador. Si entiendes esto, sabes que Gemini, Cursor y Copilot son «solo» nuevos adaptadores, no una reescritura de polyskill.

Compilador frontend/middle/backend, plugin vía registry, interfaz Adapter (parse, emit, validate), separación de concerns.

Adapter "lee Y escribe". Puedes importar una skill existente de Claude (--from claude), convertirlo en portable y luego emitirlo para ambos. Lo mismo empezando desde Codex (--from codex).

No tienes que empezar de cero. ¿Hay una skill de Claude que te encanta? Impórtala, genera la versión portable y luego expórtala. ¿Tienes una de Codex? Lo mismo desde el otro lado.

Bidireccionalidad obligatoria del adapter, con pérdida frente a sin pérdida, compatibilidad con scripts/, references/, assets/ en todas las direcciones.

Cada vez que haces un build, polyskill calcula el hash de los archivos generados. En el siguiente build, si editaste a mano algún archivo de destino, el build se aborta con un error. Tú decides: --force (sobrescribe) o polyskill reconcile (inspecciona el drift).

Sin esto, ajustarías manualmente un output de Claude para un caso específico, harías el build al día siguiente y perderías el ajuste. La drift policy es la póliza.

Hash de archivo, detección de modificación externa, consentimiento para sobrescribir (--force), reconciliación interactiva, principio "no silent loss".

El propio polyskill viene como skill instalable en los dos runtimes. Lo invocas en lenguaje natural: /polyskill converte minha skill x pra funcionar nos dois (Claude) o $polyskill converte ... (Codex). La skill llama al CLI por debajo.

Nunca memorizas flags. Lo pides en PT-BR y la skill lo traduce a polyskill import --from claude, polyskill build, etc.

Skill como wrapper de CLI, interfaz en lenguaje natural, Ruta A (arrastrar y soltar sin CLI) vs. Ruta B (fuente + CLI), dogfooding.

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

El Camino A solo ejecuta la skill: sin CLI, algunos comandos fallan. El Camino B es completo. Para crear tus propias skills cross-runtime, B es obligatorio.

Bundle precompilado frente a source, npm link, validación con polyskill --version e polyskill detect.

Comando que crea un workspace de skill con la estructura portable: definition.md (frontmatter YAML + cuerpo), carpetas scripts/, references/, assets/, y configuración del build.

La skill nueva empieza aquí. Nunca creas SKILL.md a mano: creas definition.md una vez y polyskill se encarga del resto.

Estructura inicial, definition.md vs SKILL.md, frontmatter mínimo, edición interactiva del body.

Indica una skill existente en cualquier runtime y genera el workspace portable equivalente. Funciona en ambos sentidos: --from claude toma de .claude/skills/, --from codex toma de .agents/skills/.

Tienes 10 skills de Claude que te encantan. Importa cada una con un comando y luego ejecuta build y genera una versión para Codex de cada uno. Ingeniería inversa gratis.

La importación preserva scripts/references/assets, normaliza el frontmatter y convierte la inyección dinámica en prosa cuando viene de Claude.

Genera dist/claude/<skill>/SKILL.md e dist/codex/<skill>/SKILL.md (+ sidecar agents/openai.yaml (cuando hay branding o dependencias MCP). Es el paso de compilación.

Es el comando que ejecutas cada vez que editas definition.md. Puede (y debe) ir en un watch o un hook pre-commit.

Caché de hash, flag --force para sobrescribir diferencias, dist como salida ignorable por git (pero el repo de polyskill hace commit para ilustrarlo).

Combina build + copy para los directorios canónicos: ~/.claude/skills/<skill> e ~/.agents/skills/<skill>. La skill queda disponible al instante en ambos runtimes.

Es el comando del "deploy local". Si editas, pruébalo ejecutando install, invócala en la terminal de Claude O de Codex, sin manipular las carpetas manualmente.

Recarga automática (Claude) vs actualización manual (Codex), idempotencia, alcance (global vs proyecto), desinstalación (rm directo de la carpeta).

detect indica qué runtimes están en la máquina; status indica qué destinos están sincronizados con la última compilación; adapters lista los adapters instalados (hoy: portable, claude, codex).

Para depurar. ¿La skill no se activa? Ejecuta detect para ver si el runtime está visible. ¿Build extraño? status muestra qué está desincronizado.

Comandos de solo lectura, analizables por script, output JSON cuando --json, solución de problemas sin editar nada.

validate ejecuta un linter por adapter (reglas por objetivo: límite de description en Codex, sintaxis de inyección en Claude, etc.). reconcile compara dist/ con los directorios instalados y muestra las divergencias, ofreciendo una fusión guiada.

Validate se ejecuta en CI antes del merge. Reconcile resuelve la situación real de "alguien editó manualmente fuera de polyskill".

Reglas por adapter, exit code 0 vs 1 para CI, informe de drift interactivo, decisión «mantener override / sobrescribir / fusionar».