Omics Skills

A skill and agent pack for omics data analysis, literature discovery, scientific writing, and data visualization. Works with Claude Code and the Codex CLI.

Documentation

Read the docs at https://fmschulz.github.io/omics-skills/. They cover installation, the agent set, the skill catalog, routing, and development. Release notes are published on the GitHub Releases page.

Scope

Four agent personas — omics-scientist, literature-expert, science-writer, dataviz-artist — compose a set of small, single-purpose skills (SKILL.md files) for tasks ranging from read QC through assembly, gene calling, annotation, phylogenomics, comparative genomics, structure prediction, viromics, interdomain HGT, statistics, manuscript drafting, and figure generation.

The canonical agent sources are Markdown prompts. Installation keeps those files for Claude Code and renders native TOML agent definitions for Codex. Skills are Markdown directories with defined input/output contracts. A deterministic router (scripts/skill_index.py) picks an agent and an ordered set of skills for a task.

How Analyses Are Run

Every skill can be used on its own. The bio-* skills also share a few habits that make exploratory analyses easier to audit and reproduce:

• Hypothesis register. Exploratory work starts with at least five working hypotheses (biological mechanism, technical artifact, null, sampling or batch effect, database artifact). Each is revised as supported, weakened, ruled out, or unresolved, with the evidence that changed its status.
• Reflection after each step. After each major result or QC gate, the agent records what was observed, which hypotheses gained or lost support, and the next discriminating check.
• Literature-derived analysis plan. Before deciding what is "interesting" the agent reads the literature for the inferred group and summarises which markers, comparison sets, plots, and outliers are diagnostic.
• Comparative axes against close relatives. When relatives are available, the query is run through five axes — genome-property frontier, marker-gene census, per-family copy-number, synteny and conserved neighborhoods, and non-coding RNA census — each producing a side-by-side comparison file.
• Literature search with fallbacks. When users provide API access or local corpora, polars-dovmed queries PMC and bioRxiv through the hosted API or a local parquet dovmed scan, then falls back to targeted WebFetch / WebSearch so endpoint outages do not silently skip the literature step.

Tooling baseline

Skills target current stable releases as of 2026 and document GPU alternatives where they exist.

The full survey of versions, alternatives, and benchmarks is in docs/tooling-survey-2026.md.

Installation

Claude Code / Cowork Plugin Marketplace

This repository is packaged as a Claude Code / Cowork plugin marketplace. To test the marketplace directly from GitHub:

claude plugin marketplace add fmschulz/omics-skills
claude plugin install omics-skills@omics-skills

To test a local checkout before submitting or publishing changes:

claude plugin validate .
claude plugin marketplace add ./
claude plugin install omics-skills@omics-skills

After Anthropic approves the community marketplace submission, users can install it from the public Claude plugin catalog.

Codex Plugin Marketplace

The repository also includes a native Codex plugin manifest and repo marketplace:

codex plugin marketplace add fmschulz/omics-skills
codex plugin add omics-skills@omics-skills

For a local checkout, replace fmschulz/omics-skills with .. Run codex plugin list --available --json to inspect the resolved plugin before installing it.

Makefile

git clone https://github.com/fmschulz/omics-skills.git
cd omics-skills
make install

make install builds the routing catalog, installs skills under ~/.agents/skills, symlinks the Claude agent sources, and renders Codex agents as TOML. Use make install-claude or make install-codex for one runtime, make install INSTALL_METHOD=copy for copied skills, and make status to inspect the result. Re-run the installer after changing an agent prompt because generated Codex TOML files cannot track Markdown changes through a symlink. See docs/INSTALL.md for troubleshooting.

The routing hook attaches the router to every user prompt:

make install-hook        # Claude Code + Codex CLI
make hook-status
make uninstall-hook

Set OMICS_SKILLS_AUTOROUTE=0 to suppress the hint for a session without uninstalling.

Usage

claude --agent omics-scientist
codex

In Codex, ask the primary agent to delegate to omics-scientist, or invoke a skill explicitly with $bio-annotation. The installed TOML definitions under ~/.codex/agents/ are available to Codex as custom subagents.

Query the router directly:

python3 scripts/skill_index.py route \
  "assemble a metagenome and recover MAGs"

Skills are also invocable individually as /<skill-name> in Claude Code or $<skill-name> in Codex. Agent files list the skills each agent exposes and how they compose.

Agents

Run python3 scripts/skill_index.py route --agent <agent> "<task>" to see how a specific agent routes a given task.

Repository layout

agents/                     4 agent definitions
skills/                     skill directories; each has a SKILL.md
catalog/                    generated router artifact (catalog.json)
scripts/
  skill_index.py            router and catalog builder
  routing_benchmark.py      regression harness
  emit_routing_hint.py      hook payload generator
  install_hook.py           idempotent hook installer
  install.sh                shell-script install (Makefile-free)
  uninstall.sh, test-install.sh, validate-skills.py
tests/
  test_skill_index.py       unit tests for catalog and router
  test_install_selected.py  selected-install and uninstall integration tests
  test_jgi_lakehouse_helpers.py JGI helper safety tests
  test_routing_benchmark.py harness sanity tests
  test_emit_routing_hint.py hook-script tests
  routing_benchmark.yaml    routing regression suite
docs/
  INSTALL.md                 detailed installation and troubleshooting guide
  CONTRIBUTING.md            contribution workflow
  DISTRIBUTION.md            distribution and discovery notes
  SKILL_GRAPH.md            routing model and graph
  routing_baseline.json     benchmark baseline
  tooling-survey-2026.md    bioinformatics tooling survey
Makefile                    install, catalog, hook, benchmark, uninstall targets

Development

uv run --no-project --with requests python -m unittest discover -s tests -v
make benchmark                                  # routing regression vs baseline
python3 scripts/skill_index.py build            # rebuild catalog artifacts

Adding or modifying a skill:

1. Create or edit skills/<name>/SKILL.md. The YAML name field must match the directory name.
2. Add the skill to the relevant agent's Mandatory Skill Usage and Task Recognition Patterns.
3. Rebuild the catalog and run the test suite.
4. Add a benchmark row in tests/routing_benchmark.yaml if the skill is non-trivially discoverable by the router.

See AGENTS.md for structural conventions, docs/SKILL_GRAPH.md for how the router scores and composes skills, docs/CONTRIBUTING.md for contribution flow, and docs/skills.md for the public skill catalog.

Compatibility

License

MIT. See LICENSE.