How to use the pyOpenMS mass spectrometry agent skill

What the skill makes the agent do

Mass spectrometry instruments produce large raw files, and turning them into usable results needs specialized software. With this skill installed, the agent knows how to use pyOpenMS and a set of scripts to find and align signal peaks across samples, build quantification tables, annotate metabolites by accurate mass and post-process peptide identifications.

The skill tells the agent to run a bundled script when one fits the task and to write new Python only when no script does. Each script is a parameterized command-line tool that handles loading, processing and export.

• detect_features_metabo.py: untargeted metabolomics feature detection on one sample
• detect_features_centroided.py: peptide feature detection on centroided data
• align_link_quantify.py: multi-sample pipeline from feature detection to a quantification matrix CSV
• consensus_to_matrix.py: converts a consensusXML file into a wide intensity matrix, with optional median or quantile normalization
• detect_adducts.py: groups adducts and charge variants of the same neutral mass
• accurate_mass_search.py: annotates features against local formula or structure TSV files by accurate mass
• convert_format.py: converts between file formats

Install the skill from the ZIP or the Claude apps

Download the skill ZIP from this page and unzip it. To make the skill available to every project on your machine, place the unzipped folder in ~/.claude/skills/. To limit it to one project, place it in that project's .claude/skills/ folder.

If you use the Claude apps instead, open Settings, go to Capabilities, then Skills, and upload the skill there.

• Personal: ~/.claude/skills/
• Single project: .claude/skills/ inside the project folder
• Claude apps: Settings → Capabilities → Skills

Set up the Python environment the scripts need

The scripts need CPython 3.11 or newer, pyOpenMS 3.6.0, pandas, NumPy and Matplotlib. The skill's own example creates a virtual environment with uv and installs the packages from the skill directory. Run these commands in a terminal, then activate the environment before running any script.

Verify the install by importing pyOpenMS and printing its version. The skill notes that the bundled binary prints a one-line memory-status notice on import, which is harmless.

Trigger the skill with natural requests

You do not need to name the skill or any script. Describe the analysis you want and mention your file types. The agent will pick the skill when the request matches its description, which covers feature detection, peptide or protein identification, label-free quantification, adduct annotation and LC-MS/MS pipelines.

If you want simple spectral similarity or small-molecule library matching, ask for matchms instead. The skill itself points to matchms for that work.

• Find features in sample.mzML and give me a CSV with retention time and m/z for each.
• Align these three mzML files, link the features and build a quantification matrix normalized by median.
• Group the adducts in my feature table that share the same neutral mass.
• Annotate my features by accurate mass against this local formula TSV.
• Which scripts do I need for an untargeted metabolomics run on centroided MS1 data?

Run the bundled scripts yourself

Each script accepts --help, which lists its options. Input formats differ between scripts, so check the help text before you start. Run commands from the skill directory with the environment active.

The examples below are taken from the skill. Start with one sample, then move to a multi-sample study once the single-sample output looks right.

Know the limits and safety notes

The skill runs Python scripts on your machine, so review scripts before running them on sensitive data. It does not use the network: the bundled scripts work on local files and do not fetch vendor data or databases. Identification workflows also need search-engine executables, which are a separate install.

Native tests use tiny synthetic files. The skill states that instrument-specific detection and search performance is not validated. Its outputs should not be used for clinical or regulatory decisions. When reporting identification results, state the FDR unit, decoy strategy and threshold.

• Runs scripts: yes
• Uses network: no
• Search-engine executables are required only for certain identification workflows
• Peptide detection uses an absolute m/z tolerance set with --mz-tol-da, not ppm

Tips for reliable results

Check the spectrum type before detection. The bundled detectors need centroided MS1 data and reject profile data. A sorted spectrum is not necessarily centroided, so confirm the type rather than assuming it.

Record units. Retention times and chromatogram times are in seconds, m/z is in Th and neutral mass is in Da. Keep the same convention in your notes and tables.

• Use --help on any script before you change defaults.
• Start with one file, then run the multi-sample pipeline.
• Keep your own record of tolerances, normalization and the software version used.