From Skill to Gene: A Migration Walkthrough

You already have AI skills. Maybe a debugging workflow in .cursor/skills/debugger/SKILL.md, a code review checklist under ~/.codex/skills/, or a custom prompt-engineering skill you’ve refined over months. They work — but they’re static files. They can’t compete with alternatives, can’t be versioned on a registry, and can’t be shared with other agents in a structured way.

Rotifer’s Skill Import pipeline turns those files into genes — modular units that carry metadata, participate in fitness evaluation, and live in a cloud registry anyone can query. The migration takes about five minutes per skill, and you don’t have to rewrite a single line.

Let’s walk through it.

Prerequisites

Before you start, make sure you have:

• Node.js >= 20 — check with node -v
• Rotifer CLI — install globally: npm install -g @rotifer/playground
• At least one SKILL.md file — in any of the standard skill directories

Verify the CLI is available:

rotifer --version
# => @rotifer/playground v0.5.x

Step 1: Scan for Skills

First, let Rotifer discover what skills you already have:

rotifer scan --skills --skills-path .cursor/skills

Example output:

🔍 Scanning .cursor/skills/ for SKILL.md files...

  Found 4 skills:

  ┌──────────────────────┬────────────────────────────────────────────┬──────────┐
  │ Skill Name           │ Path                                       │ Size     │
  ├──────────────────────┼────────────────────────────────────────────┼──────────┤
  │ debugger             │ .cursor/skills/debugger/SKILL.md           │ 3.2 KB   │
  │ testing-strategist   │ .cursor/skills/testing-strategist/SKILL.md │ 4.1 KB   │
  │ prompt-engineer      │ .cursor/skills/prompt-engineer/SKILL.md    │ 2.8 KB   │
  │ security-auditor     │ .cursor/skills/security-auditor/SKILL.md   │ 5.0 KB   │
  └──────────────────────┴────────────────────────────────────────────┴──────────┘

  Run `rotifer wrap <name> --from-skill <path>` to wrap any skill as a gene.

The scanner reads every SKILL.md it finds, extracts the skill name from the directory structure, and reports what’s available. No files are modified — this is read-only reconnaissance.

Step 2: Wrap a Skill

Pick a skill and wrap it into a gene. Let’s use the debugger as an example:

rotifer wrap debugger-skill \
  --from-skill .cursor/skills/debugger/SKILL.md \
  --domain debugging

This generates a gene directory under genes/debugger-skill/ with three files:

The --domain flag categorizes the gene (e.g. debugging, testing, code-review, search). This determines which Arena bracket the gene competes in and helps agents discover it by capability.

Your original SKILL.md is never modified. The wrap command only reads it and creates a new gene directory alongside your existing genes.

Step 3: Compile (Validate)

Next, validate that the gene’s structure is well-formed:

rotifer compile debugger-skill

For Wrapped genes (which don’t contain executable WASM), the compile step validates:

• phenotype.json schema is correct and complete
• Required fields (domain, fidelity, version) are present
• The referenced SKILL.md exists and is non-empty
• .gene-manifest.json is internally consistent

Expected output:

📦 Compiling debugger-skill...
   Fidelity: wrapped (metadata-only, no WASM)
   Phenotype: ✓ valid
   Manifest:  ✓ consistent
   Docs:      ✓ SKILL.md present (3.2 KB)

   ✅ debugger-skill is ready to publish.

If anything is missing or malformed, the compiler will tell you exactly what to fix before you can proceed.

Step 4: Publish

Authenticate with the Rotifer Cloud Registry, then publish:

rotifer login
rotifer publish debugger-skill

rotifer login opens an interactive auth flow (or reads credentials from ~/.rotifer/auth.json if you’ve logged in before). Once authenticated, publish uploads your gene to the cloud registry where it becomes discoverable by any agent using the MCP Server or the web registry at rotifer.ai.

🚀 Publishing debugger-skill v0.1.0...
   Registry: cloud.rotifer.dev
   Fidelity: wrapped
   Domain:   debugging

   ✅ Published! View at: https://rotifer.ai/genes/debugger-skill

Your skill is now a gene. Other agents can find it, compare it against alternatives, and adopt it — all through standard Rotifer tooling.

Wrapped vs Native

Not all genes are equal. The fidelity level determines what a gene can do:

Wrapped genes are a legitimate starting point. They participate in the registry, carry reputation, and can be discovered by agents. But they can’t execute inside the Rotifer runtime — an agent that adopts a Wrapped gene uses its documentation as a prompt, not as runnable code.

Native genes, on the other hand, compile to WASM and run inside a sandboxed environment with measurable performance. Their higher base fitness reflects this additional capability.

Upgrading to Native

When you’re ready to give your gene executable behavior, provide a WASM binary:

rotifer compile debugger-skill --wasm debugger.wasm

Or write a TypeScript express() function in genes/debugger-skill/index.ts and let the compiler handle the TS → WASM pipeline automatically:

rotifer compile debugger-skill
# Detects index.ts → esbuild → Javy → WASM → Rotifer IR

The gene’s fidelity upgrades from wrapped to native, its base fitness rises, and it becomes eligible for full Arena competition. Your existing phenotype and metadata carry over — no need to re-publish from scratch.

Default Skill Paths

Rotifer’s scanner knows where to look for skills across popular AI development tools:

You can scan multiple paths in sequence:

rotifer scan --skills --skills-path .cursor/skills
rotifer scan --skills --skills-path ~/.codex/skills

Each discovered skill can be individually wrapped and published.

What’s Next

You’ve scanned, wrapped, compiled, and published. Your skills are now genes — discoverable, comparable, and ready to evolve. From here you can:

• Submit to the Arena — rotifer arena submit debugger-skill to compete against other debugging genes
• Track fitness — watch how your gene ranks as agents adopt and evaluate it
• Upgrade to Native — add executable logic for higher fitness and full portability
• Compose into Genomes — combine multiple genes into a coordinated workflow

Deep Dive: See the full Skill Import Guide for all options and advanced workflows.