Learning path map
Detailed content
🏛️ The Agent Skills standard, the pain point, and the polyskill architecture
Before the CLI, the concept. Why polyskill exists and what it solves.
An open spec originating at Anthropic and adopted by 40+ tools. It defines the canonical skill format: a file SKILL.md, frontmatter with name e description, Markdown body, folder convention scripts/, references/, assets/.
It's the real common denominator. Everything you write within this spec works in any compatible runtime. Everything outside it ties you to a single runtime.
The 4 pillars (SKILL.md, name, description, body), folder convention, open commitment, agentskills.io as the authority.
You create a skill in Claude. You copy/adapt it for Codex. It works. A week later, you improve the Claude version. You forget to propagate the change. Then you improve the Codex version. You forget again. In a month, you have two DIFFERENT skills, and nobody knows which one is correct.
Without understanding the pain, polyskill seems like overkill. Anyone who has experienced skill drift (or worse, lost a version) understands the value immediately.
Organic drift, accidental fork, ambiguous source of truth, cognitive cost of “which version is the right one,” silent functionality breakage.
You write the skill ONCE in the canonical portable format (definition.md). The polyskill compiles to dist/claude/ e dist/codex/, each optimized for the target runtime. Like Babel/TypeScript for skills.
This is the "aha moment." Once it clicks that the skill is the source and both outputs are generated, everything else about polyskill makes sense.
Canonical source, build artifacts (dist/), selective compilation by target, runtime optimization (truncate description, rewrite injection).
(1) GO — Neutral Internal Representation, not tied to any runtime; (2) Adapters — 1 TypeScript file per runtime, able to read AND write its format; (3) CLI — orchestrates the adapters through the registry.
Adding a new runtime is literally one file: the adapter. Once you understand this, you know that Gemini, Cursor, and Copilot are “just” new adapters—not a polyskill rewrite.
Frontend/middle/backend compiler, plugin via registry, Adapter interface (parse, emit, validate), separation of concerns.
The Adapter “reads AND writes.” You can import an existing Claude skill (--from claude), make it portable, then emit for both. Same thing starting from Codex (--from codex).
You don’t have to start from scratch. Have a Claude skill you love? Import it, generate the portable version, then emit it. Have a Codex skill? Same process from the other side.
Required adapter bidirectionality, lossy vs. lossless, support for scripts/, references/, assets/ in every direction.
Every time it builds, polyskill calculates hashes of the generated files. On the next build, if any target file was edited by hand, the build aborts with an error. You decide: --force (overwrites) or polyskill reconcile (inspects drift).
Without this, you might manually adjust a Claude output for a specific case, build the next day, and lose the adjustment. Drift policy is your insurance policy.
File hash, detection of out-of-band modification, opt-in to overwrite (--force), interactive reconciliation, "no silent loss" principle.
Polyskill itself comes as an installable skill in both runtimes. You invoke it in natural language: /polyskill converte minha skill x pra funcionar nos dois (Claude) or $polyskill converte ... (Codex). The skill calls the CLI under the hood.
You never memorize flags. You ask in Brazilian Portuguese, and the skill translates it to polyskill import --from claude, polyskill build, etc.
Skill as a CLI wrapper, NL interface, Path A (drag & drop without CLI) vs. Path B (source + CLI), dogfooding.
⚡ The polyskill CLI in practice
From installation to reconcile. Each command explained and used in a real example.
A: copy skill/dist/claude/polyskill to ~/.claude/skills/ e skill/dist/codex/polyskill to ~/.agents/skills/. Works like a skill. B: clones repo, npm install && npm run build && npm link, you get the full CLI.
Path A only runs the skill — without the CLI, some commands break. Path B is complete. To build your own cross-runtime skills, B is required.
Prebuilt bundle vs. source, npm link, validation with polyskill --version e polyskill detect.
Command that creates a skill workspace with the portable structure: definition.md (frontmatter YAML + body), folders scripts/, references/, assets/, and build config.
A new skill starts here. You never create SKILL.md by hand — create definition.md once, and polyskill takes care of the rest.
Initial structure, definition.md vs. SKILL.md, minimal frontmatter, interactive body editing.
Point to an existing skill in any runtime and generate the equivalent portable workspace. It works both ways: --from claude gets from .claude/skills/, --from codex gets from .agents/skills/.
You have 10 Claude skills you love. Import each with one command, then run build and gets a Codex version of each. Free reverse engineering.
Import preserves scripts/references/assets, normalizes frontmatter, and converts dynamic injection to prose when it comes from Claude.
Generates dist/claude/<skill>/SKILL.md e dist/codex/<skill>/SKILL.md (+ sidecar agents/openai.yaml (when there's branding or MCP deps). It's the compilation step.
It's the command you run every time you edit definition.md. It can (and should) go in a watch or pre-commit hook.
Hash cache, flag --force to override drift, dist as a git-ignorable output (but the polyskill repo commits it for illustration).
Combines build + copy to the canonical directories: ~/.claude/skills/<skill> e ~/.agents/skills/<skill>. The skill instantly becomes available in both runtimes.
It's the command for a "local deploy." After editing, test by running install, run it in the Claude or Codex terminal without manually managing folders.
Automatic reload (Claude) vs. manual refresh (Codex), idempotency, scope (global vs. project), uninstall (direct rm from the folder).
detect shows which runtimes are on the machine; status shows which targets are in sync with the latest build; adapters lists the installed adapters (currently: portable, claude, codex).
For debugging. Skill not triggering? Run detect to check whether the runtime is visible. Weird build? status shows what’s out of sync.
Read-only commands, script-parseable, JSON output when --json, troubleshooting without editing anything.
validate runs a linter per adapter (rules by target: description length limits in Codex, injection syntax in Claude, etc.). reconcile compares dist/ with the installed directories and shows discrepancies, offering a guided merge.
Validate runs in CI before merge. Reconcile resolves the real-world situation where "someone edited it manually outside polyskill."
Rules per adapter, exit code 0 vs. 1 for CI, interactive drift report, decision to "keep override / overwrite / merge".