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

When intent is unclear, list all five sub-capabilities and let the user choose.

Related Skills

1. onboarding — Interactive Walkthrough

Phase 1: Environment Check

cd rotifer-playground
node dist/index.js --version
node dist/index.js list

If not installed, guide: git clone → npm install → npm run build.

Phase 2: Core Concepts

Phase 3: Hands-on Experience

Walk the user through a Gene's complete lifecycle:

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-dev/SKILL.md

2. scaffold — Natural-Language Scaffolding

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

From scratch:

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).

For deeper development details (inputSchema design, express function implementation) → route to gene-dev/SKILL.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 → Check for syntax errors, missing dependencies
 |   |   +-- Succeeds → Check network connection, Cloud credentials
 |   +-- Is phenotype.json format valid?
 |
 +-- Compilation failed
 |   +-- 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 test <name>
rotifer list
rotifer arena list --domain <domain>

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 arena list
rotifer arena list --domain <domain>
rotifer list

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-migration/SKILL.md for the full migration workflow.

Phase 4: Verification

rotifer test <name>
rotifer compile <name>
rotifer arena submit <name>

Compare F(g) scores before and after migration to confirm ranking continuity.