Guide · Agent skill
How to use the matchms agent skill for MS/MS spectral matching
Updated · written with AI from the project's own documentation and checked against our catalogue data
The matchms agent skill is a set of instructions and reference notes that teaches an AI coding agent to use the matchms Python library for tandem mass spectrometry (MS/MS) work. It covers loading spectra files, cleaning them, and scoring how similar unknown spectra are to reference spectra. This guide explains what the skill does, how to install it, how to ask for its help, and what to watch for.
Mass Spectrometry Matching with matchmsK-Dense-AI/scientific-agent-skills · MIT Download the skill Quick start
- 1Download and unzip. Download the ZIP from this page and unzip it so that a matchms folder containing SKILL.md exists.
- 2Place the skill. Move the matchms folder to ~/.claude/skills/ for personal use or to .claude/skills/ in your project. In the Claude apps, upload the ZIP under Settings → Capabilities → Skills instead.
- 3Install matchms. Confirm your Python and uv are available, then run uv pip install "matchms==0.33.1" in your environment.
- 4Make a natural request. Ask for the task in plain words, naming your files (MGF, MSP or mzML) and the scoring you want.
- 5Check the report. Review the scoring settings, tolerance units, matched peak counts and candidate metadata in the output before you use any result.
What does the matchms skill make the agent do?
An agent skill is a folder with a SKILL.md file that an AI agent reads when a task matches the skill's description. Once the matchms skill is loaded, the agent knows how to use the matchms Python package to import MS/MS data, harmonise metadata, filter peaks, compare spectra and search a library.
The skill also tells the agent to use current matchms function names, to report the scoring settings it used, and to avoid mistakes common in older tutorials. It states that similarity scores are evidence rather than proof of a compound's identity, and that LC-MS feature detection or proteomics work should go to the pyopenms skill instead.
- Read MGF, MSP, mzML, mzXML, JSON and metabolomics-USI inputs
- Clean metadata and filter peaks in the same way for queries and references
- Score with cosine, modified cosine, neutral-loss, entropy and related methods
- Produce score matrices, top-hit lists and molecular-similarity networks
How do I install the matchms skill?
Download the ZIP archive from this page and unzip it. The unzipped matchms folder, which contains SKILL.md, goes into one of two places. For a skill available in all your projects, use ~/.claude/skills/. For a skill that only one project should use, put it in that project's .claude/skills/ folder.
In the Claude apps you can instead upload the ZIP under Settings → Capabilities → Skills.
- Personal install: ~/.claude/skills/matchms/
- Project install: .claude/skills/matchms/ inside your project folder
- Claude apps: Settings → Capabilities → Skills, then upload the ZIP
What do I need installed before the skill works?
The skill targets a pinned matchms release, which the skill's own install step installs with uv. The skill lists a supported Python range, so check that your Python falls within it. matchms installs RDKit as a regular dependency, so you do not need a separate chemistry extra.
Local file workflows need no credentials. Network access is needed only for loading spectra from metabolomics-USI identifiers.
- Python within the range the skill lists
- uv package manager
- The pinned matchms release, installed with: uv pip install "matchms==0.33.1"
- Check the install with: uv run python -c "import matchms; print(matchms.__version__)"
uv pip install "matchms==0.33.1"How do I trigger the skill with natural requests?
You do not need to name the skill. Describe the task in plain words that mention spectra, files or scoring, and the agent should load the matchms skill when the request matches its description. Naming the file types and the scoring method helps.
Good requests say what you have and what you want back. Mention the file formats, whether you need a library search or a pairwise score, and any tolerance you care about. The agent should report the scoring settings it used with the results.
- Load library.msp and queries.mgf, clean both with the same peak filters, and rank the top five library matches for each query using modified cosine.
- Convert this mzML export to MGF after removing spectra with no precursor m/z.
- Build a score matrix for these 200 query spectra against my reference library and tell me how many pairs it will compute first.
- Find LC-MS features in this run and align them across samples. (This should be routed to pyopenms, not matchms.)
What does the skill's library search script do?
The skill includes scripts/library_search.py. Use it as a starting point for a library search. Read it before running it on your own data, so you know which files it reads and writes.
The skill's quick-start example follows the same pattern: load and clean the library and queries, score with a modified cosine metric at a 0.02 m/z tolerance, and print the top hits with their scores and matched peak counts. The tolerance is an absolute window in Da, not ppm.
- Keep the tolerance and its units in your report
- Use a precursor filter with a known ion mode and adduct where possible
- Check top hits with mirror plots and precursor agreement before trusting them
ranked = scores.scores_by_query(query, name=score_name, sort=True)What safety points should I know?
The skill runs scripts and uses the network, so review it before use. Its scripts and examples run on your machine through the agent's shell tool. Network access is needed only for metabolomics-USI loading.
Never load pickle files from an untrusted source, because unpickling can execute code. Do not treat a similarity score as a validated identification, and do not use the skill for regulatory or clinical decisions. Vendor raw files must be exported to mzML or mzXML first.
- Review scripts/library_search.py and any other scripts before running them
- Only load .pickle files you created or trust
- Scores are evidence, not proof of compound identity
What people use it for
- Ranking library matches for MS/MS query spectra from a metabolomics run stored as MGF or MSP files
- Harmonising metadata and filtering peaks across several spectral libraries before comparison
- Building a score matrix and molecular-similarity network for a chemistry or teaching dataset
- Learning how cosine and modified cosine scoring behave on a small set of spectra
Frequently asked questions
Is the matchms agent skill free, and what is its licence?
The directory lists the skill's repository under the MIT licence. The SKILL.md front matter declares Apache-2.0, so check the LICENSE file in the downloaded repository to confirm which terms apply before reuse.
Do I need an API key or account to use it?
No credentials are needed for local file workflows. Network access is only needed when loading spectra through metabolomics-USI identifiers.
What is the difference between matchms and pyopenms?
matchms imports, cleans and compares MS/MS spectra, including library search and similarity scores. The skill says LC-MS feature detection, chromatographic alignment, peptide identification and proteomics should go to pyopenms.
Why does the agent not find my vendor raw file?
matchms does not convert vendor raw files. Export the data to mzML or mzXML first, then load those files.
Can I use matchms scores to identify a compound for a report or a clinical decision?
No. The skill says similarity is evidence, not proof of identity, and it is not a validated identification protocol. Use it to shortlist candidates, then confirm with orthogonal evidence.
What should I do if the install fails or the agent ignores the skill?
Check that your Python version is in the range the skill lists and that uv is installed. Confirm the folder with SKILL.md sits directly inside ~/.claude/skills/ or .claude/skills/, then describe the task with file types and scoring method named.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
This skill suits metabolomics and chemistry researchers running MS/MS library searches, developers building spectral similarity pipelines in Python, and students learning how cosine scoring works. It is not suited to regulatory or clinical identification, LC-MS feature detection or proteomics, which the skill sends to pyopenms.
Download the skill