🦖 ClawBio Architecture

Overview

ClawBio is a collection of modular AI agent skills for bioinformatics, designed around three principles: local-first execution, reproducible analysis, and composable workflows.

System Design

ClawBio is easiest to read as a set of layers rather than one monolithic agent. Each layer has a narrow responsibility:

Layer	Main Files / Components	Responsibility
Interfaces	CLI, Python API, RoboTerri, Discord, OpenClaw gateway, Claude Code	Accept a user request, collect files, and either name a skill directly or ask for routing.
Skill self-description	skills/<name>/SKILL.md, optional skills/<name>/INTENTS.json, skills/catalog.json	Describe what the skill does, what inputs it accepts, how it is invoked, and when it should be considered.
Routing and planning	skills/bio-orchestrator/, clawbio/skill_intents.py, docs/skill-intents.md	Detect file types, headers, keywords, and structured intent descriptors; select a suitable skill or plan a small chain.
Runner and safety gate	clawbio.py / clawbio.run_skill()	Validate the selected skill, enforce allowed flags, prepare output directories, and launch the skill script.
Specialist skill execution	skills/<name>/<script>.py plus skill-local helpers	Run the domain method and produce skill-owned outputs.
Output contract	report.md, result.json, tables/, figures/, reproducibility/	Return human-readable reports, machine-readable results, preferred artifacts, suggested follow-ups, and replay metadata where supported.

Routing Logic

The Bio Orchestrator routes requests based on:

1. File extension: .vcf -> equity-scorer/vcf-annotator, .fastq -> seq-wrangler, etc.
2. Keyword matching: "diversity" -> equity-scorer, "structure" -> struct-predictor, etc.
3. User intent: Explicit skill names override automatic routing.
4. Chaining: Multi-step requests trigger sequential skill invocation with output piping.

Skill Independence

Every skill works standalone. The Bio Orchestrator adds:

• Automatic routing (user does not need to know skill names)
• Multi-skill chaining (pipe output of one skill to the next)
• Unified reporting (combine results from multiple skills)
• Access to skill-defined reproducibility outputs where a routed skill implements them

A user can invoke any skill directly without the orchestrator.

Skill Self-Description

Skills describe themselves before they execute. SKILL.md is the primary human- and agent-readable contract: it records the domain method, expected inputs, outputs, safety boundaries, demo commands, and gotchas. Python scripts are implementations of that contract, not replacements for it.

Some skills also publish optional intent descriptors in INTENTS.json or skill_intents.json; see docs/skill-intents.md for the descriptor schema. These files are data-only routing metadata for chat adapters and planners: aliases, trigger terms, slot extraction rules, safe execution plans, and confirmation gates. They do not grant new shell powers or new CLI flags; clawbio.py still enforces the registered allow-list.

Together, SKILL.md, optional intent descriptors, and skills/catalog.json let agents discover what a skill can do without scraping prose from previous chat sessions.

Data Flow

Input File(s)
    │
    ▼
Validation (file type, format, size checks)
    │
    ▼
Processing (skill-specific computation)
    │
    ▼
Results (tables, metrics, intermediate files)
    │
    ▼
Visualisation (matplotlib/seaborn figures)
    │
    ▼
Structured Output (result.json + preferred artifacts)
    │
    ▼
Report Assembly (markdown + embedded figures)
    │
    ▼
Optional Reproducibility Export (helper-backed commands, environment, checksums)

The same run may also expose UI-facing fields from result.json, including chat_summary_lines, preferred_artifacts, workflow_state, suggested_actions, and contract_alerts. These fields let chat or GUI frontends render compact summaries, offer deterministic next steps, and surface contract/path mismatches without inventing follow-up commands. See docs/skill-action-contract.md for the canonical schema reference.

Structured Next Steps

Where supported, a skill can describe valid follow-up actions in its result.json output:

• workflow_state: the lifecycle, label, and stable state identity for the completed run.
• preferred_artifacts: files the UI should surface first.
• suggested_actions: deterministic next-step requests, such as "show top results" or "summarise by category".
• chat_summary_lines: short skill-authored text suitable for chat adapters.

This keeps next-step menus tied to the skill's own state rather than to an agent's guess. Not every skill emits these fields yet; skills without them still return the standard report and output bundle.

Privacy Model

ClawBio enforces a strict local-first privacy model:

• No network calls for data processing. All computation happens locally.
• Optional network only for: literature search (PubMed API), structure database queries (PDB/UniProt), and package installation.
• Explicit consent required before any data leaves the machine.
• File access scoping: Skills operate within the current working directory by default. Access to parent directories requires user confirmation.

Reproducibility Contract

ClawBio's validated reproducibility contract is not universal across every skill. For skills that use the shared reproducibility helpers, the output directory typically includes:

1. reproducibility/commands.sh: A replay command for the skill run without needing the original agent session.
2. reproducibility/environment.yml: A suggested Conda environment snapshot for the run.
3. reproducibility/checksums.sha256: SHA-256 hashes for selected output files.
4. Optional extras: Some skills may emit additional provenance files such as runtime-lock.json or other lock metadata.

Important boundaries:

• Reproducibility behavior can vary by skill.
• Replays may still require external tools or the original input files to be present locally.
• analysis_log.md is not a guaranteed output for every skill.
• Portable replay scripts reduce path friction, but they are not a blanket promise that every run will reproduce unchanged on every machine.

See docs/reproducibility.md for the user workflow and a concrete multiqc-reporter example.

Skill Packaging

Each skill is a directory containing:

skill-name/
├── SKILL.md          # Required: YAML frontmatter + markdown instructions
├── skill_name.py     # Optional: Python implementation
├── utils.py          # Optional: shared utilities
├── tests/            # Optional: test cases
│   └── test_skill.py
└── examples/         # Optional: example inputs/outputs
    ├── input.vcf
    └── expected_output.md

The SKILL.md is the primary artifact. The Python files are supporting code that the agent invokes via shell commands. This separation means:

• Skills can be reviewed as markdown (human-readable)
• Python code can be tested independently
• Skills work with any compatible agent platform, not just OpenClaw

Integration with OpenBio

The existing OpenBio skill provides API access to:

• PDB (protein structures)
• UniProt (protein sequences and annotations)
• ChEMBL (bioactivity data)
• Pathway databases

ClawBio skills can call OpenBio for database lookups while keeping all computation local. For example, Struct Predictor might use OpenBio to fetch a reference structure from PDB, then run local AlphaFold for comparison.

Extensibility

New skills follow the template at templates/SKILL-TEMPLATE.md. The Bio Orchestrator routing table is designed to be extended: add a new entry mapping file types or keywords to your skill, and the orchestrator routes to it automatically.

Community submissions go through ClawHub or direct PR to this repository. 🦖