← Back to Blog
Tutorial 7 min read

From Skill to Gene: A Migration Walkthrough

Turn your existing Cursor or Codex skills into Rotifer genes. A practical guide through scan, wrap, compile, and publish.

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:

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 <gene-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:

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

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

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:

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

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 → IR compiler → 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:

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

Each discovered skill can be individually wrapped and published.

Migrating from ClawHub

If your skill is already published on ClawHub, you can migrate it in one command — no manual download required:

rotifer wrap my-weather-gene --from-clawhub weather

This single command:

  1. Queries the ClawHub API for metadata (author, downloads, stars, version)
  2. Downloads the skill package automatically
  3. Parses the SKILL.md frontmatter and _meta.json
  4. Generates a complete phenotype.json with ClawHub provenance
  5. Copies all files (assets, scripts, source code) into the gene directory

The generated gene preserves full attribution — the original ClawHub author, download count, and slug are stored in phenotype.json under the clawhub field:

{
  "source": "clawhub",
  "clawhub": {
    "slug": "weather",
    "originalAuthor": "steipete",
    "downloads": 115157,
    "stars": 329
  }
}

After migration, run rotifer vg <gene> to get a V(g) security grade, then publish to get a full F(g) quality score — something ClawHub doesn't offer today.

Why migrate?

ClawHub has 38,000+ skills and 25M+ downloads. It's the largest AI skill marketplace. But it has no quality scoring system — install count is the only ranking signal. After ClawHavoc, trust signals matter more than ever.

By migrating to Rotifer, your skill gets:

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:

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