polyskill

Cross-runtime Agent Skills. Write your skill once in a portable format. Polyskill compiles it into Claude Code and OpenAI Codex variants, each optimized for the target runtime.

After install, you invoke polyskill with /polyskill in Claude Code or $polyskill in Codex. The skill drives the CLI behind the scenes, so you never have to memorize commands.

---

Table of contents

• Why it exists
• Install (two paths)
• Quick start
• How it works
• CLI reference
• Worked example
• Drift policy
• Roadmap
• Contributing
• Community
• License

---

Why it exists

The Agent Skills standard (agentskills.io) is now implemented by 40+ tools. The portable core that Claude Code and OpenAI Codex genuinely agree on is exactly four things.

1. The SKILL.md filename
2. The name and description frontmatter fields
3. The markdown body
4. The scripts/ / references/ / assets/ directory convention

Everything else is runtime-specific. Claude Code has dynamic injection (the backtick-bang syntax that runs a shell command before reading the skill). Codex has a hidden description-length cap and a separate agents/openai.yaml sidecar for UI metadata and MCP server dependencies. Both honor different field-name conventions in the frontmatter.

Polyskill is the seam. Write the portable core once. Get a runtime-optimized output for each target, two-way.

---

Install (two paths)

Path A. Drag and drop (no CLI required)

The repo ships pre-built dist/ outputs for the polyskill meta-skill itself. Copy them straight into your skills directories.

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

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

Claude Code live-reloads, so /polyskill works immediately. In Codex, open the desktop app, go to Plugins, click refresh.

⚠️ Path A installs the polyskill skill but not the polyskill CLI. The skill will respond to natural-language requests, but if it needs to actually run polyskill build or polyskill install behind the scenes, the CLI also needs to be on PATH. See Path B Step 1.

Path B. Source + CLI (for builders)