Guide · Agent skill
How to use the Waypoint microbiome models agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The waypoint-bio skill teaches an AI agent to work with Outpost Bio's open microbiome foundation models (the Waypoint checkpoints), the Atlas pretraining corpus, the Compass benchmark and the waypoint command-line tool. This guide explains what an agent skill is, how to install this one, how to ask for work in plain language, and what to check before you trust the results. By the end you will know how to get a microbiome abundance table into the format Waypoint expects and how to start an embedding or fine-tuning job safely.
Waypoint Microbiome ModelsK-Dense-AI/scientific-agent-skills · MIT Download the skill Quick start
- 1Download and unzip the skill. Download the ZIP from this page and unzip it. Place the folder in ~/.claude/skills/ for personal use or in a project's .claude/skills/ folder.
- 2Install the Python packages. Create a separate environment and install waypoint-bio with the pinned Transformers and PEFT releases from the setup notes.
- 3Request Hugging Face access. Request access on each gated repo you need, then run hf auth login or export HF_TOKEN.
- 4Convert your data. Use prepare-dataset for abundance matrices, or the bundled profiler converter for MetaPhlAn, Kraken2 or QIIME 2 output, to produce a parquet file.
- 5Check vocabulary coverage. Run the coverage script against your chosen checkpoint and review samples with low coverage.
- 6Ask for the task in plain language. Describe the embedding, fine-tuning or benchmark goal and name your data file so the agent picks the right subcommand.
What an agent skill is and what this one makes the agent do
An agent skill is a folder of instructions and helper files that an AI agent loads when a request matches the skill's description. This skill is defined by a SKILL.md file plus reference documents and two Python scripts.
Waypoint treats a microbiome sample as a sentence: each taxon is one token, tokens are ordered by descending abundance z-score, and the model is trained with next-token prediction. With the skill, the agent can embed samples into fixed-size vectors for clustering or classification, fine-tune a checkpoint on labelled abundance data, score a model on the eight-task Compass benchmark, pretrain on taxonomic profiles, and convert MetaPhlAn, Kraken2, QIIME 2 or MGnify tables into waypoint format.
- Embed microbiome profiles for clustering, visualisation or a downstream classifier
- Fine-tune a Waypoint checkpoint to predict a phenotype, treatment or continuous readout
- Benchmark your own microbiome model on Compass with a recorded protocol
- Convert profiler output into the waypoint data format
How to install the waypoint-bio skill
Download the skill ZIP from this page and unzip it. For a personal install, place the folder in ~/.claude/skills/. To scope it to one project, place it in that project's .claude/skills/ folder.
In the Claude apps you can instead upload the skill under Settings, then Capabilities, then Skills. Either way, start a new session afterwards so the agent picks it up.
- Personal: ~/.claude/skills/
- Project only: .claude/skills/ inside your project folder
- Claude apps: Settings → Capabilities → Skills
Set up Python, the waypoint-bio package and Hugging Face access
The skill needs Python (the source lists a minimum of 3.10) and the waypoint-bio package, with the compatible Transformers and PEFT releases pinned in the setup notes. A GPU is recommended for training but not needed for conversion or small tests.
The Waypoint checkpoints, the Atlas corpus and the Compass benchmark are gated on Hugging Face. Request access on each repo page you need, then authenticate. Access is auto-approved but requires a click-through once per repo. A read token (HF_TOKEN) is needed only for Hub downloads; local conversion works without it.
Note that the package does not bound its dependencies, and newer Transformers releases remove a pretraining argument. Keep a separate environment with the pinned versions.
- Gated repos: Waypoint-6m, Waypoint-45m, Waypoint-170m, Atlas and Compass
- 401 or 403 errors usually mean an invalid token, missing read scope, or no approval for that specific repo
- The upstream CLI has no revision flag; download a reviewed snapshot and pass its local path
pip install "waypoint-bio==1.0.2" "transformers==4.57.6" "peft==0.18.1" "huggingface-hub<1"
hf auth login
# or: export HF_TOKEN=hf_...Prepare your abundance data in waypoint format
Waypoint consumes a parquet, CSV or TSV file where each row is a sample, with a Taxa list column of full lineage strings and a Relative Abundances list column of the same length and order. Any label or covariate columns sit alongside. Use parquet, because CSV and TSV loading in the upstream tool loses the sample-ID index and does not parse string lists.
Give full lineages such as k__Bacteria; p__Firmicutes; g__Lactobacillus, not bare names. The tokenizer reads the genus segment and falls back to a higher rank only when genus is missing; bare names turn that fallback off.
If you already have a sample by taxa abundance matrix, prepare-dataset converts it. It detects orientation from the first column header and normalises rows to sum to 1 unless you pass the no-normalise flag. It cannot read profiler output directly, so use the bundled converter for MetaPhlAn, Kraken2 reports and QIIME 2 tables.
- Required columns: Taxa and Relative Abundances
- Keep full lineage strings with ; separators
- MetaPhlAn uses | separators, Kraken2 encodes hierarchy as indentation, and QIIME 2 or SILVA use d__ instead of k__
waypoint prepare-dataset --input abundance_matrix.tsv --metadata sample_labels.csv --output dataset.parquet
python scripts/profiler_to_waypoint.py --input merged_metaphlan.tsv --format metaphlan --output dataset.parquet
python scripts/profiler_to_waypoint.py --input reports/*.kreport --format kraken --output dataset.parquet
python scripts/profiler_to_waypoint.py --input feature-table.tsv --format qiime2 --taxonomy-column taxonomy --output dataset.parquetCheck vocabulary coverage before you run anything
Waypoint's vocabulary is fixed at pretraining time from Atlas. Taxa outside that vocabulary become unknown tokens and are silently dropped by waypoint embed. A sample whose taxa are all out of vocabulary gets a degenerate embedding, so check coverage first.
The coverage script reports per-sample coverage against a chosen checkpoint. Look at it before embedding or training, and treat low-coverage samples as a data problem rather than a model result.
- Run the coverage check against the same checkpoint you plan to use
- Investigate samples with very low coverage before you interpret their embeddings
python scripts/vocab_coverage.py --model outpost-bio/Waypoint-6m --data dataset.parquetAsk the agent for embeddings, fine-tuning or benchmarks
Once the skill is loaded, describe the outcome you want in plain language. Name your data file, the checkpoint if you have one in mind, and the task. The agent chooses the matching subcommand (prepare-dataset, embed, finetune, benchmark or pretrain) and reads the reference files for flags and config paths.
Training examples in the skill are source-checked templates, not completed scientific runs. Expect the agent to explain what it is about to run and to flag upstream issues, such as the local tokenizer save error that blocks pretraining and some fine-tuning exports.
- Good request: Convert this MetaPhlAn table, check coverage against Waypoint-6m, then embed the samples
- Good request: Fine-tune Waypoint-6m on dataset.parquet with the Split column, predicting the disease label
- Good request: Score my model on the Compass benchmark and record the protocol
Safety notes: scripts and network use
The skill runs Python scripts and uses the network for Hub downloads. The tokenizer loader executes repository code with trust_remote_code enabled, so review that code and pin an immutable Hub commit before use. The skill is licensed MIT, but the Waypoint models, Atlas and Compass data carry their own gated access terms on Hugging Face.
Do not use outputs for clinical or diagnostic decisions. The models are research artefacts, and performance on a new study is not guaranteed.
- Read the scripts in scripts/ before running them on sensitive data
- Keep HF_TOKEN out of shared notebooks and logs
- Run conversion locally when you do not need Hub access
What people use it for
- Embedding gut microbiome profiles from a cohort for clustering or visualisation
- Fine-tuning a Waypoint checkpoint to predict a treatment response from abundance tables
- Converting a batch of Kraken2 reports into a single waypoint-format parquet file
- Benchmarking a team's own microbiome model on the Compass eight-task suite
Frequently asked questions
Is the waypoint-bio skill free to use?
The skill is released under the MIT licence. The Waypoint checkpoints, Atlas and Compass are open from Outpost Bio but gated on Hugging Face, so you must request access and authenticate for Hub downloads.
What do I need to run the waypoint-bio skill?
You need Python, the waypoint-bio package with the pinned Transformers and PEFT releases, and a Hugging Face read token only if you download gated repos. A GPU is recommended for training but not required for data conversion.
How do I install an agent skill like this one?
Download the ZIP from this page and unzip it into ~/.claude/skills/ or a project's .claude/skills/ folder. Alternatively, upload it in the Claude apps under Settings, then Capabilities, then Skills.
Why do my Hugging Face downloads return 401 or 403 errors?
Check that your token is valid and has read scope, and that you have been approved for the specific repo. Each Waypoint, Atlas and Compass repo needs its own access request.
Can I use MetaPhlAn or Kraken2 output with Waypoint?
Yes, but not directly with prepare-dataset. Use the bundled profiler converter, which handles MetaPhlAn pipe separators, Kraken2 indentation and QIIME 2 domain prefixes.
Are embeddings from Waypoint better than a random forest?
Not guaranteed. For small labelled datasets, the source recommends starting with a random-forest baseline using grouped validation, because embeddings may not help and performance on a new study is not assured.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
This skill suits microbiome researchers and data scientists who work with taxonomic abundance tables and want embeddings, a fine-tuned predictor or a Compass benchmark run. If you have a small labelled dataset, need clinical or diagnostic output, or cannot check taxa coverage, start with a simpler baseline such as a random forest with grouped validation instead.
Download the skill