Skip to main content
skill CX Codex

bioproject-search — Claude Code skill: what it does, how to install

bioproject-search is a Claude Code skill that retrieves NCBI BioProject metadata via the official E-utilities API. It exports project titles, organisms, and release dates to CSV or JSON.

MIT ★ 77 updated 2026-10-27

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add ssinder/bioinformatics-agent-skills --skill bioproject-search -a claude-code
Open on GitHub

What bioproject-search does

The scripts/search_bioprojects.py script queries the official NCBI E-utilities API to retrieve project records instead of scraping web pages. Given PRJNA or PRJEB accessions, it uses esearch to resolve internal UIDs, then queries both esummary and efetch. Combining these endpoints captures organism taxids, submitters, release dates, and full descriptions, normalising all date formats to YYYY-MM-DD.

Output records are written to bioproject_data.csv and bioproject_data.json. The --filter argument keeps records matching specific keywords, while --drop-noisy strips navigation boilerplate from descriptions.

Running the script requires Python 3.9+ and the requests library. NCBI usage policy requires a contact email provided via --email or the BIOPIPE_EMAIL environment variable. An optional API key raises the request rate limit from 3 to 10 requests per second.

What it helps with

  • retrieve BioProject metadata using PRJNA or PRJEB accession numbers
  • filter sequencing projects by keywords in titles or descriptions
  • export organism names, submitters, and release dates to CSV or JSON
  • compile project catalogues for scientific papers and datasets

Example prompts for the agent

  • Fetch BioProject metadata for PRJNA172563 and PRJNA212358 into the results directory
  • Process accession IDs from prj_ids.txt and filter projects mentioning CRISPR

How to install bioproject-search

1Skills CLI (Vercel)

npx skills add ssinder/bioinformatics-agent-skills --skill bioproject-search -a claude-code

2Manually: put the files in place

~/.claude/skills/bioproject-search/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/bioproject-search/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about bioproject-search

How to install bioproject-search in Claude Code?

Run the command npx skills add ssinder/bioinformatics-agent-skills --skill bioproject-search -a claude-code.

What does bioproject-search do?

It retrieves BioProject records in batches via the NCBI E-utilities API using project accession IDs. The tool merges details from esummary and efetch, exporting structured metadata to CSV and JSON.

What is required to run bioproject-search?

You need Python 3.9+, the requests library, and a contact email set in BIOPIPE_EMAIL or passed via --email. An NCBI API key is optional to increase rate limits.

Source text

SKILL.md · MIT
---
name: bioproject-search
description: >-
  Retrieves NCBI BioProject metadata — title, description, organism, submitter and
  release dates — for a batch of BioProject accessions, using the official NCBI
  E-utilities API rather than scraping the BioProject web pages. Supports
  keyword filtering over titles and descriptions, CSV/JSON export, and requires
  a contact email as the NCBI usage policy mandates. This skill should be used when
  looking up what a BioProject or PRJNA/PRD accession contains, retrieving
  sequencing project descriptions, or collecting BioProject metadata in bulk is
  requested.
license: MIT
compatibility: Python 3.9+; needs requests for network access; standard library only otherwise
metadata:
  version: "1.0"
  last-reviewed: "2026-10-26"
  skill-author: sinder
---

# BioProject Metadata Retrieval

## Overview

This skill retrieves NCBI BioProject records through the official
**E-utilities** API and exports them as CSV/JSON.

The alternative — scraping the BioProject web pages — is fragile in a way that
is easy to underestimate. Page-scraping code ends up with selectors like
`div:nth-child(5)` that encode the *current* number of wrapper elements in
the page. When NCBI adjusts its layout, the selector silently stops matching
and the description column comes back empty, which is indistinguishable from
"this project has no description".

E-utilities returns structured XML with stable field names. The same query
that works today keeps working after a website redesign.

The skill also follows NCBI's usage policy properly: a **contact email is
required** (via `--email` or the `BIOPIPE_EMAIL` environment variable).
NCBI uses the email to identify callers and to contact them when problems
occur; fabricating placeholder addresses defeats that purpose and can get
your IP rate-limited.

## When to Use This Skill

- Finding out what a specific BioProject / PRJNA / PRJEB accession contains
- Collecting titles, descriptions and organisms for a list of projects
- Screening projects by keyword before deciding which ones to download
- Building a project catalogue for a methods or dataset section
- Looking up submitter and release dates for citation purposes

## Quick Start

```bash
export PYTHONPATH="$PWD/packages"
export BIOPIPE_EMAIL="[email protected]"

# 从文件读取 accession
python scripts/search_bioprojects.py --ids prj_ids.txt --output-dir results/

# 直接给 accession
python scripts/search_bioprojects.py --ids PRJNA172563 PRJNA212358 --output-dir results/

# 只保留描述里提到 CRISPR 的项目
python scripts/search_bioprojects.py --ids prj_ids.txt --output-dir results/ --filter CRISPR

# 有 NCBI API key 时可提高限速(10 req/s)
python scripts/search_bioprojects.py --ids prj_ids.txt --output-dir results/ --api-key $NCBI_API_KEY
```

## Workflow

1. **Collect accessions** — `--ids` accepts accession strings or paths to
   text files (one per line, `#` for comments). Entries that do not look like
   BioProject accessions are reported and skipped rather than silently
   dropped.
2. **Resolve to UIDs** — `esearch` translates accessions into NCBI's internal
   UIDs. The query uses the `[Project Accession]` field qualifier, without
   which an accession string can match unrelated records.
3. **Fetch details from two endpoints** — `esummary` and `efetch` are called
   together and their results merged. This is not redundancy: **no single
   endpoint carries every field**. `esummary` is the only source for the
   structured organism name, taxonomy ID, project type and submitter
   organisation; `efetch` is the only source for the release date and the
   full description text. Calling only one of them silently drops about
   half the metadata without raising an error.
4. **Parse** — the merged records carry accession, title, name, description,
   organism, taxonomy ID, project type, submitter, registration date, release
   date and last-update date. All three NCBI date formats are normalised to
   `YYYY-MM-DD`.
5. **Filter (optional)** — `--filter` keeps records whose title, name or
   description contains the keyword (case-insensitive). `--drop-noisy`
   removes descriptions that look like page navigation rather than content.
6. **Export** — `bioproject_data.csv` and `bioproject_data.json` are written
   to the output directory.

## Parameters

| Parameter | Default | Description |
|---|---|---|
| `--ids` | required | Accession list or path(s) to text files containing accessions |
| `--output-dir` | `bioproject_results` | Output directory for the CSV/JSON results |
| `--email` | `$BIOPIPE_EMAIL` | Contact email (required by NCBI's usage policy) |
| `--api-key` | `$BIOPIPE_API_KEY` | NCBI API key; raises the rate limit from 3 to 10 req/s |
| `--filter` | none | Keep only records whose title/name/description contains this keyword |
| `--drop-noisy` | off | Drop descriptions that look like page navigation |
| `--timeout` | `60` | Per-request timeout in seconds |

## Outputs

| File | Content |
|---|---|
| `bioproject_data.csv` | One row per project: accession, title, name, description, organism, taxid, study type, submitter, registration date, release date, last-update date, UID |
| `bioproject_data.json` | Same content as nested JSON |

## Validation

- **A description should be a paragraph, not a sentence fragment.** Empty or
  one-word descriptions usually mean the project record genuinely lacks one —
  some submitters provide only a title. Cross-check with the linked BioSample
  or SRA records.
- **The accession prefix indicates the archive** — `PRJNA` (NCBI), `PRJEB`
  (EBI/ENA), `PRJDB` (DDBJ). A project submitted to ENA may be reachable
  through ENA's own portal rather than NCBI's.
- **Organism names come from the submitter** and are not normalised. A
  project may list several organisms, in which case the field contains a
  comma-separated list rather than a single taxon — do not treat it as a
  single taxid. The `organism` field always holds a *name*; the numeric
  identifier belongs in `taxid`.
- **An empty date means "not recorded", not "zero".** NCBI uses the
  placeholder `1/01/01 00:00` for "date unknown"; it is deliberately not
  converted into a real date, so the field stays empty. Do not interpret an
  empty `registration_date` as a bug — check whether the project is
  dbGaP-backed (those records have their submitter details stripped).
- **Release date may be in the future or absent** for embargoed projects.
  An embargoed project returns its metadata to authorised submitters only;
  the public record will be sparse.
- **Search term semantics** — `[Project Accession]` matches the accession
  field exactly. To search descriptions by keyword across *all* projects
  rather than a known list, use NCBI Entrez directly with
  `bioproject[Filter]` and a keyword term.
- **Search term semantics** — `[Project Accession]` matches the accession
  field exactly. To search descriptions by keyword across *all* projects
  rather than a known list, use NCBI Entrez directly with
  `bioproject[Filter]` and a keyword term.
## References

- `references/methodology.md` — E-utilities protocol, field semantics, rate limits
- `references/troubleshooting.md` — common failures and how to diagnose them
- NCBI E-utilities documentation: <https://www.ncbi.nlm.nih.gov/books/NBK25501/>
- BioProject: <https://www.ncbi.nlm.nih.gov/bioproject/>

© ssinder · MIT · ssinder/bioinformatics-agent-skills

Similar skills

All skills for Science and research →

From the same set10

The whole set →
protein-structure protein-structure is a Claude Code skill that analyzes protein structures in PDB files. It activates for requests about secondary structure, radius of gyration, or PDB parsing. CX Codex +1 ★ 77repo stars protein-interactions protein-interactions is a Claude Code skill that extracts residue-level contacts from PLIP XML reports and AlphaFold archives. Runs on interaction profiling, hotspot ranking and network graphing tasks. CX Codex +1 ★ 77repo stars ml-peptide-generation ml-peptide-generation is a Claude Code skill that generates peptide candidates aimed at binding a target protein. It ranks sequences by pseudo-perplexity and compares peptide lengths and top-k settings. CX Codex +1 ★ 77repo stars ena-download ena-download is a Claude Code skill that downloads sequencing FASTQ files and run metadata via the ENA Portal API. Runs when fetching raw sequencing reads by SRA, ERR, or DRR accessions. CX Codex +1 ★ 77repo stars protein-docking-lightdock protein-docking-lightdock is a Claude Code skill that runs local protein docking via LightDock and saves best complexes as PDB files. It evaluates receptor-ligand grids and ranks results by DFIRE scores. CX Codex +1 ★ 77repo stars alphafold-db alphafold-db is a Claude Code skill that fetches predicted protein structures and confidence metrics from AlphaFold DB. It runs for requests to retrieve models by UniProt accession or screen them by pLDDT. CX Codex +1 ★ 77repo stars bio-database-fetch bio-database-fetch is a Claude Code skill that retrieves chemical properties from PubChem and taxonomic lineages from NCBI. It queries official REST endpoints in batches of 100 IDs. CX Codex +1 ★ 77repo stars protein-docking-hdock protein-docking-hdock is a Claude Code skill that sends protein docking jobs to HDOCK and collects scores and complex models. It activates for structure-prediction requests or result retrieval. CX Codex +1 ★ 77repo stars

Project sponsors

Companies that keep this analytics open