5.2 CLI polyskill na prática

🎯O que você ganha aqui

Conhecer cada comando do CLI por dentro. Sair sabendo qual usar pra cada situação (instalar, importar skill existente, builddar, validar, lidar com drift) e o que esperar do output.

Conteúdo detalhado

📥 Instalação — Caminho A vs Caminho B

Duas formas de instalar, dependendo do que você precisa. A é mais rápido mas limitado. B é completo — necessário pra construir suas próprias skills.

A. Drag & drop (sem CLI)

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

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

Skill funciona pra invocação NL. Mas se ela precisar rodar polyskill build por baixo, falha — CLI não está no PATH.

B. Source + CLI (completo)

git clone \
  
cd pollyskill
npm install
npm run build
npm link

# Confirma
polyskill --version
polyskill detect

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

CLI no PATH. Você consegue tudo: criar skills, importar, buildar, instalar, reconcile.

💡Qual escolher

Se você só quer USAR skills cross-runtime já existentes, A basta. Se vai CRIAR/PORTAR skills suas, B é obrigatório. Na dúvida, B — não tem downside.

Conceitos-chave

Bundle pré-built
Caminho A

npm link
CLI no PATH

polyskill detect
Valida install

Dist commitado
Skills/dist/* no repo

🚀 polyskill init <nome>

Cria um workspace de skill portable do zero. Estrutura inicial com definition.md stub, pastas convencionadas, config de build. Você nunca cria SKILL.md à mão.

Em ação

$ 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`

Conceitos-chave

Estrutura inicial
Tudo pronto

definition.md
Não SKILL.md

.polyskill.json
Config local

Stub pronto
Só editar

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

Pega skill existente em qualquer runtime, gera workspace portable equivalente. Bidirecional: --from claude pega de .claude/skills/, --from codex pega de .agents/skills/.

Em ação — importando uma skill do 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

✓ O que importação preserva

• Todos os arquivos em scripts/, references/, assets/
• Frontmatter (name + description)
• Body markdown completo
• Links relativos

⚠ O que se converte

• Backtick-bang (Claude) → prosa de fallback + marcador na IR
• allowed-tools (Claude) → IR genérico de tool restriction
• Sidecar openai.yaml (Codex) → IR de branding + mcp_deps
• Description longa → mantida (front-loading só no build pro Codex)

💡Reverse engineering grátis

Você tem 10 skills do Claude que adora? Importa cada uma com um comando, daí polyskill build gera versão Codex de cada. Round-trip — começou Claude-only, agora roda nos dois. Mesma coisa se você começou no Codex.

Conceitos-chave

--from claude
Origem .claude/skills/

--from codex
Origem .agents/skills/

Preserva arquivos
scripts/refs/assets

Anota conversões
Marcador na IR

🏗️ polyskill build

Compila definition.md pra dist/<target>/<skill>/. É o comando que você roda toda vez que edita a skill. Pode ir num watch ou pre-commit hook.

Output do 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).

O que cada adapter faz no emit

Claude adapter

Codex adapter

Restaura backtick-bang nas marcações da IR

Converte marcações dinâmicas em prosa de fallback

Emite allowed-tools no frontmatter se IR tem

Ignora allowed-tools (não suporta)

Sem sidecar

Emite agents/openai.yaml se IR tem branding/mcp

Description literal

Front-loading: triggers nos primeiros 1-2KB

⚠️--force pra ignorar drift

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

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

Use --force só quando tem certeza que o ajuste à mão pode ir embora. Senão, use reconcile.

Conceitos-chave

dist/<target>/
Output por adapter

.polyskill-hashes
Drift detection

--force
Sobrescreve drift

Watch/pre-commit
Roda automatic

📦 polyskill install

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

Em ação

$ 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 do dia a dia

Editou? Roda install. Skill atualizada nos dois. É o comando mais usado depois de build.

🔄

Reload

Claude reload é automático. Codex CLI também. Codex desktop precisa refresh manual.

🗑️

Uninstall

Não tem comando. rm -rf ~/.claude/skills/x + rm -rf ~/.agents/skills/x.

Escopo de install

Por padrão instala no global (~/.claude/, ~/.agents/). Pra instalar no projeto:

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

Conceitos-chave

build + copy
Atalho 2-em-1

Global default
~/.claude e ~/.agents

--scope project
Localiza no repo

Reload manual
Só Codex desktop

🔍 polyskill detect / status / adapters

Três comandos read-only de inspeção. Não editam nada. Servem pra debug e introspecção do estado atual.

`polyskill detect`

Diz quais runtimes estão instalados na máquina e onde estão.

$ 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/ atual com os diretórios instalados. Mostra o que está em 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 os adapters instalados no polyskill. Hoje: 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 em troubleshoot

Skill não dispara? detect primeiro pra ver se o runtime está visível. Build estranho? status mostra o que está dessincronizado. Adapter quebrou? adapters confirma que está carregado.

Conceitos-chave

Read-only
Não editam

--json
Parseable

CI-friendly
Exit codes

Debug first stop
Sempre detect

🩺 polyskill validate / reconcile

Dois comandos de saúde. validate roda linter por adapter (regras por alvo). reconcile resolve drift quando alguém editou à mão fora do 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 tem regras suas: Codex valida description size, Claude valida sintaxe de allowed-tools, etc. validate roda em CI antes de merge.

polyskill reconcile — drift interativo

$ 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

Quando rodar validate

• Antes de commit (pre-commit hook)
• Em CI antes de merge
• Depois de importar skill de outro runtime
• Quando editar description (checa truncamento)

Quando rodar reconcile

• Build aborta com erro de drift
• Você sabe que alguém editou à mão
• Skill voltou pra source de outra máquina
• Periodicamente como sanity check

💡Setup ideal

Pre-commit hook roda polyskill validate + polyskill build. CI roda os dois também. Reconcile você corre à mão quando drift aparece. Esse triângulo cobre 95% dos casos.

Conceitos-chave

Regras por adapter
Lint específico

Exit code CI
0 = ok, 1 = falha

4 opções reconcile
keep/over/manual/skip

Triângulo CI
validate+build+reconcile

🎯Resumo do módulo

✓

Caminho A pra usar, Caminho B pra criar — npm link no B coloca CLI no PATH.

✓

init cria workspace portable — definition.md + dirs convencionados.

✓

import puxa skill existente nos dois sentidos — anota conversões na IR.

✓

build emite pros 2 targets + grava hash — --force pra ignorar drift.

✓

install = build + copy pros dirs canônicos — global por padrão, --scope project se quiser.

✓

detect/status/adapters = inspeção read-only — primeiros comandos pra troubleshoot.

✓

validate em CI + reconcile pra drift — triângulo de saúde da skill.

Próxima trilha:

T6 — Fluxos avançados (session handoff, dois terminais, MCP compartilhado, governança)

← Anterior: 5.1 Trilha 6: Fluxos →