sdrf-skills

Turn Claude Code, Cursor, OpenAI Codex, Gemini CLI, or OpenCode into an expert proteomics SDRF annotator.

Pick a dataset → the agent fetches PRIDE + paper → you review a validated SDRF.

Structured skills that give AI assistants expert-level capabilities for annotating, validating, improving, and reviewing proteomics metadata in the SDRF format. Instead of guessing at ontology terms or SDRF rules, the agent follows the methodology of experienced annotators using real tools (OLS, PRIDE, PubMed). The specification data (column definitions, templates) lives in a git submodule and is read at runtime, so the skills stay current as the spec evolves.

Available skills

Four skills. Three are slash commands under /sdrf-skills:; sdrf-adversarial-review is dispatched by sdrf-annotate into a fresh context and is never typed as a command (a pipeline can also run it directly as a separate task):

Installation

Then pip install -e . from the checkout gives you the sdrf-tools command (pip install -e '.[mcp]' adds the bundled MCP server’s dependencies), and sdrf-tools doctor checks parse_sdrf, sdrf-tools, the spec submodule and techsdrf, and says what to install for anything missing.

Claude Code, in two lines — no clone needed; the marketplace install fetches the spec/ submodules with it:

/plugin marketplace add bigbio/sdrf-skills
/plugin install sdrf-skills@sdrf-skills

Then run sdrf-tools doctor; if it reports something missing, skills/sdrf-annotate/references/setup.md has the install steps for parse_sdrf and techsdrf. The skills resolve spec/, tools/ and data/ against $CLAUDE_PLUGIN_ROOT, so you can work from any directory.

From a checkout (for development, or for the other platforms below):

# 1. Clone WITH submodules (the spec data is a submodule):
git clone --recurse-submodules https://github.com/bigbio/sdrf-skills
# already cloned without them?  git submodule update --init --recursive

# 2. Install the deterministic helper tools (conda recommended — includes thermorawfileparser):
conda env create -f environment.yml && conda activate sdrf-skills
# pip alternative (thermorawfileparser not on PyPI):
#   pip install -r requirements.txt && pip install git+https://github.com/bigbio/techsdrf.git

# 3. Point the skills at this checkout (they resolve spec/, tools/ and data/ against it).
#    Run from the checkout; this writes its absolute path to your shell profile (in an image, use ENV):
echo "export SDRF_SKILLS_ROOT=\"$PWD\"" >> ~/.bashrc

Update the bundled spec any time with git submodule update --remote --recursive.

Container image. ghcr.io/bigbio/sdrf-skills holds the skills, the spec/ submodule, tools/ and data/ at /opt/sdrf-skills, with sdrf-tools, parse_sdrf, git, curl and jq on PATH. SDRF_SKILLS_ROOT and CLAUDE_PLUGIN_ROOT point at /opt/sdrf-skills. The parse_sdrf ontology cache is included, so validation works offline and as any user. The image installs the core dependencies from pyproject.toml without the [mcp] extra, and has no techsdrf. Tags: X.Y.Z, X.Y and latest for each release, main for the tip of main, and sha- for every build. To release, push a tag vX.Y.Z that matches the version in .claude-plugin/plugin.json; the workflow refuses any other tag.

docker run --rm -v "$PWD":/data ghcr.io/bigbio/sdrf-skills:main sdrf-tools doctor
docker run --rm -v "$PWD":/data ghcr.io/bigbio/sdrf-skills:main \
  parse_sdrf validate-sdrf --sdrf_file file.sdrf.tsv --template ms-proteomics --template human

A pipeline can use it as the container of an agent task (Nextflow: container 'ghcr.io/bigbio/sdrf-skills:') and load the skills from /opt/sdrf-skills/skills, or use it as a base image (FROM ghcr.io/bigbio/sdrf-skills:) and add the agent runtime. Pin the same version for the skills and the image.

Setup by AI platform

Usage

/sdrf-skills:sdrf-annotate PXD045678     → record + paper → tables → sdrf-tools build → validate → independent review
/sdrf-skills:sdrf-annotate file.sdrf.tsv → review an existing SDRF against its record and the spec
`/sdrf-skills:sdrf-annotate ` (review mode) file.sdrf.tsv → template + ontology validation
`sdrf-tools fix` (patterns: `sdrf-annotate/references/fix-patterns.md`) file.sdrf.tsv      → repair UNIMOD swaps, case, formats, artifacts (with changelog)
/sdrf-skills:sdrf-contribute PXD045678   → open a PR to bigbio/sdrf-annotated-datasets

Python tools

The repo is skills-first: new user-facing workflows go in skills/. tools/ holds deterministic helpers a skill can call (TSV parsing, OLS client, hallucination detection, quality scoring, auto-fix, cell-line enrichment, MassIVE fallback, and the review gate). Run them via the unified CLI:

sdrf-tools check  file.sdrf.tsv          # hallucinated terms / UNIMOD swaps
sdrf-tools score  file.sdrf.tsv          # quality score (0-100, 5 dimensions)
sdrf-tools fix    file.sdrf.tsv -o out.tsv
sdrf-tools verify UNIMOD:1 --label Acetyl
sdrf-tools ols "breast carcinoma" --ontology mondo  # label -> accession
sdrf-tools fetch PXD000001               # PRIDE record, raw file list, paper -> evidence/ (no MCP needed)
sdrf-tools review-gate gate              # enforce independent-review receipts
sdrf-tools schema-check PXD000001.evidence.json  # evidence manifest against its JSON Schema
sdrf-tools manifest-coverage file.sdrf.tsv file.evidence.json  # columns with values but no evidence claim
sdrf-tools doctor                        # is everything installed?
sdrf-tools search-params mqpar.xml       # mods, enzyme, tolerances from a deposited search file
sdrf-tools contract -t ms-proteomics -t human          # column contract of a template union
sdrf-tools build --samples samples.tsv --technical technical.tsv \
  --files files.json -t ms-proteomics -t human -o out.sdrf.tsv  # SDRF from a sample table, deterministically

Feeding a pipeline. quantms reads SDRF natively (nextflow run bigbio/quantms --input file.sdrf.tsv --fasta proteins.fasta). For the others, sdrf-pipelines converts: parse_sdrf convert-maxquant --sdrf file.sdrf.tsv --fastafilepath proteins.fasta, convert-openms --sdrf file.sdrf.tsv --onetable, convert-diann --sdrf file.sdrf.tsv, convert-msstats, convert-normalyzerde.

Adversarial review gate. Changed SDRFs are identified by SHA-256; a passing receipt is valid only for that exact content, and any edit makes it pending again. Changed artifacts are discovered from git (measured against the merge base), so the gate works from Claude Code, another assistant, CI, or a plain shell: python3 tools/review_gate.py gate --cwd (exit 1 = review still needed). On Claude Code a Stop hook runs the same check; the hook is a convenience, not the enforcement.

How it works

The skills/ directory is platform-agnostic markdown; each platform needs only a thin shim (.claude-plugin/, .cursor/rules/, .codex/, GEMINI.md, .opencode/) to discover and load it. The MCP tools an agent needs already exist (OLS, PRIDE, PubMed) — what was missing was the expertise: which ontology to search per column, how to read a paper for SDRF metadata, the common errors and their fixes, and what “good” annotation looks like. Skills encode that as step-by-step workflows, and the spec/ submodule keeps the column/template data current with no SKILL.md changes.

A skill’s SKILL.md is loaded whole whenever it is invoked, and it stays in the model’s context for every turn after that, so its length is a per-turn cost. The largest skill, sdrf-annotate, is therefore a short core (the workflow: operating mode, templates, the two tables, build, validate) plus references/ files — gathering the record, finding sample and technical values, the channel-map ladder, reconciliation, planning — that it tells the model to read only when that step needs them. The format rules themselves exist once, in skills/sdrf-annotate/references/format-rules.md.

Contributing

Add a skill by creating skills/your-skill/SKILL.md with YAML frontmatter, writing the workflow in markdown, and referencing spec/ for any specification data (never hardcode). For questions about the SDRF specification itself, open an issue in bigbio/proteomics-metadata-standard.

Contributors

Maintained by the BigBio team.

• Yasset Perez-Riverol (maintainer) — @ypriverol · [email protected]
• Timo Sachsenberg — @timosachsenberg
• Julianus Pfeuffer — @jpfeuffer
• Fabian Egli — @fabianegli
• Enrique Audain — @enriquea
• Husen M. Umer — @husensofteng
• Chengxin Dai — @daichengxin
• Yixuan Yang — @Yixuan39
• Selvakumar — @selva439
• Jonas Scheid — @jonasscheid
• Yufei Shen — @Shen-YuFei
• Asier Larrea Sebal — @asierlarrea · EMBL-EBI
• @2024-denglei

License

MIT