rotifer-guide

Rotifer Guide — User Entry Point

This Skill handles intent recognition and workflow routing. Deep technical details are delegated to specialized Skills.

Prerequisites

Before using this Skill, ensure the Rotifer CLI is available:

npx @rotifer/playground --version

If you prefer MCP integration instead of CLI, add this to your MCP config:

{
  "mcpServers": {
    "rotifer": {
      "command": "npx",
      "args": ["@rotifer/mcp-server"]
    }
  }
}

No version pinning needed — both packages resolve to the latest release automatically.

---

Intent Router

Every row assumes the user is already asking about Rotifer. The signals below route within this Skill; they are not reasons to invoke it. A user asking "how do I get started" or "why is my score 0" without Rotifer in view is asking someone else.

When the request is about Rotifer but the sub-capability is unclear, list all five and let the user choose. When the request is not about Rotifer, say so and stop — do not map it onto the nearest row.

Related Skills

---

What this Skill does on your machine

It has no code of its own — it tells your assistant which rotifer commands to run. That is why its manifest declares process execution, filesystem read/write and outbound network access: every one of those is the CLI acting, not this Skill.

Commands that install, publish or overwrite are proposed for your approval first, never run silently.

---

1. onboarding — Interactive Walkthrough

Phase 1: Environment Check

npx @rotifer/playground --version
rotifer doctor
rotifer list

If the CLI is missing: npm i -g @rotifer/playground, which installs the rotifer binary.

rotifer doctor checks the TypeScript→WASM toolchain (esbuild / javy). Run it first: without that toolchain rotifer compile fails at the WASM step, and the error looks like a code problem rather than a missing tool. It exits non-zero and prints the install line when something is absent.

Phase 2: Core Concepts

Phase 3: Hands-on Experience

Two paths — pick by what the user wants first, a result or an understanding.

Fastest result — rotifer hello:

rotifer hello

An interactive builder: pick one of six templates (quality-advisor, uiux-diagnosis, content-analysis, code-security, doc-qa, web3-toolkit), and it selects Genes, composes them, creates the Agent and runs it. Use this when the user wants to see Rotifer work before learning what a Gene is. rotifer hello --list-templates shows what is on offer; --template , --input , --file and --dir skip the prompts.

Full lifecycle — one command per concept:

rotifer init hello-world --domain content.greeting --fidelity Wrapped
rotifer test hello-world
rotifer compile hello-world
rotifer arena submit hello-world
rotifer arena list --domain content.greeting

After each step, explain the output and confirm the user understands before proceeding.

Phase 4: Next Steps

Recommend based on user background:

• Has an existing SKILL.md → scaffold (rotifer wrap)
• Wants to browse the ecosystem → explorer
• Wants to dive deeper → route to gene skill (modules/dev.md)

---

2. scaffold — Natural-Language Scaffolding

This sub-capability is backend-backed. When network is available, scaffold uses the /api/playground/* endpoints on rotifer.ai for LLM-assisted Gene generation, V(g) scanning, and one-click Cloud publish. The CLI path remains as fallback.

Phase 1: Intent Extraction

Extract from the user's natural-language description:

Phase 2: Confirm Parameters

Present inferred results to the user, wait for confirmation before executing.

Phase 3: Scaffold Generation

Path A — Web Studio (backend-backed, preferred when online):

Use the rotifer.ai Playground API for LLM-assisted generation:

1. POST /api/playground/generate  { prompt, domain }  → { source, phenotype }
2. POST /api/playground/scan      { source }           → { grade, findings }
3. POST /api/playground/publish   { source, phenotype } → { published, grade }

The Web Studio UI at https://rotifer.ai/studio/ provides a visual 3-step flow (Describe → Create → Publish) that calls these same endpoints.

This path sends the user's text to rotifer.ai. generate transmits the description they wrote; scan transmits the generated source; publish transmits source and phenotype and makes the Gene public. Say so before using it, and offer Path B when the description contains anything the user would not post publicly — Path B is entirely local and produces the same scaffold without a network call.

Path B — CLI (local, always available):

rotifer init  --domain  --fidelity 

From an existing SKILL.md:

rotifer scan --skills
rotifer wrap  --from-skill 

From ClawHub:

rotifer wrap  --from-clawhub 

Phase 4: Verification

rotifer test 
rotifer compile 

After compilation passes, prompt: publish to Cloud (rotifer publish) or submit to Arena (rotifer arena submit).

rotifer publish defaults to uploading to the Rotifer Cloud Registry. Disable with rotifer config set default-publish false or ROTIFER_AUTO_PUBLISH=false.

Offline Fallback

If the Playground API is unreachable, display:

Network unavailable. Use rotifer init for local-only Gene creation.

Then follow Path B (CLI).

For deeper development details (inputSchema design, express function implementation) → route to gene skill (modules/dev.md).

---

3. doctor — Diagnostics & Repair

Decision Tree

User reports a problem
 |
 +-- F(g) = 0 or abnormally low score
 |   +-- Does rotifer test  pass?
 |   |   +-- Fails → Check if express() return value matches outputSchema
 |   |   +-- Passes → Check if phenotype.json domain is reasonable
 |   +-- Are there competitors in the same domain?
 |       +-- Yes → Analyze competitor strengths, suggest optimizations
 |
 +-- Publish failed
 |   +-- Does rotifer compile  succeed?
 |   |   +-- Fails → rotifer doctor first, then syntax errors / missing dependencies
 |   |   +-- Succeeds → rotifer whoami — signed in at all, and as whom?
 |   |                  Then check network connectivity
 |   +-- Is phenotype.json format valid?
 |
 +-- Compilation failed
 |   +-- FIRST: rotifer doctor — is the TS→WASM toolchain even installed?
 |   |   +-- Reports esbuild / javy missing → install those; the code is not the problem
 |   +-- Check the exported express function signature in index.ts
 |   +-- Check inputSchema / outputSchema in phenotype.json
 |   +-- Check if fidelity declaration matches actual code
 |       +-- Declared Native but has fetch calls → Change to Hybrid or remove network calls
 |
 +-- Runtime error
     +-- rotifer test  --verbose
     +-- Check if input conforms to inputSchema
     +-- Check if express() handles edge cases correctly

Common Diagnostic Commands

rotifer doctor                       # TS→WASM toolchain — run this before blaming the code
rotifer test 
rotifer vg                     # V(g) security scan — grade A–D, or ? for a code-free Skill
rotifer list
rotifer arena list --domain 
rotifer arena watch          # live ranking movement (Ctrl+C to stop)

rotifer doctor takes no arguments and checks one thing: whether esbuild and javy are present and reachable on PATH. A missing toolchain surfaces as a compile failure that reads like a code error, so it is the cheapest first move on any "compilation failed" report.

Quick Reference

---

4. explorer — Ecosystem Search

Phase 1: Understand the Need

Extract from user description: functionality keywords, target domain, fidelity preference.

Phase 2: Search

rotifer search is the ecosystem search — it queries the Cloud registry, which is where Genes published by other people live. arena list ranks what is already in the Arena and list shows what is on this machine; all three answer different questions, so pick by what the user asked for.

rotifer search                         # the ecosystem — Cloud registry
rotifer search  --domain  --fidelity Native --sort downloads
rotifer arena list --domain           # ranked competitors in one domain
rotifer list                                  # what is already installed here

Follow up on a specific result:

rotifer info                # full details, local or Cloud
rotifer reputation          # R(g) — the reputation column below
rotifer stats               # downloads: 7d / 30d / 90d / all time
rotifer versions @owner/        # version history chain
rotifer compare         # 2–5 published Genes, side by side

rotifer reputation @username scores a creator instead of a Gene, and --leaderboard ranks creators.

Phase 3: Result Analysis

Display search results in a table:

Phase 4: Recommendation

• Found a matching Gene → suggest install: rotifer install
• Found a partial match → suggest fork and modify, or submit an Arena challenge (route to rotifer-arena/SKILL.md)
• Nothing found → suggest creating a new Gene (route to scaffold)

---

5. upgrade — Fidelity Evolution

Phase 1: Assess Current State

rotifer list

Check the target Gene's phenotype.json — confirm current fidelity and express() implementation.

Phase 2: Migration Path Decision

Phase 3: Execute Migration

After confirming the migration plan, route to gene skill (modules/migration.md) for the full migration workflow.

Phase 4: Verification

rotifer test 
rotifer vg 
rotifer compile 
rotifer arena submit 
rotifer arena watch 

A fidelity upgrade rewrites the Gene's code, so the V(g) security grade it earned before the rewrite no longer describes it — rotifer vg re-scans and returns A–D (or ? when there is no src/). Compare F(g) before and after to confirm ranking continuity; arena watch shows the move happening rather than requiring a second arena list.