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 --yes @rotifer/playground@0.26.0 --version

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

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

Both commands name an exact version on purpose. An unversioned npx resolves to whatever the registry serves at that moment, so the code you run would not be the code that was reviewed. The @rotifer/mcp-server pin is the one this repository agrees on everywhere; move it in one deliberate step, not per file. Stronger than pinning the npx call: install the CLI into the project and run the local binary.

npm install --save-dev --save-exact @rotifer/playground@0.26.0
npm exec -- rotifer --version

Commit the lockfile and use npm ci in automation. Before moving a pin to a newer release, review what changed and record what you are accepting: npm view @rotifer/playground@<version> dist.integrity.

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 --yes @rotifer/playground@0.26.0 --version
rotifer doctor
rotifer list

If the CLI is missing: npm i -g @rotifer/playground@0.26.0, which installs the rotifer binary at that exact version.

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 <id>, --input <json>, --file <path> and --dir <path> 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 rotifer-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 <name> --domain <domain> --fidelity <fidelity>

From an existing SKILL.md:

rotifer scan --skills
rotifer wrap <name> --from-skill <path>

From ClawHub:

rotifer wrap <name> --from-clawhub <slug>

Phase 4: Verification

rotifer test <name>
rotifer compile <name>

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 rotifer-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 <name> 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 <name> 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 <name> --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 <name>
rotifer vg <path>                    # V(g) security scan — grade A–D, or ? for a code-free Skill
rotifer list
rotifer arena list --domain <domain>
rotifer arena watch <domain>         # 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 <query>                        # the ecosystem — Cloud registry
rotifer search <query> --domain <domain> --fidelity Native --sort downloads
rotifer arena list --domain <domain>          # ranked competitors in one domain
rotifer list                                  # what is already installed here

Follow up on a specific result:

rotifer info <gene-ref>               # full details, local or Cloud
rotifer reputation <gene-ref>         # R(g) — the reputation column below
rotifer stats <gene-ref>              # downloads: 7d / 30d / 90d / all time
rotifer versions @owner/<name>        # version history chain
rotifer compare <ref-a> <ref-b>       # 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 <name>
• 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 rotifer-gene skill (modules/migration.md) for the full migration workflow.

Phase 4: Verification

rotifer test <name>
rotifer vg <path-to-gene>
rotifer compile <name>
rotifer arena submit <name>
rotifer arena watch <domain>

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.