Guide · Agent skill
How to use the GSMM Model Validator agent skill (gsmm-validator)
Updated · written with AI from the project's own documentation and checked against our catalogue data
The gsmm-validator skill teaches an AI agent to run a quality-control checklist on a genome-scale metabolic model, which is a large computer map of an organism's biochemical reactions. The agent writes and runs Python code using the COBRApy library to check the model before you use it for flux simulations. This guide is for computational biologists, bioinformatics teams and students who want a repeatable validation step, and it explains how to install the skill, trigger it and read its report.
GSMM Model Validatoraiming-lab/AutoResearchClaw · MIT Download the skill Quick start
- 1Download and unzip the skill. Download the gsmm-validator ZIP from this page and unzip it. The folder should contain SKILL.md.
- 2Place the skill folder. Move the gsmm-validator folder into ~/.claude/skills/ for personal use or into .claude/skills/ in your project. In the Claude apps, you can upload the ZIP under Settings → Capabilities → Skills instead.
- 3Prepare your model file. Make sure your model is a COBRApy model saved as JSON, such as my_model.json.
- 4Ask for validation. Request validation in plain language and name your model file, for example: validate my_model.json before FBA.
- 5Let the agent run the checks. The agent loads the model and runs the six check categories in Python, including mass balance, biomass FBA and GPR checks.
- 6Read validation_report.json. Open the saved report and check the overall status, then fix every listed error before continuing.
- 7Review warnings. Investigate each warning, such as dead-end metabolites or blocked reactions, to decide whether it reflects an incomplete reconstruction.
What is an agent skill and what does this one do?
An agent skill is a folder containing a SKILL.md file that gives an AI agent instructions for a specific kind of task. When a request matches the skill, the agent follows its workflow instead of improvising.
The gsmm-validator skill covers six categories of checks: mass and charge balance, feasibility and biomass production, dead-end metabolites, stoichiometric consistency, thermodynamic loop detection, and gene-protein-reaction (GPR) rule integrity. The agent writes and runs the Python code for these checks and saves a JSON report with errors and warnings and an overall PASS or FAIL status.
- Mass/charge balance: flags non-boundary reactions with elemental imbalance as errors.
- Biomass producibility: runs an FBA optimisation and fails the model if growth is not optimal or is effectively zero.
- Dead-end metabolites: flags metabolites that are only produced or only consumed, as warnings.
- Blocked reactions: lists reactions that cannot carry flux, as warnings.
- Thermodynamic loops: compares standard and loopless FBA growth, as warnings.
- GPR rules: flags gene IDs referenced in a rule that are not in the model, as errors.
What you need before you start
The skill needs Python, the COBRApy library (imported as cobra), and a COBRApy model file in JSON format, such as my_model.json. The skill loads the model with cobra.io.load_json_model, so other file formats will not load.
The skill runs scripts, and it does not use the network.
- Python installed on the machine where the agent runs code.
- The cobra (COBRApy) library available to Python.
- A model file in JSON format, for example my_model.json.
How to install the gsmm-validator skill
Download the skill ZIP from this page and unzip it. You can install it for yourself across all projects, or for a single project.
For a personal install, unzip the folder into ~/.claude/skills/. For a project install, unzip it into the project's .claude/skills/ folder. In the Claude apps, you can instead upload the ZIP under Settings → Capabilities → Skills.
- Personal: place the gsmm-validator folder inside ~/.claude/skills/.
- Project: place the gsmm-validator folder inside .claude/skills/ in your project.
- Claude apps: upload the ZIP under Settings → Capabilities → Skills.
How to trigger the skill with natural requests
You do not need a special command. Ask in plain language about validating a metabolic model, and mention your model file. The skill's trigger keywords include metabolic, COBRApy, model validation, mass balance, charge balance, dead-end metabolites, biomass growth, thermodynamic loops and GPR.
Name the file so the agent knows what to load. The workflow begins by loading the model from a JSON file, so a clear file name helps.
- "Validate my_model.json for mass and charge balance before I run FBA."
- "Check this COBRApy model for dead-end metabolites and blocked reactions."
- "Run a thermodynamic loop check on my_model.json and tell me if growth is inflated."
- "Check the GPR rules in my model for gene IDs that aren't in the gene list."
What the report contains and how to read it
The skill writes a file named validation_report.json. It records the model ID, a timestamp, the counts of reactions, metabolites and genes, the growth rate when the solution is optimal, the overall status, and the lists of errors and warnings.
Errors must be fixed before you proceed to flux balance analysis, because they produce incorrect results. Warnings may point to an incomplete reconstruction and should be investigated case by case. A model with only warnings is acceptable for exploratory FBA but should be corrected for publication. Exchange, demand, sink and biomass reactions (EX_, DM_, SK_, BIOMASS) are excluded from mass balance errors because they intentionally have no counter-reaction.
- FAIL status: at least one ERROR was recorded.
- PASS status: no errors were recorded; warnings may still be present.
- Growth rate is null in the report if the optimisation was not optimal.
Safety notes: scripts and checks
This skill runs scripts. Review the generated Python code before you run it on important work, especially if you are working with models you did not build. The skill does not use the network.
The checks are structural heuristics. A PASS result means the model passes these structural checks, not that its biology is accurate. The skill does not verify the biological accuracy of the model, so it should not be used for clinical or safety-critical decisions.
- Runs scripts: yes. Uses network: no.
- PASS does not mean the biology is correct.
- Do not rely on it alone for clinical or safety-critical decisions.
Tips for better validation results
Give the agent a model that is already in COBRApy JSON format, because other formats are not supported. Keep the file name in your request so the agent loads the right file. Read warnings as prompts for investigation rather than automatic failures.
The skill's trigger keywords and workflow are written for metabolic modelling. The domain checks have no use outside that field, so it is not suitable for non-biology tasks.
- Convert your model to COBRApy JSON before validating.
- Fix all errors first, then review warnings one by one.
- Re-run validation after each correction to confirm the status changes.
What people use it for
- Checking a newly built genome-scale metabolic model before running flux balance analysis.
- Curating an existing model by finding unbalanced reactions and GPR rules that reference missing genes.
- Creating a repeatable validation step in a bioinformatics pipeline before flux analysis.
- Teaching students what makes a metabolic network structurally sound by reviewing the report's errors and warnings.
Frequently asked questions
Is the gsmm-validator skill free to use?
The source material does not state a price or licence terms for the skill beyond the item's listed licence, which is MIT. Check the licence file in the repository before you use or redistribute it.
What do I need to install to use gsmm-validator?
You need Python, the COBRApy library (imported as cobra), and a COBRApy model file in JSON format. The skill loads the model from JSON and will fail on other formats.
Where do I put the gsmm-validator skill folder?
For personal use, unzip it into ~/.claude/skills/. For a single project, put it in the project's .claude/skills/ folder. In the Claude apps, you can upload the ZIP under Settings → Capabilities → Skills.
Does gsmm-validator check whether my model's biology is correct?
No. The checks are structural heuristics, and the skill does not verify the biological accuracy of the model. A PASS means the model passed the structural checks only.
Why are exchange reactions not flagged for mass imbalance?
Exchange, demand, sink and biomass reactions (EX_, DM_, SK_, BIOMASS) intentionally have no counter-reaction, so the skill excludes them from mass balance errors. Other imbalanced reactions are recorded as errors.
Does the skill need an internet connection?
No. The skill is listed as not using the network, although it does run scripts, so review the generated code before running it on important work.
How does it compare with other model validation tools?
The source does not compare this skill with other tools, so it makes no claim about relative performance. Its scope is the six listed checks on COBRApy JSON models.
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
Use gsmm-validator if you build or curate genome-scale metabolic models with COBRApy and want a repeatable, documented check before flux analysis. Pick something else if your model is not in COBRApy JSON format, if you need biological accuracy verified, or if your work is outside metabolic modelling.
Download the skill