Rotifer Agent

End-to-end guide for building AI Agents from Genes: intent decomposition, Gene selection, Genome composition, Agent creation, and testing. Use when the user...

Security Scan

An instruction-only skill that coherently documents how to design and create Rotifer Agents; it does not request credentials or install software itself, though it assumes using npx to run Rotifer tooling at runtime.

Purpose & Capability

The skill's name and description (compose Genes into Agents) match the instructions: all steps reference the Rotifer CLI, Arena, local .rotifer agent files, and gene selection. Required capabilities are proportional and relevant.

Instruction Scope

SKILL.md confines actions to documenting decomposition, rotifer CLI commands (rotifer agent create/run, rotifer arena list), inspecting local agent JSON and phenotype.json, and routing to related skills. It does not instruct reading arbitrary system files, exfiltrating data, or contacting unknown endpoints.

Install Mechanism

There is no install spec (instruction-only), which is low risk. However the document prescribes using npx (e.g., npx @rotifer/playground, npx @rotifer/mcp-server). Those npx invocations will fetch and execute packages from npm when run by the user — this is common but worth noting because it executes external code at runtime outside the skill bundle.

Credentials

The skill declares no required environment variables, credentials, or config paths. The instructions do not request secrets or unrelated credentials.

Persistence & Privilege

The skill is not always-enabled and does not request persistent system privileges, nor does it modify other skills or global agent configuration in its instructions.

Assessment

This is an authoritative guide for using the Rotifer CLI to design and run agents and appears internally consistent. Before following commands: (1) be aware that running the suggested npx commands will download and execute code from the npm registry — verify package names, versions, and the upstream rotifer.dev / repository to ensure you trust them; (2) the workflow expects you to inspect and edit local .rotifer JSON files — review those edits carefully before running agents; (3) the guide may route you to other skills (e.g., gene-dev) — confirm those skills' trustworthiness if they are invoked; (4) no credentials are required by this skill itself, but avoid pasting secrets into agent configs you create unless necessary and understood.

Rotifer Agent — From Genes to Agents

Decompose user intent into capability units, select Genes from the ecosystem, compose a Genome, create and validate an Agent.

Prerequisites

This Skill requires the Rotifer CLI:

npx @rotifer/playground --version

Or use the MCP Server for IDE integration:

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

---

Hierarchy: Gene (atomic logic) → Genome (composition) → Agent (runnable entity)

---

Phase 1: Intent Decomposition

Break the user's goal into independent capability units (each maps to a Gene).

Steps:

1. Confirm the Agent's input and expected output with the user
2. Decompose the task into 2–6 capability units, each satisfying the Gene three axioms (functional cohesion, self-sufficient interface, independently evaluable)
3. Label each unit with a domain (e.g. content.grammar, security.audit)
4. Confirm the decomposition with the user before proceeding to Phase 2

Output format:

#	Capability unit	Domain	Input	Output
1	Grammar check	content.grammar	text	issues[], score
2	Readability analysis	content.readability	text	grade, suggestions[]

---

Phase 2: Gene Selection

Match existing Genes to each capability unit.

rotifer list
rotifer arena list --domain <domain>

Selection priority:

Priority	Source	Command
1	Local Gene with highest Arena rank	rotifer arena list --domain <d>
2	Cloud Registry	rotifer install <name>
3	Doesn't exist, needs creation	Proceed to Phase 3

Show the user candidate Genes' F(g) fitness and fidelity, let them confirm the selection.

---

Phase 3: Gap Filling

If a capability unit has no existing Gene:

Approach	When to use	Action
Create Wrapped Gene	External API / Skill available to wrap	Route to gene-dev Skill
Create Native Gene	Pure computation, no external dependencies	Route to gene-dev Skill
Adjust decomposition	Capability unit granularity is wrong	Return to Phase 1
Merge units	Two units are too coupled, splitting makes the interface awkward	Merge into one Gene

After all Genes are ready, proceed to Phase 4.

---

Phase 4: Genome Composition

Choose a composition strategy based on relationships between capability units.

Composition Strategy Decision Table

Strategy	Semantics	Use when	Example
Seq(A, B, C)	Pipeline: A → B → C	Previous output feeds the next	Check → Fix → Format
Par(A, B)	Parallel: run simultaneously	Independent tasks, merge results	Grammar check + Readability analysis
Cond(p, A, B)	Branch: if p then A else B	Input characteristics determine path	Chinese → Chinese proofing / English → English proofing
Try(A, B)	Fallback: A fails → B	Primary path unreliable	Main API → Backup API
TryPool(A, B, C)	Race: all try, first success wins	Multiple equivalent implementations	Multiple translation services racing

Par Merge Strategies

When using Par, specify --par-merge:

Strategy	Behavior	Use when
first	Take the first completed result	Racing scenario
concat	Concatenate all results (array)	Results are complementary
merge	Deep-merge objects	Same structure, merge fields

Seq Schema Compatibility Warning

Known limitation: Seq composition requires the previous Gene's outputSchema to be compatible with the next Gene's inputSchema. The current version does not auto-validate — schema mismatches cause runtime errors.

Recommendation: Before creating a Seq composition, manually compare adjacent Genes' inputSchema / outputSchema in phenotype.json to confirm field names and types match.

Nested Composition

Strategies can be nested:

Seq(
  Par(grammar-checker, readability-analyzer),
  tone-analyzer
)

Corresponding CLI:

rotifer agent create doc-qa \
  --genes grammar-checker readability-analyzer tone-analyzer \
  --composition Seq

The current CLI only supports top-level composition strategies. Nested compositions require manual editing of .rotifer/agents/<id>.json.

---

Phase 5: Agent Creation

Execute creation after confirming the composition plan.

Manual Gene Selection

rotifer agent create <name> \
  --genes <gene1> <gene2> <gene3> \
  --composition <Seq|Par|Cond|Try|TryPool> \
  --par-merge <first|concat|merge>

Auto-select Genes (by domain ranking)

rotifer agent create <name> \
  --domain <domain> \
  --top <n> \
  --composition <strategy>

After creation, verify the Agent configuration file .rotifer/agents/<name>.json is correct.

---

Phase 6: Test Run

rotifer agent run <name> --input '{"text": "Test input content"}'

Validation checklist:

• Does the output structure match the expected schema?
• Were all Genes executed? (check logs)
• Is schema passing correct in Seq composition?
• Are Par merge results complete?
• Do error paths (Try/TryPool) degrade correctly?

If results are unsatisfactory, proceed to Phase 7.

---

Phase 7: Iterative Optimization

Problem	Optimization
One Gene's output quality is poor	rotifer arena list --domain <d> to find alternatives
Seq intermediate results missing fields	Check schema compatibility, consider inserting an adapter Gene
Par merge results are messy	Switch --par-merge strategy
Latency too high	Seq → Par (if Genes are independent)
Overall below expectations	Route to rotifer-arena Skill for head-to-head Gene evaluation

---

Scenario Examples

Scenario 1: Document Quality Agent

Goal: Input text, output grammar issues + readability score + tone analysis.

Decomposition:

#	Capability	Gene	Domain
1	Grammar check	grammar-checker	content.grammar
2	Readability analysis	readability-analyzer	content.readability
3	Tone analysis	tone-analyzer	content.tone

Composition: All three accept text input, no dependencies → Par + concat.

rotifer agent create doc-quality \
  --genes grammar-checker readability-analyzer tone-analyzer \
  --composition Par \
  --par-merge concat

rotifer agent run doc-quality --input '{"text": "Document content to check..."}'

Scenario 2: Code Review Agent

Goal: Input code file, output security vulnerabilities + complexity report + documentation suggestions.

#	Capability	Gene	Domain
1	Security audit	security-auditor	security.audit
2	Complexity analysis	code-complexity	code.analysis
3	Documentation generation	docs-writer	content.docs

Composition: Security audit and complexity analysis can run in parallel, documentation depends on both → Seq(Par(1,2), 3).

rotifer agent create code-review \
  --genes security-auditor code-complexity docs-writer \
  --composition Seq

rotifer agent run code-review --input '{"code": "...", "language": "typescript"}'

Note: The Par(security-auditor, code-complexity) merged output must be compatible with docs-writer's inputSchema. Manual verification required.

Scenario 3: Search & Summarize Agent

Goal: Input a search query, search → summarize → format output.

#	Capability	Gene	Domain
1	Web search	genesis-web-search	search.web
2	Text summarization	text-summarizer	content.summarize
3	Markdown formatting	markdown-formatter	content.format

Composition: Strict serial pipeline → Seq.

rotifer agent create search-digest \
  --genes genesis-web-search text-summarizer markdown-formatter \
  --composition Seq

rotifer agent run search-digest --input '{"query": "Rotifer Protocol agent framework"}'

Note the Seq schema chain: genesis-web-search output field names must match text-summarizer's inputSchema. Run cat genes/*/phenotype.json | jq '.inputSchema, .outputSchema' to verify before creating.

---

Related Skills

Skill	Relationship	When to route
gene-dev	Gene creation/development	Phase 3 gap filling
rotifer-arena	Gene comparison & evaluation	Phase 7 when replacing underperforming Genes
genome	Genome quality analysis	After Agent creation for overall assessment

---

Constraints

• Agent configuration files are stored in .rotifer/agents/<id>.json and should not be committed to Git
• A single Agent should contain 2–6 Genes; more than 6 suggests splitting into multiple Agents
• Seq schema compatibility is a known limitation — always verify manually before creating
• Nested compositions require manual JSON editing; the CLI only supports top-level strategies