🎯What you get here
Learn every CLI command inside and out. Know which one to use for each situation (install, import an existing skill, build, validate, handle drift) and what to expect from the output.
Detailed content
📥 Installation — Path A vs Path B
Two ways to install, depending on what you need. A is faster but limited. B is comprehensive — necessary for building your own skills.
A. Drag & drop (no CLI)
# Claude Code cp -r skill/dist/claude/polyskill \ ~/.claude/skills/polyskill # OpenAI Codex cp -r skill/dist/codex/polyskill \ ~/.agents/skills/polyskill
The skill works for natural-language invocation. But if it needs to run polyskill build under the hood, it fails — CLI isn't on the PATH.
B. Source + CLI (complete)
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 on PATH. You can do everything: create skills, import, build, install, reconcile.
💡Which one to choose
If you only want to USE existing cross-runtime skills, A is enough. If you’re going to CREATE/PORT your own skills, B is required. When in doubt, choose B — there’s no downside.
Key concepts
Path A
CLI on PATH
Validates the install
Skills/dist/* in the repo
🚀 polyskill init <nome>
Create a portable skill workspace from scratch. Initial structure with definition.md stub, conventional folders, build config. You never create SKILL.md by hand.
In action
$ 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
initial definition.md
--- 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`
Key concepts
All set
Not SKILL.md
Local config
Edit only
📤 polyskill import <path> --from claude|codex
Takes an existing skill from any runtime and generates an equivalent portable workspace. Bidirectional: --from claude gets from .claude/skills/, --from codex gets from .agents/skills/.
In action — importing a skill from 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
✓ What import preserves
- • All files in
scripts/,references/,assets/ - • Frontmatter (name + description)
- • Complete markdown body
- • Relative links
⚠ What gets converted
- • Backtick-bang (Claude) → fallback prose + marker in the IR
- •
allowed-tools(Claude) → generic tool restriction IR - • Sidecar openai.yaml (Codex) → branding IR + mcp_deps
- • Long description → kept (front-loading only in the build for Codex)
💡Free reverse engineering
Have 10 Claude skills you love? Import each with one command, then polyskill build generates a Codex version of each. Round trip—it started as Claude-only, and now runs in both. Same thing if you started in Codex.
Key concepts
Source .claude/skills/
Source .agents/skills/
scripts/refs/assets
Marker in the IR
🏗️ polyskill build
Compile definition.md to dist/<target>/<skill>/. It’s the command you run every time you edit the skill. It can go in a watch or pre-commit hook.
Build output
$ 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).
What each adapter does during emit
allowed-tools in frontmatter if the IR hasallowed-tools (doesn't support)agents/openai.yaml if IR has branding/mcp⚠️--force to ignore drift
$ polyskill build ✗ Drift detected in dist/claude/x/SKILL.md (run reconcile or --force) $ polyskill build --force ✓ Forced overwrite (drift discarded)
Use --force only when you're sure the manual adjustment can be discarded. Otherwise, use reconcile.
Key concepts
Output per adapter
Drift detection
Overrides drift
Runs automatically
📦 polyskill install
Combine build + copy to the canonical directories: ~/.claude/skills/<skill> e ~/.agents/skills/<skill>. Skill available instantly in both runtimes.
In action
$ 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.
Everyday command
Edited it? Run install. Skill updated in both. It's the most-used command after build.
Reload
Claude reloads automatically. Codex CLI does too. Codex desktop needs a manual refresh.
Uninstall
There's no command. rm -rf ~/.claude/skills/x + rm -rf ~/.agents/skills/x.
Install scope
By default, it installs in global (~/.claude/, ~/.agents/). To install in the project:
$ polyskill install --scope project
✓ Installed to ./.claude/skills/ and ./.agents/skills/
Key concepts
2-in-1 shortcut
~/.claude and ~/.agents
Locates in the repo
Codex desktop only
🔍 polyskill detect / status / adapters
Three commands read-only for inspection. They don’t edit anything. They’re for debugging and inspecting the current state.
polyskill detect
Tells you which runtimes are installed on the machine and where they are.
$ 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
Compare dist/ current with the installed directories. Shows what’s in 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
Lists the adapters installed in polyskill. Today: 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
💡Useful for troubleshooting
Skill not triggering? detect first, to check whether the runtime is visible. Weird build? status shows what’s out of sync. Adapter broke? adapters confirm it’s loaded.
Key concepts
Don't edit
Parseable
Exit codes
Always detect
🩺 polyskill validate / reconcile
Two commands for health. validate runs a linter per adapter (rules by target). reconcile resolves drift when someone edited it by hand outside polyskill.
polyskill validate — lint by 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.
Each adapter has its own rules: Codex validates description size, Claude validates allowed-tools syntax, etc. validate runs in CI before merge.
polyskill reconcile — interactive drift
$ 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
When to run validate
- • Before commit (pre-commit hook)
- • In CI before merging
- • After importing a skill from another runtime
- • When editing description (checks for truncation)
When to run reconcile
- • Build aborts with a drift error
- • You know someone edited it by hand
- • Skill reverted to the source from another machine
- • Periodically as a sanity check
💡Ideal setup
Pre-commit hook runs polyskill validate + polyskill build. CI runs both too. You run reconcile manually when drift appears. This triangle covers 95% of cases.
Key concepts
Specific linting
0 = ok, 1 = failure
keep/over/manual/skip
validate+build+reconcile
🎯Module summary
Next track:
T6 — Advanced workflows (session handoff, two terminals, shared MCP, governance)