SDRF Skills para Anotação de Proteômica
bigbio/sdrf-skills
IA especialista em anotação e validação de metadados proteômicos SDRF
Ver no GitHubConjunto de skills agentic que transforma Claude, Cursor, Codex e Gemini em anotadores especialistas de metadados de proteômica no formato SDRF. Automatiza a captura, validação e revisão de datasets usando ontologias reais (OLS, PRIDE, PubMed) e mantém sincronização com a especificação através de git submodule.
Instalação
npx convez-ai bigbio/sdrf-skills1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Anotação automática de datasets proteômicos no padrão SDRF
- Validação e melhoria de metadados existentes com revisão adversarial
- Campanhas de screening de estudos proteômicos contra critérios específicos
- Contribuição de SDRFs revisados ao repositório sdrf-annotated-datasets
Veredito

Ferramenta altamente especializada e bem arquitetada para um domínio técnico específico (proteômica). A abordagem de manter a especificação atualizada via git e usar múltiplos agentes (incluindo revisão adversarial) demonstra rigor metodológico sólido, ideal para pesquisadores e curadores de dados biológicos em larga escala.
README
A tradução para o português deste README ainda está na fila.
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):
| Skill | What it does |
|---|---|
/sdrf-skills:sdrf-annotate | Everything about one SDRF. A PXD: record + paper → samples.tsv + technical.tsv → sdrf-tools build → validate → independent review, always. An existing .sdrf.tsv: review it (validate, structure, check, reconcile, cross-reference, score, then the independent review). A question: explain the format, look up a term, or plan what to capture. A short core plus references/ it reads only when a step needs them |
/sdrf-skills:sdrf-contribute | Contribute a reviewed SDRF back to sdrf-annotated-datasets via PR, behind the review gate |
/sdrf-skills:sdrf-campaign | Screen a class of studies against your criteria into a resumable TSV, then loop sdrf-annotate over the included ones, keeping only evidence-backed improvements |
sdrf-adversarial-review (dispatched, not typed) | Independent review of an SDRF in a fresh context, checked against the evidence, with a verdict bound to the file's hash |
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-<commit> 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:<version>')
and load the skills from /opt/sdrf-skills/skills, or use it as a base image
(FROM ghcr.io/bigbio/sdrf-skills:<version>) and add the agent runtime. Pin the same version for the skills and the image.
Setup by AI platform
Marketplace install (recommended)
/plugin marketplace add bigbio/sdrf-skills
/plugin install sdrf-skills@sdrf-skills
Claude Code clones the repository with its submodules, so the SDRF spec data comes with the plugin.
Skills resolve bundled paths through $CLAUDE_PLUGIN_ROOT, so any working directory is fine — your
SDRF files stay where they are. Setting SDRF_SKILLS_ROOT overrides the plugin's own copy for the
skills; the hooks and the MCP server still run from the plugin copy, so keep both at the same version.
Run sdrf-tools doctor (install notes: sdrf-annotate/references/setup.md) once for parse_sdrf/techsdrf, then
/sdrf-skills:sdrf-annotate PXD###### or /sdrf-skills:sdrf-annotate <file.sdrf.tsv> (review mode).
From a working tree (development)
cd sdrf-skills && claude --plugin-dir . # loads skills from the working tree
Bundled MCP server (optional). .mcp.json wires mcp/server.py (PRIDE + Europe PMC + OLS
helpers) and expects a virtualenv next to the plugin, so create it inside the plugin directory —
sdrf-tools doctor (install notes: sdrf-annotate/references/setup.md) prints the exact path for your install:
uv venv "$PLUGIN_ROOT/.venv" && uv pip install --python "$PLUGIN_ROOT/.venv/bin/python" -e "$PLUGIN_ROOT[mcp]"
Without it the server simply fails to connect; the skills fall back to their other sources. A plugin upgrade replaces the plugin directory, so re-create the venv after upgrading.
Ensure .cursor/rules/sdrf-skills.mdc is in your project; then ask "Follow the sdrf setup workflow" (Cursor does not run Claude Code's SessionStart hook).
- Codex — follow
.codex/INSTALL.mdto symlinkskills/andspec/into your Codex skills path. - Gemini CLI — auto-loads
GEMINI.mdfrom the repo root. - OpenCode — follow
.opencode/AGENTS.mdto wire the skills in.
For full annotation, configure the OLS, PRIDE, PubMed, and bioRxiv MCP servers, and validate with parse_sdrf validate-sdrf.
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 <file.sdrf.tsv>` (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 <repo-root> (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 · ypriverol@gmail.com
- 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