DEV Community

Rotifer Protocol
Rotifer Protocol

Posted on • Originally published at rotifer.dev

From Skill to Gene: A Migration Walkthrough

#ai #tutorial #webassembly #devtools

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
Enter fullscreen mode Exit fullscreen mode

Step 1: Scan for Skills

First, let Rotifer discover what skills you already have:

rotifer scan --skills --skills-path .cursor/skills
Enter fullscreen mode Exit fullscreen mode

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.
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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

File Purpose
phenotype.json Declares the gene's domain, input/output schema, and fidelity level (wrapped)
SKILL.md A copy of your original skill file, now bundled as gene documentation
.gene-manifest.json Internal metadata — gene ID, version, creation timestamp, source path

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
Enter fullscreen mode Exit fullscreen mode

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.
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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:

Attribute Wrapped Gene Native Gene
Source Imported from SKILL.md Written with express() function
Contains WASM No — metadata only Yes — executable IR
Runs in sandbox No Yes
Base fitness 0.45 0.70
Arena eligible Limited brackets All brackets
Portable across bindings Metadata only Full execution portability

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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:

Environment Default Path Notes
Cursor .cursor/skills/ Project-level skills
Codex ~/.codex/skills/ Global skills
Custom Any directory Pass --skills-path <dir> to rotifer scan

You can scan multiple paths in sequence:

rotifer scan --skills --skills-path .cursor/skills
rotifer scan --skills --skills-path ~/.codex/skills
Enter fullscreen mode Exit fullscreen mode

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.

Top comments (0)