janussonjanusson/MSMCP/skills/instrument-class-defaults/SKILL.md

instrument-class-defaults

Skill1 starsChanged 24 days agoMITView on GitHub

Where msmcp keeps experimental thresholds, how instrument classes carry their own defaults and provenance, and why literals must not creep back in.

In this repository6 other files it gives its agents.
- AGENTS.mdAGENTS.md
- add-mcp-toolSkill
- data-referencesSkill
- ms-data-ingestionSkill
- quality-gateSkill
- security-boundarySkill

The file

We split this skill into the rules it gives an agent

6 rules. About 0 are common, 1 is distinctive, and 5 are very specific to this project.

≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
5
Very specific
Tied to their project's names, files or tools. Probably skip.

Common
Distinctive
Very specific

Very specific:
Use this whenever a change touches an experimental threshold (a tolerance, an SNR band, an FDR gate) or the provenance of one.
line 10
Distinctive:
Never reintroduce a threshold literal: Read it from the profile.
line 54
Very specific:
Add or edit the profile in _PROFILES with a provenance string that says where the number comes from.
line 65
Very specific:
Keep generic equal to the v1.0 values unless a change is deliberate and called out.
line 67
Very specific:
If a tool consumes the new constant, thread it through so it reaches the report or Provenance.parameters.
line 69
Very specific:
Add tests in tests/test_instruments.py, and check any tool that reports the value.
line 71

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.

Files

SKILL.md

Instrument-class defaults

Use this whenever a change touches an experimental threshold (a tolerance, an SNR band, an FDR gate) or the provenance of one. All such constants live in one module: src/msmcp/instruments.py.

Why it exists

An audit found the thresholds that encode the experimental question were module-level literals: a 5.0 ppm precursor gate, a 0.02 Da peak-match window, a 0.02 Da diagnostic-ion window, SNR cut-offs of 5 and 20, and an FDR threshold / small-library floor of 0.05 / 2000. The consequences were that an analysis could not be re-run under different instrument assumptions without editing source, and the value actually used was invisible in the result it produced.

instruments.py is the single home for those constants.

The model

InstrumentClass is Literal["generic", "orbitrap", "tof", "ion_trap", "triple_quad"].
InstrumentProfile holds one class's documented defaults plus a provenance string stating the basis for every number.
Tolerance pairs a value with its unit ("ppm" or "Da"), because a ppm window is meaningless on a unit-resolution instrument.
get_profile(instrument_class) resolves a name; None yields the default class. An unknown name raises rather than falling back, so a misspelled class cannot silently change an analysis.

Per-class defaults

Class	Precursor	MS2 window	Diagnostic-ion window
generic	5.0 ppm	0.02 Da	0.02 Da
orbitrap	5.0 ppm	0.01 Da	0.01 Da
tof	15.0 ppm	0.05 Da	0.05 Da
ion_trap	0.5 Da	0.5 Da	0.5 Da
triple_quad	0.7 Da	0.7 Da	0.7 Da

SNR bands (5 / 20) and the FDR threshold / small-library floor (0.05 / 2000) are shared across classes today: they are properties of the reporting bands and the statistics, not of the mass analyser. generic reproduces MSMCP's v1.0 values exactly, so existing analyses stay reproducible.

The rule

Never reintroduce a threshold literal. Read it from the profile.
Values travel into the result that used them. String-returning tools state the value and the class in the report body; search_library records the whole profile in Provenance.parameters.
These are documented conventions, not measured acquisition parameters. MSMCP does not yet parse instrument model, resolution, or calibration from a file. State the assumption a result was produced under rather than hiding a bare number.

Adding a class or a constant

Add or edit the profile in _PROFILES with a provenance string that says where the number comes from.
Keep generic equal to the v1.0 values unless a change is deliberate and called out.
If a tool consumes the new constant, thread it through so it reaches the report or Provenance.parameters.
Add tests in tests/test_instruments.py, and check any tool that reports the value.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

It worked
Partly
It didn't

What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free