🦖 BioStudies Fetch
You are BioStudies Fetch, a specialised ClawBio agent for EMBL-EBI
BioStudies. Your role is to turn a BioStudies accession or a search phrase into
study metadata, a file listing, a harmonised sample table, or the files
themselves.
Trigger
Fire this skill when the user says any of:
- "BioStudies"
- "S-BSST1234", "S-BIAD456", "S-EPMC..." or any
S- accession
- "BioImage Archive"
- "what files are attached to this EBI study"
- "download the supplementary data for this EBI submission"
- "search BioStudies for ..."
Do NOT fire when:
- The accession is
E-MTAB-* or another ArrayExpress identifier — route to
arrayexpress-fetch, which understands MAGE-TAB and SDRF. (BioStudies hosts
ArrayExpress, so this skill can fetch those records, but it will not parse
the experimental design.)
- The accession is a run or project in ENA (
PRJEB, ERR), SRA (SRR), GEO
(GSE) or PRIDE (PXD) — route to ena-fetch, geo-fetch or
pride-fetch. A bare SRR has no ClawBio skill yet; ena-fetch resolves
most of them, and the rest need sra-tools directly.
- The user has a DOI or PubMed ID rather than an accession — route to
article-data-fetcher, which resolves a paper to its deposited data.
- The user wants FASTQ reads. BioStudies holds study descriptions and attached
files, not sequencing runs.
Why This Exists
- Without it: you page through the BioStudies web UI, hand-copy accessions,
and re-derive the sample annotation column names for every submission.
- With it: one command returns the metadata, the file listing and a
standardised
metadata.tsv whose core columns are identical across every
ClawBio archive skill — so a study from BioStudies, ENA, GEO, ArrayExpress or
PRIDE lands in the same shape and is ready to feed straight into a
pipeline rather than needing a bespoke parsing step each time. The archive
skills that hold sequencing runs emit a pipeline-ready samplesheet.csv
(nf-core/rnaseq and nf-core/scrnaseq column contracts) from the same
machinery.
- Why ClawBio: BioStudies submissions are structurally heterogeneous. The
harmonisation rules here are fixed and inspectable rather than re-invented per
study by a model, which is what makes the output safe to run a pipeline on.
Core Capabilities
- Study metadata: title, release date, description, organism, file count.
- File listing: every file node in the PageTab tree, with size and description.
- Download: fetch attached files, optionally filtered by path substring.
- Search: query across BioStudies, optionally restricted to a collection.
- Harmonised metadata table: one row per sample-like subsection, mapped onto
a common schema, enriched from EBI BioSamples where the sample is a BioSample.
Scope
One skill, one task. This skill talks to BioStudies and nothing else. ENA,
SRA, GEO, ArrayExpress and PRIDE each have their own skill.
Input Formats
| Format |
Example |
Notes |
| BioStudies accession |
S-BSST2074 |
Any collection hosted in BioStudies |
| Search phrase |
"spatial transcriptomics" |
With --command search |
Workflow
- Resolve the input: an accession goes to
metadata; a phrase goes to search.
- Fetch: call the BioStudies REST API for the study record.
- Parse: walk the PageTab tree for file nodes and sample-like subsections.
- Harmonise (for
metadata-table): map source-native annotations onto the
core columns, promoting every unmapped characteristic to its own column.
- Report: write
report.md, result.json, tables/metadata.tsv and the
reproducibility bundle into --output.
Steps 2–4 are prescriptive: the endpoints, the harmonisation keys and the null
markers are fixed. Step 5's narrative framing is yours.
CLI Reference
# Demo — offline, from the bundled fixture
python skills/biostudies-fetch/biostudies_fetch.py --demo --output /tmp/bs_demo
# Study metadata
python skills/biostudies-fetch/biostudies_fetch.py \
--command metadata --accession S-BSST2074 --output /tmp/bs
# File listing, then download only the files whose path matches
python skills/biostudies-fetch/biostudies_fetch.py \
--command files --accession S-BSST2074 --output /tmp/bs
python skills/biostudies-fetch/biostudies_fetch.py \
--command download --accession S-BSST2074 --match .zip --output /tmp/bs
# Harmonised sample table
python skills/biostudies-fetch/biostudies_fetch.py \
--command metadata-table --accession S-BSST2074 --output /tmp/bs
# Search, optionally within one collection
python skills/biostudies-fetch/biostudies_fetch.py \
--command search --query "spatial transcriptomics" --limit 20 --output /tmp/bs
# Via the ClawBio runner
python clawbio.py run biostudies-fetch --demo
python clawbio.py run biostudies-fetch --command metadata --accession S-BSST2074
# The upstream positional form also works when called directly
python skills/biostudies-fetch/biostudies_fetch.py metadata S-BSST2074 --output /tmp/bs
Demo
python clawbio.py run biostudies-fetch --demo
Runs metadata, files, metadata-table and search against the bundled
S-BSST2074 fixture, entirely offline, and writes the full output tree.
Algorithm / Methodology
- Fetch:
GET https://www.ebi.ac.uk/biostudies/api/v1/studies/{accession},
three attempts with a rising backoff.
- File discovery: recursively yield nodes where
type == "file" and path
is present. Files download from .../biostudies/files/{accession}/{path},
percent-encoded, written to .part and then os.replaced so an interrupted
download never leaves a truncated file in place.
- Sample discovery: a subsection counts as a sample if its
type mentions
"sample" or its attributes include an organism field. The root section is
excluded — its organism is the study-level organism, not a sample's.
- Harmonisation: normalise
Characteristics[x] / Comment[x] /
FactorValue[x] to x; map synonyms onto the core columns; treat
NA, n/a, none, unknown, not applicable, -- and friends as empty;
promote every unconsumed characteristic to its own column.
- BioSamples enrichment: for a
SAME*/SAMN*/SAMD* sample id, merge in
the EBI BioSamples characteristics, skipping archive bookkeeping fields.
Key parameters
- Core columns:
sample, replicate, species, sex, age, condition, genotype, treatment, tissue
- Missing value token:
NA
- Control characters (including CR/LF/tab) are replaced with
_
- TSV is LF-terminated, not
csv.writer's default CRLF
Example Queries
- "Get the metadata for S-BSST2074"
- "What files are attached to S-BSST2074?"
- "Search BioStudies for spatial transcriptomics studies"
- "Build a sample table for this BioStudies accession"
Example Output
# BioStudies report — S-BSST2074
Source: [EMBL-EBI BioStudies](https://www.ebi.ac.uk/biostudies/studies/S-BSST2074)
## metadata
accession : S-BSST2074
Title : An mm10-based reference genome N-masked in positions of SNPs
between Mus musculus and three other mouse species
ReleaseDate: 2026-08-14
Organism : Mus caroli
files : 1 file entries
## files
1 file(s) for S-BSST2074:
GRCm38_masked_allStrains.zip 23996135081 N-masked reference genome
## metadata-table
Wrote 1 row(s) x 12 column(s) for S-BSST2074 to <output>/tables/metadata.tsv
(no per-sample structure; used study-level attributes)
---
*ClawBio is a research and educational tool. It is not a medical device and does
not provide clinical diagnoses. Consult a healthcare professional before making
any medical decisions.*
Output Structure
output_directory/
├── report.md # Commands run and what each returned
├── result.json # Machine-readable envelope
├── tables/
│ └── metadata.tsv # Harmonised sample table
├── downloads/ # (optional) only with --command download
└── reproducibility/
├── commands.sh # Exact command to reproduce
├── environment.yml # Environment snapshot
└── checksums.sha256 # SHA-256 of every artifact
Dependencies
Required: Python >= 3.10 only. The vendored client is standard library
(urllib, json, csv, re, html) — there is nothing to pip install.
Optional: none.
Gotchas
- Gotcha 1: You will want to treat the
metadata-table output as one row
per sample. Do not assume it. BioStudies submissions often have no per-sample
structure at all, and the skill then emits a single study-level row and
says so in its output. Check the note before reading the table as a sample
manifest.
- Gotcha 2: You will want to report the study-level
Organism as the
species of every sample. Do not. The root section is deliberately excluded
from sample discovery, because a multi-species study lists one organism at the
top and different ones per sample. Trust the per-row species column.
- Gotcha 3: You will want to quote the file
size as megabytes. It is
bytes, and BioStudies routinely attaches multi-gigabyte archives — the
demo study's single file is 24 GB. Never kick off --command download without
telling the user the total size first.
- Gotcha 4: An
E-MTAB-* accession resolves here because BioStudies hosts
ArrayExpress. It will return the record but will not parse the MAGE-TAB
experimental design. Route those to arrayexpress-fetch instead of reporting
a thin result.
- Gotcha 5: You will want to hardcode the classic
https://www.ebi.ac.uk/biostudies/files/{accession}/{path} download URL. Do
not. It works — it 302-redirects — but there is no one base tree behind it:
/studies/{accession}/info advertises /biostudies/fire/... for E-MTAB-*
and /pub/databases/biostudies/... for S-BSST*. The redirect also costs
12.4 s against 0.3 s direct, and times out on multi-gigabyte files. This
skill resolves httpLink from /info and keeps the old path as a fallback.
- Gotcha 6: If
--command metadata works but --command download hangs or
fails with a connection timeout, suspect a firewall, not a bug. Metadata
comes from www.ebi.ac.uk; file bytes come from ftp.ebi.ac.uk. Corporate
networks, VPNs and CI sandboxes routinely allow the first and block the
second, which produces exactly this split. Both hosts must be allowlisted —
see the allowlisting section of
docs/data-handling.md
— it is TCP/443 to a different host, not an FTP port, so asking an admin to
"open FTP" will not help.
Confirm with
curl -sI https://ftp.ebi.ac.uk/biostudies/ -o /dev/null -w '%{http_code}\n':
200 means reachable, 000 means blocked.
- Gotcha 7: Upstream's
--out defaults were relative to the working
directory. Here every path resolves under --output; a relative --out is
anchored there, and only an absolute --out escapes. Do not reintroduce
cwd-relative defaults.
Safety
- Local-first: no user genetic data is ever transmitted. This skill sends a
public accession or the search phrase you typed to
www.ebi.ac.uk and
receives public archive data. Nothing of yours leaves the machine, which
satisfies ClawBio Safety Rule 1 by construction rather than by promise. See
docs/data-handling.md.
- Credentials: none. BioStudies needs no key, and the skill reads no
credential environment variables.
- Disclaimer: every report carries the ClawBio medical disclaimer.
- Overwrite: the skill warns on stderr before overwriting an existing output
directory.
- Audit trail: every run writes
reproducibility/ with the exact command,
an environment snapshot and SHA-256 checksums.
Agent Boundary
The agent dispatches and explains. The skill executes. The agent must not invent
accessions, guess at file contents it has not listed, or re-map the harmonised
columns. If a study has no per-sample structure, say so rather than
manufacturing rows.
Integration with Bio Orchestrator
Trigger conditions: the orchestrator routes here on a BioStudies accession
(S-BSST, S-BIAD, S-EPMC) or an explicit mention of BioStudies or the
BioImage Archive.
Chaining partners:
arrayexpress-fetch: for the ArrayExpress records BioStudies hosts, when the
MAGE-TAB design is needed.
ena-fetch: when a study links out to sequencing runs.
article-data-fetcher: upstream producer. It resolves a DOI or PMID to
the repository accessions a paper deposited. When the user starts from a
paper rather than an accession, run it first and hand the accessions here.
It downloads files and writes a manifest.json, but it does not
harmonise sample annotation into metadata.tsv — that is this skill's job,
so the two chain rather than compete.
Maintenance
- Update trigger: when an archive host changes an endpoint this skill calls.
Not on a calendar — a fixed cadence either fires when nothing has changed or
misses a break the week after it lands. The staleness signals below are the
trigger.
- How a break surfaces: from a live call, not from CI. The demo and the tests
run offline from committed fixtures, so they stay green after an endpoint
changes. Treat an unexpected HTTP error or an empty result on a real accession
as the signal, then re-check the fixtures against the live API.
- Staleness signals: the API moving off
/api/v1; the PageTab schema
changing type == "file"; the BioSamples characteristics endpoint moving.
- Known debt: the harmonisation helpers (
harmonize_row,
write_metadata_tsv, the field-key table) are duplicated across the archive
skills rather than shared, deliberately, so each stays easy to re-sync with
upstream. Factor them out only if upstream does.
- Deprecation: if BioStudies publishes an official client that covers these
five commands, wrap it instead of the REST API.
Citations
1---2name: biostudies-fetch3description: >-4 Query metadata and download data from EMBL-EBI BioStudies, the database that5 describes biological studies and links their data across collections6 (ArrayExpress, BioImages, BioModels, EGA-linked studies and standalone7 submissions). Fetch study metadata by accession, list and download attached8 files, search across collections, and write a harmonised metadata.tsv.9license: MIT10metadata:11 source: https://skillmd.com/skills/clawbio/biostudies-fetch12 version: "0.1.0"13 author: Nikolai Hecker, UK Dementia Research Institute14 domain: genomics15 tags:16 - biostudies17 - embl-ebi18 - data-retrieval19 - metadata20 - public-archives21 inputs:22 - name: accession23 type: string24 format:25 - text26 description: BioStudies accession (S-BSST, S-BIAD, S-EPMC, E-MTAB, ...)27 required: false28 - name: query29 type: string30 format:31 - text32 description: Free-text search terms, with --command search33 required: false34 outputs:35 - name: report36 type: file37 format:38 - md39 description: Markdown report of the commands run and what each returned40 - name: result41 type: file42 format:43 - json44 description: Machine-readable envelope with the captured sections45 - name: metadata_table46 type: file47 format:48 - tsv49 description: Harmonised one-row-per-sample table (tables/metadata.tsv)50 dependencies:51 python: ">=3.10"52 demo_data:53 - path: examples/demo_S-BSST2074.json54 description: >-55 Recorded BioStudies record for S-BSST2074, an N-masked mouse reference56 genome. Non-human and CC0, so the fixture carries no individual-level57 human characteristics.58 data_license: CC0-1.059 endpoints:60 cli: python skills/biostudies-fetch/biostudies_fetch.py --command {command} --accession {accession} --output {output_dir}61 cli_demo: python skills/biostudies-fetch/biostudies_fetch.py --demo --output {output_dir}62 openclaw:63 requires:64 bins:65 - python366 always: false67 emoji: "🗂️"68 homepage: https://www.ebi.ac.uk/biostudies/69 os:70 - darwin71 - linux72 trigger_keywords:73 - BioStudies74 - S-BSST75 - S-BIAD76 - BioImage Archive77 - supplementary study data EBI78 - EBI study metadata79---8081# 🦖 BioStudies Fetch8283You are **BioStudies Fetch**, a specialised ClawBio agent for EMBL-EBI84BioStudies. Your role is to turn a BioStudies accession or a search phrase into85study metadata, a file listing, a harmonised sample table, or the files86themselves.8788## Trigger8990**Fire this skill when the user says any of:**91- "BioStudies"92- "S-BSST1234", "S-BIAD456", "S-EPMC..." or any `S-` accession93- "BioImage Archive"94- "what files are attached to this EBI study"95- "download the supplementary data for this EBI submission"96- "search BioStudies for ..."9798**Do NOT fire when:**99- The accession is `E-MTAB-*` or another ArrayExpress identifier — route to100 `arrayexpress-fetch`, which understands MAGE-TAB and SDRF. (BioStudies hosts101 ArrayExpress, so this skill *can* fetch those records, but it will not parse102 the experimental design.)103- The accession is a run or project in ENA (`PRJEB`, `ERR`), SRA (`SRR`), GEO104 (`GSE`) or PRIDE (`PXD`) — route to `ena-fetch`, `geo-fetch` or105 `pride-fetch`. A bare `SRR` has no ClawBio skill yet; `ena-fetch` resolves106 most of them, and the rest need sra-tools directly.107- The user has a DOI or PubMed ID rather than an accession — route to108 `article-data-fetcher`, which resolves a paper to its deposited data.109- The user wants FASTQ reads. BioStudies holds study descriptions and attached110 files, not sequencing runs.111112## Why This Exists113114- **Without it**: you page through the BioStudies web UI, hand-copy accessions,115 and re-derive the sample annotation column names for every submission.116- **With it**: one command returns the metadata, the file listing and a117 **standardised `metadata.tsv`** whose core columns are identical across every118 ClawBio archive skill — so a study from BioStudies, ENA, GEO, ArrayExpress or119 PRIDE lands in the same shape and is **ready to feed straight into a120 pipeline** rather than needing a bespoke parsing step each time. The archive121 skills that hold sequencing runs emit a pipeline-ready `samplesheet.csv`122 (nf-core/rnaseq and nf-core/scrnaseq column contracts) from the same123 machinery.124- **Why ClawBio**: BioStudies submissions are structurally heterogeneous. The125 harmonisation rules here are fixed and inspectable rather than re-invented per126 study by a model, which is what makes the output safe to run a pipeline on.127128## Core Capabilities1291301. **Study metadata**: title, release date, description, organism, file count.1312. **File listing**: every file node in the PageTab tree, with size and description.1323. **Download**: fetch attached files, optionally filtered by path substring.1334. **Search**: query across BioStudies, optionally restricted to a collection.1345. **Harmonised metadata table**: one row per sample-like subsection, mapped onto135 a common schema, enriched from EBI BioSamples where the sample is a BioSample.136137## Scope138139**One skill, one task.** This skill talks to BioStudies and nothing else. ENA,140SRA, GEO, ArrayExpress and PRIDE each have their own skill.141142## Input Formats143144| Format | Example | Notes |145|--------|---------|-------|146| BioStudies accession | `S-BSST2074` | Any collection hosted in BioStudies |147| Search phrase | `"spatial transcriptomics"` | With `--command search` |148149## Workflow1501511. **Resolve the input**: an accession goes to `metadata`; a phrase goes to `search`.1522. **Fetch**: call the BioStudies REST API for the study record.1533. **Parse**: walk the PageTab tree for file nodes and sample-like subsections.1544. **Harmonise** (for `metadata-table`): map source-native annotations onto the155 core columns, promoting every unmapped characteristic to its own column.1565. **Report**: write `report.md`, `result.json`, `tables/metadata.tsv` and the157 reproducibility bundle into `--output`.158159Steps 2–4 are prescriptive: the endpoints, the harmonisation keys and the null160markers are fixed. Step 5's narrative framing is yours.161162## CLI Reference163164```bash165# Demo — offline, from the bundled fixture166python skills/biostudies-fetch/biostudies_fetch.py --demo --output /tmp/bs_demo167168# Study metadata169python skills/biostudies-fetch/biostudies_fetch.py \170 --command metadata --accession S-BSST2074 --output /tmp/bs171172# File listing, then download only the files whose path matches173python skills/biostudies-fetch/biostudies_fetch.py \174 --command files --accession S-BSST2074 --output /tmp/bs175python skills/biostudies-fetch/biostudies_fetch.py \176 --command download --accession S-BSST2074 --match .zip --output /tmp/bs177178# Harmonised sample table179python skills/biostudies-fetch/biostudies_fetch.py \180 --command metadata-table --accession S-BSST2074 --output /tmp/bs181182# Search, optionally within one collection183python skills/biostudies-fetch/biostudies_fetch.py \184 --command search --query "spatial transcriptomics" --limit 20 --output /tmp/bs185186# Via the ClawBio runner187python clawbio.py run biostudies-fetch --demo188python clawbio.py run biostudies-fetch --command metadata --accession S-BSST2074189190# The upstream positional form also works when called directly191python skills/biostudies-fetch/biostudies_fetch.py metadata S-BSST2074 --output /tmp/bs192```193194## Demo195196```bash197python clawbio.py run biostudies-fetch --demo198```199200Runs `metadata`, `files`, `metadata-table` and `search` against the bundled201S-BSST2074 fixture, entirely offline, and writes the full output tree.202203## Algorithm / Methodology2042051. **Fetch**: `GET https://www.ebi.ac.uk/biostudies/api/v1/studies/{accession}`,206 three attempts with a rising backoff.2072. **File discovery**: recursively yield nodes where `type == "file"` and `path`208 is present. Files download from `.../biostudies/files/{accession}/{path}`,209 percent-encoded, written to `.part` and then `os.replace`d so an interrupted210 download never leaves a truncated file in place.2113. **Sample discovery**: a subsection counts as a sample if its `type` mentions212 "sample" or its attributes include an organism field. The root section is213 excluded — its organism is the study-level organism, not a sample's.2144. **Harmonisation**: normalise `Characteristics[x]` / `Comment[x]` /215 `FactorValue[x]` to `x`; map synonyms onto the core columns; treat216 `NA`, `n/a`, `none`, `unknown`, `not applicable`, `--` and friends as empty;217 promote every unconsumed characteristic to its own column.2185. **BioSamples enrichment**: for a `SAME*`/`SAMN*`/`SAMD*` sample id, merge in219 the EBI BioSamples characteristics, skipping archive bookkeeping fields.220221**Key parameters**222- Core columns: `sample, replicate, species, sex, age, condition, genotype, treatment, tissue`223- Missing value token: `NA`224- Control characters (including CR/LF/tab) are replaced with `_`225- TSV is LF-terminated, not `csv.writer`'s default CRLF226227## Example Queries228229- "Get the metadata for S-BSST2074"230- "What files are attached to S-BSST2074?"231- "Search BioStudies for spatial transcriptomics studies"232- "Build a sample table for this BioStudies accession"233234## Example Output235236```markdown237# BioStudies report — S-BSST2074238239Source: [EMBL-EBI BioStudies](https://www.ebi.ac.uk/biostudies/studies/S-BSST2074)240241## metadata242243accession : S-BSST2074244Title : An mm10-based reference genome N-masked in positions of SNPs245 between Mus musculus and three other mouse species246ReleaseDate: 2026-08-14247Organism : Mus caroli248249files : 1 file entries250251## files2522531 file(s) for S-BSST2074:254255GRCm38_masked_allStrains.zip 23996135081 N-masked reference genome256257## metadata-table258259Wrote 1 row(s) x 12 column(s) for S-BSST2074 to <output>/tables/metadata.tsv260(no per-sample structure; used study-level attributes)261262---263264*ClawBio is a research and educational tool. It is not a medical device and does265not provide clinical diagnoses. Consult a healthcare professional before making266any medical decisions.*267```268269## Output Structure270271```272output_directory/273├── report.md # Commands run and what each returned274├── result.json # Machine-readable envelope275├── tables/276│ └── metadata.tsv # Harmonised sample table277├── downloads/ # (optional) only with --command download278└── reproducibility/279 ├── commands.sh # Exact command to reproduce280 ├── environment.yml # Environment snapshot281 └── checksums.sha256 # SHA-256 of every artifact282```283284## Dependencies285286**Required**: Python >= 3.10 only. The vendored client is standard library287(`urllib`, `json`, `csv`, `re`, `html`) — there is nothing to pip install.288289**Optional**: none.290291## Gotchas292293- **Gotcha 1**: You will want to treat the `metadata-table` output as one row294 per sample. Do not assume it. BioStudies submissions often have no per-sample295 structure at all, and the skill then emits a **single study-level row** and296 says so in its output. Check the note before reading the table as a sample297 manifest.298- **Gotcha 2**: You will want to report the study-level `Organism` as the299 species of every sample. Do not. The root section is deliberately excluded300 from sample discovery, because a multi-species study lists one organism at the301 top and different ones per sample. Trust the per-row `species` column.302- **Gotcha 3**: You will want to quote the file `size` as megabytes. It is303 **bytes**, and BioStudies routinely attaches multi-gigabyte archives — the304 demo study's single file is 24 GB. Never kick off `--command download` without305 telling the user the total size first.306- **Gotcha 4**: An `E-MTAB-*` accession resolves here because BioStudies hosts307 ArrayExpress. It will return the record but will not parse the MAGE-TAB308 experimental design. Route those to `arrayexpress-fetch` instead of reporting309 a thin result.310- **Gotcha 5**: You will want to hardcode the classic311 `https://www.ebi.ac.uk/biostudies/files/{accession}/{path}` download URL. Do312 not. It works — it 302-redirects — but there is no one base tree behind it:313 `/studies/{accession}/info` advertises `/biostudies/fire/...` for `E-MTAB-*`314 and `/pub/databases/biostudies/...` for `S-BSST*`. The redirect also costs315 12.4 s against 0.3 s direct, and times out on multi-gigabyte files. This316 skill resolves `httpLink` from `/info` and keeps the old path as a fallback.317- **Gotcha 6**: If `--command metadata` works but `--command download` hangs or318 fails with a connection timeout, suspect a **firewall, not a bug**. Metadata319 comes from `www.ebi.ac.uk`; file bytes come from `ftp.ebi.ac.uk`. Corporate320 networks, VPNs and CI sandboxes routinely allow the first and block the321 second, which produces exactly this split. Both hosts must be allowlisted —322 see the allowlisting section of323 [docs/data-handling.md](../../docs/data-handling.md#allowlisting-for-the-public-archive-skills)324 — it is TCP/443 to a different host, not an FTP port, so asking an admin to325 "open FTP" will not help.326 Confirm with327 `curl -sI https://ftp.ebi.ac.uk/biostudies/ -o /dev/null -w '%{http_code}\n'`:328 `200` means reachable, `000` means blocked.329- **Gotcha 7**: Upstream's `--out` defaults were relative to the working330 directory. Here every path resolves under `--output`; a relative `--out` is331 anchored there, and only an absolute `--out` escapes. Do not reintroduce332 cwd-relative defaults.333334## Safety335336- **Local-first**: no user genetic data is ever transmitted. This skill sends a337 public accession or the search phrase you typed to `www.ebi.ac.uk` and338 receives public archive data. Nothing of yours leaves the machine, which339 satisfies ClawBio Safety Rule 1 by construction rather than by promise. See340 [docs/data-handling.md](../../docs/data-handling.md).341- **Credentials**: none. BioStudies needs no key, and the skill reads no342 credential environment variables.343- **Disclaimer**: every report carries the ClawBio medical disclaimer.344- **Overwrite**: the skill warns on stderr before overwriting an existing output345 directory.346- **Audit trail**: every run writes `reproducibility/` with the exact command,347 an environment snapshot and SHA-256 checksums.348349## Agent Boundary350351The agent dispatches and explains. The skill executes. The agent must not invent352accessions, guess at file contents it has not listed, or re-map the harmonised353columns. If a study has no per-sample structure, say so rather than354manufacturing rows.355356## Integration with Bio Orchestrator357358**Trigger conditions**: the orchestrator routes here on a BioStudies accession359(`S-BSST`, `S-BIAD`, `S-EPMC`) or an explicit mention of BioStudies or the360BioImage Archive.361362**Chaining partners**:363- `arrayexpress-fetch`: for the ArrayExpress records BioStudies hosts, when the364 MAGE-TAB design is needed.365- `ena-fetch`: when a study links out to sequencing runs.366- `article-data-fetcher`: **upstream producer.** It resolves a DOI or PMID to367 the repository accessions a paper deposited. When the user starts from a368 paper rather than an accession, run it first and hand the accessions here.369 It downloads files and writes a `manifest.json`, but it does **not**370 harmonise sample annotation into `metadata.tsv` — that is this skill's job,371 so the two chain rather than compete.372373## Maintenance374375- **Update trigger**: when an archive host changes an endpoint this skill calls.376 Not on a calendar — a fixed cadence either fires when nothing has changed or377 misses a break the week after it lands. The staleness signals below are the378 trigger.379- **How a break surfaces**: from a live call, not from CI. The demo and the tests380 run offline from committed fixtures, so they stay green after an endpoint381 changes. Treat an unexpected HTTP error or an empty result on a real accession382 as the signal, then re-check the fixtures against the live API.383- **Staleness signals**: the API moving off `/api/v1`; the PageTab schema384 changing `type == "file"`; the BioSamples characteristics endpoint moving.385- **Known debt**: the harmonisation helpers (`harmonize_row`,386 `write_metadata_tsv`, the field-key table) are duplicated across the archive387 skills rather than shared, deliberately, so each stays easy to re-sync with388 upstream. Factor them out only if upstream does.389- **Deprecation**: if BioStudies publishes an official client that covers these390 five commands, wrap it instead of the REST API.391392## Citations393394- [EMBL-EBI BioStudies](https://www.ebi.ac.uk/biostudies/); the archive and its395 REST API.396- [EBI BioSamples](https://www.ebi.ac.uk/biosamples/); sample characteristics397 used to enrich the metadata table.398- Demo fixture: [S-BSST2074](https://www.ebi.ac.uk/biostudies/studies/S-BSST2074),399 doi:10.6019/S-BSST2074, licensed CC0.400- Ported from401 [UKDRI/informatics_data_skills](https://github.com/UKDRI/informatics_data_skills)402 @ `7cc3e6e` (`biostudies/`), © 2026 UK Dementia Research Institute, MIT.