5.2 CLI polyskill en la práctica

🎯Lo que obtienes aquí

Conocer cada comando del CLI en detalle. Terminar sabiendo cuál usar en cada situación (instalar, importar una skill existente, hacer build, validar, gestionar el drift) y qué esperar del output.

Contenido detallado

📥 Instalación — Ruta A vs. Ruta B

Dos formas de instalar, según lo que necesites. A es más rápido, pero limitado. B es completo — necesario para crear tus propias skills.

A. Arrastrar y soltar (sin CLI)

# Claude Code
cp -r skill/dist/claude/polyskill \
  ~/.claude/skills/polyskill

# OpenAI Codex
cp -r skill/dist/codex/polyskill \
  ~/.agents/skills/polyskill

La skill funciona con la invocación en lenguaje natural. Pero si necesita ejecutar polyskill build por debajo, falla — la CLI no está en el PATH.

B. Source + CLI (completo)

git clone \
  https://github.com/inematds/pollyskill
cd pollyskill
npm install
npm run build
npm link

# Confirma
polyskill --version
polyskill detect

# Instala a meta-skill
cd skill && polyskill install

CLI en el PATH. Puedes hacerlo todo: crear skills, importar, compilar, instalar, reconcile.

💡Cuál elegir

Si solo quieres USAR skills cross-runtime existentes, A basta. Si vas a CREAR/PORTAR tus propias skills, B es obligatorio. Si tienes dudas, elige B: no tiene desventajas.

Conceptos clave

Bundle precompilado
Camino A

npm link
CLI en el PATH

polyskill detect
Valida la instalación

Dist commitado
Skills/dist/* en el repo

🚀 polyskill init <nome>

Crea un workspace de skill portable desde cero. Estructura inicial con definition.md stub, carpetas convencionadas, configuración de build. Nunca creas SKILL.md a mano.

En acción

$ polyskill init my-reviewer
✓ Created workspace: ./my-reviewer

Structure:
  ./my-reviewer/
  ├── definition.md       # edit this
  ├── scripts/            # empty
  ├── references/         # empty
  ├── assets/             # empty
  └── .polyskill.json     # config

Next steps:
  cd my-reviewer
  $EDITOR definition.md
  polyskill build

definition.md inicial

---
name: my-reviewer
description: Use when... [edit this]
---

# My Reviewer

Edite o corpo aqui. Suporta markdown padrão.

Pode referenciar arquivos relativos: `./references/x.md`
Pode delegar pra scripts: `./scripts/check.sh`

Conceptos clave

Estructura inicial
Todo listo

definition.md
No es SKILL.md

.polyskill.json
Configuración local

Stub listo
Solo editar

📤 polyskill import <path> --from claude|codex

Toma una skill existente en cualquier runtime y genera un workspace portable equivalente. Bidireccional: --from claude toma de .claude/skills/, --from codex toma de .agents/skills/.

En acción — importando una skill de Claude

$ polyskill import ~/.claude/skills/code-reviewer \
    --from claude

✓ Parsed ~/.claude/skills/code-reviewer/SKILL.md
✓ Copied 2 scripts, 3 references, 0 assets
⚠ Converted 2 backtick-bang occurrences → prose fallback (with annotation in IR)
✓ Wrote ./code-reviewer/definition.md
✓ Workspace created

Next steps:
  cd code-reviewer
  polyskill build
  polyskill install   # instala nos DOIS runtimes

✓ Lo que conserva la importación

• Todos los archivos en scripts/, references/, assets/
• Frontmatter (name + description)
• Body completo en markdown
• Enlaces relativos

⚠ Lo que se convierte

• Backtick-bang (Claude) → prosa de respaldo + marcador en la IR
• allowed-tools (Claude) → IR genérico de restricción de herramientas
• Sidecar openai.yaml (Codex) → IR de branding + mcp_deps
• Description larga → se mantiene (el front-loading solo se hace en el build para Codex)

💡Ingeniería inversa gratis

¿Tienes 10 skills de Claude que te encantan? Importa cada una con un comando y luego polyskill build genera una versión para Codex de cada uno. Ida y vuelta: empezó siendo solo para Claude y ahora funciona en ambos. Lo mismo si empezaste en Codex.

Conceptos clave

--from claude
Origen .claude/skills/

--from codex
Origen .agents/skills/

Preserva archivos
scripts/refs/assets

Anota las conversiones
Marcador en la IR

🏗️ polyskill build

Compila definition.md para dist/<target>/<skill>/. Es el comando que ejecutas cada vez que editas la skill. Puede ir en un watch o en un hook pre-commit.

Resultado del build

$ polyskill build

✓ Parsed ./definition.md
✓ Built dist/claude/code-reviewer/SKILL.md
✓ Built dist/codex/code-reviewer/SKILL.md
✓ Built dist/codex/code-reviewer/agents/openai.yaml
✓ Copied scripts/, references/, assets/ to all targets
✓ Updated .polyskill-hashes

Build complete (3 files in 2 targets, 312ms).

Qué hace cada adapter en el emit

Adaptador de Claude

Adaptador de Codex

Restaura backtick-bang en las marcas de la IR

Convierte marcas dinámicas en prosa de respaldo

Emite allowed-tools en el frontmatter si la IR tiene

Ignora allowed-tools (no es compatible)

Sin sidecar

Emite agents/openai.yaml si IR tiene branding/mcp

Description literal

Carga inicial: activadores en los primeros 1-2KB

⚠️--force para ignorar drift

$ polyskill build
✗ Drift detected in dist/claude/x/SKILL.md (run reconcile or --force)

$ polyskill build --force
✓ Forced overwrite (drift discarded)

Usa --force solo cuando estés seguro de que puedes descartar el ajuste manual. Si no, usa reconcile.

Conceptos clave

dist/<target>/
Resultado por adapter

.polyskill-hashes
Detección de drift

--force
Sobrescribe la divergencia

Watch/pre-commit
Ejecuta de forma automática

📦 polyskill install

Combina build + copiar a los directorios canónicos: ~/.claude/skills/<skill> e ~/.agents/skills/<skill>. Skill disponible al instante en ambos runtimes.

En acción

$ polyskill install

✓ Built 2 targets (claude, codex)
✓ Claude Code     → ~/.claude/skills/code-reviewer
✓ OpenAI Codex    → ~/.agents/skills/code-reviewer

Reload notes:
  - Claude Code: hot-reload (já disponível, /code-reviewer)
  - Codex: open desktop app → Plugins → refresh
          (CLI: skill aparece no próximo $ + autocomplete)

Install complete.

⚡

Comando del día a día

¿Editaste? Ejecuta install. Skill actualizada en ambas. Es el comando más usado después de build.

🔄

Recarga

La recarga de Claude es automática. La de Codex CLI también. Codex desktop requiere una actualización manual.

🗑️

Desinstalar

No tiene comando. rm -rf ~/.claude/skills/x + rm -rf ~/.agents/skills/x.

Ámbito de instalación

Por defecto se instala en global (~/.claude/, ~/.agents/). Para instalarlo en el proyecto:

$ polyskill install --scope project
✓ Installed to ./.claude/skills/ and ./.agents/skills/

Conceptos clave

build + copy
Atajo 2 en 1

Valor predeterminado global
~/.claude y ~/.agents

--scope project
Busca en el repo

Recarga manual
Solo Codex de escritorio

🔍 polyskill detect / status / adapters

Tres comandos solo lectura para inspección. No editan nada. Sirven para depurar e introspeccionar el estado actual.

`polyskill detect`

Indica qué runtimes están instalados en la máquina y dónde están.

$ polyskill detect
✓ Claude Code     v1.4.2 (~/.claude/, npm)
✓ OpenAI Codex    v0.8.1 (~/.codex/, brew)
✗ Gemini CLI      not installed
✗ Cursor          not installed

`polyskill status`

Compara dist/ actual con los directorios instalados. Muestra lo que está en sync.

$ polyskill status
Workspace: ./code-reviewer

Targets:
  claude     ✓ in sync  (~/.claude/skills/code-reviewer)
  codex      ⚠ behind    (~/.agents/skills/code-reviewer, 2 commits old)

Run `polyskill install` to sync.

`polyskill adapters`

Lista los adapters instalados en polyskill. Hoy: portable + claude + codex.

$ polyskill adapters
✓ portable    canonical source format
✓ claude      Claude Code (.claude/skills/)
✓ codex       OpenAI Codex (.agents/skills/ + sidecar)

Roadmap (not yet):
  - gemini
  - cursor

💡Útil para troubleshooting

¿La skill no se activa? detect primero para ver si el runtime está visible. ¿Build extraño? status muestra qué está desincronizado. ¿Se rompió el adapter? adapters confirma que está cargado.

Conceptos clave

Solo lectura
No editan

--json
Parseable

Compatible con CI
Exit codes

Primera parada para depurar
Detectar siempre

🩺 polyskill validate / reconcile

Dos comandos de salud. validate ejecuta un linter por adapter (reglas por objetivo). reconcile resuelve las diferencias cuando alguien editó a mano fuera de polyskill.

polyskill validate — lint por target

$ polyskill validate

✓ portable     definition.md is valid
✓ claude       SKILL.md will be valid in Claude Code
✗ codex        SKILL.md has issues:
                - description is 8.4KB, will be truncated to ~8KB
                - triggers "review PR" found at offset 8200 → will be lost
                - move triggers to first 1-2KB (front-loading)

Validation FAILED for 1 target.

Cada adapter tiene sus propias reglas: Codex valida el tamaño de la descripción, Claude valida la sintaxis de allowed-tools, etc. validate se ejecuta en CI antes del merge.

polyskill reconcile — diferencias interactivas

$ polyskill reconcile

⚠ Drift detected in 1 target:
  ~/.claude/skills/code-reviewer/SKILL.md

Diff (target vs last-built):
  + Added section: "## Special case: monorepo"
  ~ Modified body of "## Output format"

Options:
  [k] keep target version (import back into definition.md)
  [o] overwrite target with current build
  [m] manual merge (open editor)
  [s] skip (leave drift for now)

Choice (k/o/m/s): k

✓ Imported target → definition.md updated
✓ Rebuilt all targets from new definition
✓ Drift resolved

Cuándo ejecutar validate

• Antes del commit (pre-commit hook)
• En CI antes del merge
• Después de importar una skill de otro runtime
• Cuándo editar description (verifica el truncamiento)

Cuándo ejecutar reconcile

• La compilación se aborta con un error de drift
• Sabes que alguien editó a mano
• La skill volvió a la source de otra máquina
• Periódicamente como verificación de cordura

💡Setup ideal

El hook pre-commit se ejecuta polyskill validate + polyskill build. CI también ejecuta ambos. Ejecutas Reconcile a mano cuando aparece drift. Este triángulo cubre el 95% de los casos.

Conceptos clave

Reglas por adapter
Lint específico

Exit code CI
0 = correcto, 1 = fallo

4 opciones de reconcile
keep/over/manual/skip

Triángulo CI
validate+build+reconcile

🎯Resumen del módulo

✓

Camino A para usar, Camino B para crear — npm link en B pone la CLI en el PATH.

✓

init crea un workspace portable — definition.md + directorios convencionales.

✓

import trae una skill existente en ambos sentidos — registra las conversiones en la IR.

✓

build genera los 2 targets + guarda el hash — --force para ignorar el drift.

✓

install = build + copiar a los directorios canónicos — global por defecto, --scope project si quieres.

✓

detect/status/adapters = inspección de solo lectura — primeros comandos para troubleshoot.

✓

validate en CI + reconcile para detectar divergencias — triángulo de salud de la skill.

Siguiente ruta:

T6 — Flujos avanzados (session handoff, dos terminales, MCP compartido, gobernanza)

← Anterior: 5.1 Ruta 6: Flujos →