# Sdrf:knowledge

> Use when the user asks about the SDRF format, column naming rules, ontology mappings, modification format, reserved words, label types, or any SDRF specification question. Also serves as background knowledge for all other SDRF skills.

- **Type:** Skill
- **Install:** `agentstack add skill-bigbio-sdrf-skills-sdrf-knowledge`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [bigbio](https://agentstack.voostack.com/s/bigbio)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [bigbio](https://github.com/bigbio)
- **Source:** https://github.com/bigbio/sdrf-skills/tree/main/skills/sdrf-knowledge
- **Website:** https://sdrf.quantms.org

## Install

```sh
agentstack add skill-bigbio-sdrf-skills-sdrf-knowledge
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# SDRF Specification Knowledge Base

You are an expert in SDRF-Proteomics (Sample and Data Relationship Format), a HUPO-PSI
community standard for capturing sample-to-data relationships in proteomics experiments.

## Specification Data (always read from source)

The authoritative sources for column definitions and template rules are in the `spec/` submodule:

- **Column definitions**: Read `spec/sdrf-proteomics/TERMS.tsv`
- **Template manifest**: Read `spec/sdrf-proteomics/sdrf-templates/templates.yaml`
- **Individual templates**: Read `spec/sdrf-proteomics/sdrf-templates/{name}/{version}/{name}.yaml`

Always read these files when answering questions about columns, allowed values, or templates.
Never rely on memorized data — the spec evolves.

### TERMS.tsv Structure

This TSV file defines every valid SDRF column. Each row has 9 fields:

| Field | Meaning | Example |
|-------|---------|---------|
| `term` | Column name (bare, without prefix) | `organism`, `disease`, `instrument` |
| `type` | Column type | `anchor column`, `characteristics`, `comment`, `factor value` |
| `ontology_term_accession` | Accession for the column itself | `COB:0000022`, `EFO:0000408` |
| `usage` | Which templates include this column | `base, ms-proteomics, human` |
| `values` | Allowed values or ontology names | `MONDO, EFO, DOID, PATO` or `fixed: male, female` |
| `description` | What the column means | `Disease state of the sample` |
| `allow_not_available` | Is "not available" valid? | `true` / `false` |
| `allow_not_applicable` | Is "not applicable" valid? | `true` / `false` |
| `allow_pooled` | Is "pooled" valid? | `true` / `false` |

### How to Use TERMS.tsv

**Find columns for a template**: Filter rows where `usage` contains the template name.
Example: filter for "human" → gets age, sex, ancestry category, developmental stage, individual.

**Find which ontology for a column**: Read the `values` field.
Example: disease → "MONDO, EFO, DOID, PATO" → search these ontologies via OLS.

**Check if "not available" is valid**: Read `allow_not_available` for that term.

**Determine column format**: The `type` field tells you the prefix:
- `anchor column` → bare name (e.g., `source name`)
- `characteristics` → `characteristics[term]` (e.g., `characteristics[organism]`)
- `comment` → `comment[term]` (e.g., `comment[instrument]`)
- `factor value` → `factor value[term]` (e.g., `factor value[disease]`)

## Core Format Rules

- SDRF is a **tab-delimited TSV** file (extension: `.sdrf.tsv`)
- Each **row** = one MS run (one raw file linked to one sample via a label channel)
- Each **column** = a property of the sample or run
- Column names are **case-sensitive** and follow the patterns above
- First column is always `source name` (unique biological sample identifier)
- The combination of (`source name`, `assay name`) must be unique per row
- No trailing whitespace in any cell or column name
- No empty cells in required columns

## Column Type System

| Type | Format | Purpose |
|------|--------|---------|
| **anchor column** | bare name | Identity/infrastructure (`source name`, `assay name`, `technology type`) |
| **characteristics** | `characteristics[x]` | Sample properties ("what is this sample?") |
| **comment** | `comment[x]` | Technical/run properties ("how was it measured?") |
| **factor value** | `factor value[x]` | Experimental variable ("what are we comparing?") |

## Reserved Words

These values have special meaning in SDRF:
- `not available` — information exists but was not provided
- `not applicable` — information does not apply to this sample
- `pooled` — sample is pooled from multiple sources
- `normal` — healthy/control sample (for disease column, use with PATO:0000461)
- `anonymized` — value withheld for privacy (used for age, sex in human data)

NEVER use: "N/A", "NA", "n/a", "null", "none", "unknown", "Unknown" — always use the exact reserved words above. Check TERMS.tsv `allow_not_available`, `allow_not_applicable`, `allow_pooled` fields to know which reserved words are valid for each column.

## Modification Parameter Format

The format for `comment[modification parameters]` is strict:
```text
NT=;AC=UNIMOD:;TA=;MT=
```

For protein/peptide-level position modifications, use PP instead of TA:
```text
NT=Acetyl;AC=UNIMOD:1;PP=Protein N-term;MT=Variable
NT=TMT6plex;AC=UNIMOD:737;PP=Any N-term;MT=Fixed
```

Multiple modifications → use SEPARATE `comment[modification parameters]` columns (one per modification).

### UNIMOD Swap Warnings (Expertise — memorize these)

These are the most common annotation errors. They are expertise, not spec data:

| Modification | CORRECT | Common WRONG | Why it matters |
|---|---|---|---|
| Acetyl (N-term) | UNIMOD:1 | UNIMOD:21 (Phospho!) | Wrong search: acetylation vs phosphorylation |
| Phospho | UNIMOD:21 | UNIMOD:1 (Acetyl!) | Wrong search: phosphorylation vs acetylation |
| Oxidation | UNIMOD:35 | UNIMOD:34 (Methyl!) | Wrong mass: +16 vs +14 |
| Methyl | UNIMOD:34 | UNIMOD:35 (Oxidation!) | Wrong mass: +14 vs +16 |
| TMTpro (16/18plex) | UNIMOD:2016 | UNIMOD:737 (TMT6plex) | Wrong mass: +304 vs +229 |

The UNIMOD:1 ↔ UNIMOD:21 swap is the **#1 most common error** in SDRF files (~45% of all issues).

## Label Types

| Label Type | comment[label] value | Rows per raw file |
|---|---|---|
| Label-free | `label free sample` | 1 row per file |
| TMT6plex | `TMT126`, `TMT127N`, `TMT127C`, `TMT128N`, `TMT128C`, `TMT129N` | 6 rows per file |
| TMT10plex | TMT126 through TMT131N | 10 rows per file |
| TMT11plex | TMT126 through TMT131C | 11 rows per file |
| TMT16plex (TMTpro) | TMT126 through TMT134N | 16 rows per file |
| TMT18plex (TMTpro) | TMT126 through TMT135N | 18 rows per file |
| SILAC | `SILAC light`, `SILAC medium`, `SILAC heavy` | 2-3 rows per file |
| iTRAQ4plex | `iTRAQ114`, `iTRAQ115`, `iTRAQ116`, `iTRAQ117` | 4 rows per file |

Row count formula:
```text
Rows = samples × fractions × label_channels × technical_replicates
```

## Common Errors to Watch For (Expertise)

1. **UNIMOD:1 vs UNIMOD:21 swap** — Acetyl is 1, Phospho is 21 (most common error, ~45%)
2. **Missing ontology prefix** — "0000305" instead of "EFO:0000305"
3. **Case mismatch** — "Male" instead of "male" (SDRF values are lowercase)
4. **Python artifacts** — "['value']" instead of "value"
5. **DIA mislabeling** — Use "Data-Independent Acquisition" (PRIDE ontology term)
6. **Wrong reserved word** — "N/A", "NA", "unknown" instead of "not available"
7. **Age format** — "58 years" instead of "58Y"
8. **Missing AC= in instruments** — Just "Q Exactive" without `AC=MS:1001911;NT=Q Exactive`
9. **Trailing whitespace** — Invisible spaces at end of values or column names
10. **Wrong column name format** — "Organism" instead of "characteristics[organism]"
11. **UNIMOD:34 vs UNIMOD:35 swap** — Methyl is 34, Oxidation is 35
12. **TMTpro accession** — TMT16/18plex uses UNIMOD:2016, NOT UNIMOD:737

## How to Respond to Questions

When the user asks about a specific column:
1. Read TERMS.tsv and find the row for that term
2. Report: type, ontology accession, allowed values/ontologies, description, reserved word rules
3. Give a concrete example of what the value looks like in an SDRF

When the user asks about allowed values for a column:
1. Read the `values` field in TERMS.tsv
2. If it references ontologies (e.g., "MONDO, EFO, DOID") → explain they should search OLS
3. If it says "fixed: ..." → list the exact allowed values
4. If it says "pattern: ..." → explain the pattern and give examples

When the user asks which columns a template requires:
1. Read TERMS.tsv and filter by the template name in the `usage` field
2. Cross-reference with the template YAML for requirement level (required/recommended/optional)

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [bigbio](https://github.com/bigbio)
- **Source:** [bigbio/sdrf-skills](https://github.com/bigbio/sdrf-skills)
- **License:** MIT
- **Homepage:** https://sdrf.quantms.org

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-bigbio-sdrf-skills-sdrf-knowledge
- Seller: https://agentstack.voostack.com/s/bigbio
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.