5.1 Agent Skills, pain points, and polyskill architecture

🎯What you get here

Complete mental model of polyskill — why it exists, what problem it addresses, and how it works internally. Without this, the CLI in the next lesson becomes "memorized commands." With it, the architecture is clear.

Detailed content

📐 The open Agent Skills spec (agentskills.io)

Standard originating at Anthropic and released as an open spec. Adopted by 40+ tools today. Defines the canonical skill format: SKILL.md + YAML frontmatter + Markdown body + folder conventions.

The 4 pillars — what ALL runtimes agree on

File Name: SKILL.md — don't invent variations

YAML frontmatter with at least name e description

Body in standard Markdown

Convention-based folders: scripts/, references/, assets/

💡Why this matters

Everything you write within these 4 pillars works in any compatible runtime. Everything OUTSIDE (allowed-tools, backtick-bang, openai.yaml, model override) ties you to a specific runtime—and that’s where the polyskill work comes in.

Key concepts

Open spec
agentskills.io

40+ runtimes
Broad adoption

4 pillars
Portable core

Extras = glue
Outside the 4 = runtime

😩 The pain — maintaining two divergent skills

Without understanding the pain, polyskill seems like overkill. This is the story EVERYONE who uses both runtimes goes through:

Day 1 — Create a skill in Claude

Works perfectly. You’re happy.

Day 2 — Copy/adapt it for Codex

Move it to .agents/skills/, remove the backtick-bang, adjust the description. It works in both. You’re still happy with it.

Week 2 — Improve Claude's (forget Codex's)

Find a new use case, add instructions to Claude. Forget to propagate them.

Week 3 — Improve Codex's (forget Claude's)

It was in Codex, spotted a bug, fixed it. Forgot to bring the change over to Claude.

Month 1 — TWO DIFFERENT skills

The versions diverged in 4 places. You don't remember which one is right. Every time you improve one, you throw away the improvement in the other. Ambiguous source of truth.

💀Invisible costs of drift

• Time wasted deciding "which version is the good one"
• Bugs come back (you fixed it in one version and forgot in the other)
• Feature works in one agent, but not the other
• Team gets confused (skill behaves differently)
• Documentation gets outdated on both sides

Key concepts

Organic drift
Inevitable without tooling

Accidental fork
Diverging versions

Ambiguous source
What's the best option?

Cognitive cost
Constant decision-making

💡 The core idea — one source, multiple targets

Polyskill solves the pain point by a compiler turns "portable code". 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.

Direct analogy — Babel/TypeScript

TypeScript:

source.ts → tsc → source.js (ES5) + source.js (ES2020)

Babel:

source.jsx → babel → source.js (target: ie11) + source.js (modern)

Polyskill:

definition.md → polyskill build → dist/claude/SKILL.md + dist/codex/SKILL.md

Same metaphor: canonical source, selective compilation by target, optimized output.

What the structure looks like

minha-skill/
├── definition.md          ← SOURCE canônica (você edita aqui)
├── scripts/
├── references/
├── assets/
└── dist/                  ← OUTPUTS (gerados pelo polyskill build)
    ├── claude/
    │   └── minha-skill/
    │       └── SKILL.md  ← versão Claude (com allowed-tools, backtick-bang...)
    └── codex/
        └── minha-skill/
            ├── SKILL.md  ← versão Codex (sem bang, description front-loaded)
            └── agents/
                └── openai.yaml  ← sidecar gerado automaticamente

🎯The "aha moment"

You never edit dist/. Edit only definition.md. Run polyskill build. O dist/ reflects. Runs polyskill install. Both runtimes get the latest version. A single source of truth.

Key concepts

Canonical source
definition.md

Compilation
polyskill build

generated dist/
Don't edit by hand

Optimization/target
By adapter

🧱 The 3 pieces — IR, adapters, CLI

Inside, polyskill has three parts. Once you understand that, you can see that adding Gemini/Cursor/Copilot is ONE file — the adapter. No rewrite.

🏛️

1. IR (Intermediate Representation)

A runtime-neutral version of everything a skill needs to be, with NO ties to a specific runtime. It’s the esperanto of polyskill.

🔌

2. Adapters

One TypeScript file per runtime. Each adapter implements parse() + emit() + validate(). Plug in → supported. Remove → gone.

⚡

3. CLI

What you run in the terminal. It orchestrates adapters via the registry. It doesn’t know runtime details — ask the adapter.

Visual architecture

┌──────────────────┐

│ definition.md │ ← YOU edit

└────────┬─────────┘

│

▼

┌──────────────────┐ ┌─ portable adapter ─┐

│ Parse (portable)│ ──▶│ parse() / emit() │

└────────┬─────────┘ └────────────────────┘

│

▼

┌──────────────────┐

│ IR (neutral) │ ← internal representation

└────────┬─────────┘

│ split by target

├──────────────┬──────────────┐

▼ ▼ ▼

┌──────────────┐ ┌──────────────┐ ┌──────────────┐

│claude adapter│ │codex adapter │ │gemini adapter│ ← 1 file each

│ emit() │ │ emit() │ │ emit() │

└──────┬───────┘ └──────┬───────┘ └──────┬───────┘

▼ ▼ ▼

dist/claude/ dist/codex/ dist/gemini/

The Adapter interface

interface Adapter {
  name: string;

  // Lê o formato do runtime e devolve IR
  parse(path: string): IR;

  // Pega IR e escreve no formato do runtime
  emit(ir: IR, outputDir: string): void;

  // Roda regras específicas do runtime (lint)
  validate(ir: IR): ValidationResult;
}

// Registrar é literalmente uma linha:
register(new CodexAdapter());

🚀Why this scales

When Gemini CLI gains traction, someone implements src/adapters/gemini.ts with parse/emit/validate, registers in the registry, opens a PR. Polyskill gains Gemini support without changing a single line of core. Same thing for Cursor, Copilot, whatever comes next.

Key concepts

Neutral GO
No runtime lock-in

parse+emit+validate
Adapter contract

Registry pattern
Dynamic plugin

Open core
Via PR adapter

🔁 Round-trip — Claude ↔ portable ↔ Codex

The Adapter “reads AND writes.” You can import an existing Claude skill (--from claude), make it portable, then emit for both. You don't have to start from scratch.

Round-trip workflows

# Case 1: started in Claude, wants portability

~/.claude/skills/x/ ──▶ claude.parse() ──▶ IR ──▶ portable.emit() ──▶ ./x/definition.md

# Case 2: started in Codex, wants portability

~/.agents/skills/x/ ──▶ codex.parse() ──▶ IR ──▶ portable.emit() ──▶ ./x/definition.md

# Case 3: has portable, wants it for both

./x/definition.md ──▶ portable.parse() ──▶ IR ──▶ claude.emit() + codex.emit()

Claude → portable import

$ polyskill import \
  ~/.claude/skills/x \
  --from claude

Reads SKILL.md + scripts + references. Generates definition.md while preserving everything.

Codex → portable import

$ polyskill import \
  ~/.agents/skills/x \
  --from codex

Reads SKILL.md + sidecar openai.yaml. Normalizes to portable.

Lossless when possible, lossy when needed

Round-trip preserves almost everything:

✓ scripts/, references/, assets/ pass through intact in both directions
✓ Portable frontmatter (name, description) is preserved
✓ Markdown body is preserved

Runtime-specific things become markers in the IR:

⚠️ Claude’s backtick-bang → IR marks it as "dynamic injection" → emitted to Codex as prose
⚠️ Codex’s openai.yaml sidecar → IR marks it as "mcp deps" + "branding" → emitted to Claude as allowed-tools

Key concepts

Bidirectional
Reads AND writes

--from claude/codex
Origin flag

Lossless dirs
scripts/refs/assets

Lossy semantic
Bang → prose

🛡️ Drift policy — protection against overwriting

Every time it builds, polyskill calculates the hash of the output files. On the next build, if any destination file was edited manually outside polyskill, the build ABORTS with an error. You decide.

The drift workflow

polyskill build → generates dist/claude/x/SKILL.md, stores the hash in .polyskill-hashes

You edit them by hand ~/.claude/skills/x/SKILL.md (specific adjustment)

Days later: polyskill build again

Polyskill compares hash: drift detected. Aborts with a clear message.

You choose: --force (overwrites, loses customization) OR polyskill reconcile (inspects, decides).

✓ Why this is safe

• Never silently overwrites your work
• Drift is SEEN, not hidden
• You always have the option to force OR reconcile
• Production edits can be detected in the next build

✗ Without a drift policy, it would be…

• A manual adjustment would disappear in the next build
• You'd never know (no error)
• Trust in the tool would drop
• You'd go back to manual maintenance anyway

Output example

$ polyskill build
✗ Drift detected!

The following targets have been modified outside polyskill:
  - ~/.claude/skills/x/SKILL.md (last hash: a3f9...; current: 8d2b...)

Options:
  - Run `polyskill build --force` to overwrite (loses local edits)
  - Run `polyskill reconcile` to inspect and merge

Build aborted.

Key concepts

Hash file
.polyskill-hashes

No silent loss
Abort first

--force
Opt-in override

reconcile
Interactive merge

🦜 The meta-skill — polyskill as a skill

Poetic detail: polyskill if it distributes using itself. Comes as an installable skill in both runtimes. You invoke it in natural language; the skill calls the CLI under the hood, translating your request into commands.

🔷 Claude Code

/polyskill converts my skill
y-compare to work in both
runtimes

Skill receives NL, translates to:

$ polyskill import \
    ~/.claude/skills/y-compare \
    --from claude
$ polyskill build

🟣 Codex

$polyskill converte minha skill
y-compare pra funcionar nos dois
runtimes

Same skill, same translation:

$ polyskill import \
    ~/.agents/skills/y-compare \
    --from codex
$ polyskill build

Installation paths — A vs. B

Path A — drag & drop

Copy skill/dist/claude/polyskill to ~/.claude/skills/ e skill/dist/codex/polyskill to ~/.agents/skills/. Without CLI. Only the meta-skill works; the commands it needs to run break.

Path B — source + CLI

Clone the repo, npm install && npm run build && npm link. Full CLI on the PATH. To build your own skills, B is required.

💡Full dogfooding

Polyskill solves the "cross-runtime skills" problem by using a cross-runtime skill that it generates itself. If the meta-skill works in both runtimes, polyskill proves it works. If it breaks in one, that proves the opposite. Architectural honesty.

Key concepts

Meta-skill
Polyskill as a skill

NL interface
No need to memorize flags

Path A vs. B
Without CLI / with

Dogfooding
Use the tool itself

🎯Module summary

✓

Agent Skills is an open spec with 4 portable pillars — SKILL.md, name+description, markdown body, convention-based dirs.

✓

Drift without tooling is inevitable — one week is enough for them to diverge.

✓

Canonical source → compiled targets — direct analogy with Babel/TypeScript.

✓

3 pieces: IR + Adapters + CLI — adding a runtime takes ONE file.

✓

Bidirectional round-trip — starts with Claude or Codex, then supports both.

✓

Drift policy = hash + reconcile — never silently overwrites.

✓

Meta-skill dogfoods polyskill — uses its own format to distribute itself.

Next module:

5.2 — polyskill CLI in practice (init, import, build, install, validate, reconcile)

← Back to Track 5 Next: 5.2 →