# math-modeling-skill runs one contest problem through three phases and five gates

> An agent skill for CUMCM, MCM and ICM teams that splits a dated contest problem into three gated phases, five read-only checks and a Word file by default. The gates are the interesting part, and so is the squeeze between nine candidate figures and the eight a finished paper needs.

**XiaoMaColtAI/math-modeling-skill** — A math-modeling skill for competitions like CUMCM and MCM/ICM: a three-stage workflow covering modeling analysis, Python/MATLAB coding, and DOCX paper generation. Includes a rich algorithm library (optimization, forecasting, evaluation, graph theory, machine learning, etc.), role guidance docs, paper templates and utility scripts.

- Repository: https://github.com/XiaoMaColtAI/math-modeling-skill
- Website: https://mms.weseeworld.cn
- Stars: 1,888 · Forks: 99
- Language: Python
- License: not declared
- Published: 2026-10-14 · Updated: 2026-10-14 · Language: en
- Canonical page: https://hysenlabs.com/projects/xiaomacoltai-math-modeling-skill

## One problem, three phases and five blocking checks

Competition teams hit a scheduling problem before they hit a mathematics problem: a model must be chosen, defended in code, then written up before the clock runs out, and every stage exposes mistakes the previous stage hid. math-modeling-skill answers that by dividing one submission into three phases with fixed deliverables and a gate in front of each. Phase 1, the modeller, reads the statement, inspects the attachments, splits the sub-problems and writes 题目分析报告.md together with 术语表格.md, and cannot move on until the modelling final check M1 returns. Phase 2, the coder, writes and runs Python or MATLAB, produces result tables and figures, and must clear P1, a minimum runnable result, before the full computation and the final plots begin, then P2. Phase 3, the writer, builds the argument out of real results and clears W1, an evidence outline, before the long body and the dual format layout start, then W2.

One rule inside those phases matters more than the phase list. Each sub-problem may draw on at most 2 independent model systems, and in a physics question a basic approximation plus a high precision expansion of the same mechanism count as one family, not two. That cap is what stops a team from stacking five methods on a single question, and it is enforced by review rather than by anything a script can check.

## Read-only checkers ship on, optional collaborators ship off

Five checkpoints send a read-only subagent into the running work: the modelling final check, the minimum runnable result, the coding final check, the paper evidence outline and the paper final check. Where they sit costs less than what they return. The protocol in references/Subagent调度.md treats the checking subagent as a stage internal read-only acceptor and explicitly not a fourth fixed role, and it gives the failure path more detail than the success path: when a gate returns FAIL, the original executor repairs the work against the evidence and re-dispatches the check, while the main agent is forbidden from overwriting a failed conclusion by itself. Two of the five checkpoints are deliberately early, since P1 fires before the full computation and the final figures and W1 fires before the long body and the typesetting, and deferring the first check to the end of the pipeline is called out as forbidden.

Everything past those five is off by default. Optional subagents for rule verification, attachment inventory, literature and model research, algorithm prototyping, independent experiments, a Python against MATLAB comparison and terminology checking run only when a user turns them on by name. A team that assumes rich collaboration is running will get exactly five checks and nothing more.

## A read-only skill tree and a project root that takes everything

The layout is two roots and one rule about writing. SKILL_ROOT is the repository root and stays read only, holding role specs, algorithm material, scripts and templates. PROJECT_ROOT is the directory that carries the user's problem, and every run product is written there. The statement and its attachments stay read only as well, and a template has to be copied into PROJECT_ROOT before anything modifies it. Role specs sit under paths such as references/roles/建模手/SKILL.md with one file per role, and the main entry point is SKILL.md at the root, which the version badge and the stated current version both point to as 1.3.0.

Progressive loading is what lets that tree stay this wide. references/算法索引.md is an index read first, and the notes behind it load by problem type across seven categories: optimization, prediction, evaluation, graph theory, statistics, general methods and machine learning. The repository's one line description names only five of those categories and closes with a catch-all for others, which understates what ships. No LICENSE file appears among the top-level entries and no licence identifier is given, so the terms for copying the preset or the reference material are unstated.

## Three install routes and one preset directory named exactly

A Git clone is the plainest route, after which the repository goes into whatever Skills directory the agent in use expects.

```bash
git clone https://github.com/XiaoMaColtAI/math-modeling-skill.git
```

There is also a one line installer.

```bash
npx skills add https://github.com/xiaomacoltai/math-modeling-skill --skill math-modeling
```

Downloading the repository ZIP and unpacking it into the same Skills directory is the third option. The fourth is the DeepSeek Harness preset at dsh-plugin/math-modeling-agent/, which is copied as a whole directory into the preset root `<dsh-home>\.agent-presets\`, and on Windows the default path given is `C:\Users\<用户名>\AppData\Roaming\dsh-desktop\dsh-home\.agent-presets`. The directory name becomes the preset id, so the folder named math-modeling registers under that id, and a new dsh session that picks the preset called 数学建模 Workbench exposes mm_project_init, mm_phase_enter, mm_todo, mm_gate, mm_check_deliverables, mm_complete and mm_state. The preset is described as self contained, with its knowledge base persisted inside it, so it can be copied to another machine whole.

For agents such as Claude Code, Codex, Cursor, Trae and Qoder there is no pinned load path, because the documentation defers to each tool's own current instructions. Anyone scheduling this against a deadline still has to confirm the loading mechanism for the agent they actually use.

## Dependency checks ask for features, not whole environments

Before a model runs, the coder checks the environment, and the check is scoped rather than exhaustive. In Python the script takes only the features the chosen model family needs:

```bash
python references/roles/编程手/scripts/check_env.py \
  --features data visualization optimization
```

MATLAB takes the same feature vocabulary through a helper function:

```matlab
addpath("references/roles/编程手/scripts");
report = check_matlab_env(["data", "visualization", "optimization"]);
```

A first use is a typed request rather than a menu, and the single stage prompts are short:

```text
只做建模分析，输出题目分析报告和术语表格。
只实现现有模型，使用 MATLAB 运行并生成全部结果和图。
根据现有代码结果生成完整论文.docx。
```

After the first prompt the reader should find two Markdown files in PROJECT_ROOT and no plot at all. After the second, a script named 问题1_求解.py or 问题1_求解.m beside a results folder, and after the third, 完整论文.docx. Running the checks early pays off because both languages are supported, yet the dependency list is decided by the model family rather than by the skill, and nothing in the documentation maps a feature name such as optimization onto the exact library it expects.

## Nine candidate figures in, eight formal figures out

The coding phase sets a floor of at least 3 candidate figures in each of 3 classes, raw, process and result, covering every sub-problem, plus at least 1 overall modelling flow diagram. That is 9 candidates before the writer opens anything. The writing phase then demands at least 8 formal figures, again covering every sub-problem, with at least 1 formal result figure per sub-problem. The two floors sit 1 apart, which leaves a team almost no slack when a candidate is rejected in review, and the file naming makes the trap easy to see: raw_q1_*, process_q1_* and result_q1_* are written as fixed triples per class rather than as a ranked pool.

The rest of the figure contract is stricter than the floor. Chart type comes after the data and the argument are dissected, encoding has to stay readable for colour vision deficiency, export is SVG plus PNG at 300 DPI, and every figure passes a self check loop that drops a grayscale preview into _qa/. That loop runs by itself, so a figure surviving grayscale has cleared one legibility bar without a human opening it. Reproducibility lands next to the figures in results/复现清单.json, which records random seeds, the SHA-256 of input files, runtime and dependency versions, key parameters and the single command that reproduces the run.

## Two search engines, one cross check and a missing key

Literature work goes to a single script that queries OpenAlex and AnySearch in parallel, then cross verifies each hit by DOI or by title.

```bash
python tools/paper_search/scripts/hybrid_scholar.py \
  --query "robust optimization vehicle routing" \
  --limit 10 \
  --json
```

OpenAlex reaches its polite pool when `--email` is passed, and AnySearch needs a key through the environment variable ANYSEARCH_API_KEY. A formal search runs both engines at once, while the single engine arguments are kept for diagnosis only. That design has a cost worth naming: a team without an AnySearch key runs one engine out of two, the documentation gives no cached or offline fallback for the missing half, and the writer's claim of a dual engine search then stops being true for that run. The cross verification step either degrades or has to be skipped by hand.

The runnable surface is worth knowing before anyone adopts this. The commands the documentation names are this search script, the Python environment check and its MATLAB counterpart, plus the mm_ wrappers inside the dsh preset. The algorithm library is guidance loaded through the index, not shipped solvers, which means the coder still writes the Python or MATLAB for every sub-problem.

## Word is the deliverable, LaTeX is opt in and costly

The writer phase ships 完整论文.docx and stops there unless a user asks for more. The LaTeX branch is heavier than a format conversion: it copies the official template project, records its hashes, binds authoritative code and figures to it, compiles a real PDF, then checks resource, source and PDF hashes, blank pages, page size, font embedding and image DPI, writing 完整论文.conversion.json and 完整论文.build.json as the record. When both formats are produced, the same data, figures, formulas, references and conclusions have to appear on both sides, and an existing LaTeX main manuscript can be converted whole with Pandoc.

Here is the honest alternative: skip the skill, drive OpenAlex, Pandoc and a plotting library yourself, and take one phase at a time through the single stage prompts. That route is faster when a single sub-problem is all you have, and nothing in it produces M1, P1, P2, W1, W2 or results/复现清单.json.

The numbers in this phase are where the project's rules meet the competition's. Completeness for CUMCM targets roughly 15000 word units across about 20 pages, described as a quality goal and not an official requirement, while the same text says the official submission rules of the year in question decide which version can actually be entered. Against that, a baseline of at least 8 formal figures is applied to every competition. A team that reads those numbers as requirements will optimise for a house target the project itself says is not the rule.

## Conclusion

Adopt it when your team faces a dated contest deadline and has never run a gated pipeline, because the value here is the evidence chain rather than any model inside it. Skip it for one sub-problem a single library already solves, and skip it as a base for redistributing the work. Before promising a result, verify the load path in your own agent, confirm the official template for your year is actually on hand, and check whether results/复现清单.json survives the edits your team will make. Last push: 2026-09-19.

## FAQ

### How do I install math-modeling-skill into Claude Code or Codex?

Clone the repository with git and place it in the Skills directory your agent uses, or run the documented npx skills add command with --skill math-modeling. For agents other than dsh the documentation does not fix a load path and defers to each tool's own instructions, so confirm the loading mechanism first.

### Does math-modeling-skill produce a LaTeX paper by default?

No. The default deliverable is 完整论文.docx built from an official template, and the LaTeX source project, a compiled PDF and the hash manifest are produced only when a user explicitly asks for them.

### What does math-modeling-skill actually execute, and what does it leave to the model?

The named runnable pieces are the dual engine search script, the Python environment check and its MATLAB counterpart, plus the mm_ tools inside the dsh preset. Model code for each sub-problem is still written by the coder role, because the algorithm library is guidance loaded through references/算法索引.md rather than shipped solvers.

### How many figures does a math-modeling-skill paper need?

The coding phase asks for at least three candidate figures in each of three classes plus an overall modelling flow diagram, and the writing phase asks for at least eight formal figures covering every sub-problem, with one formal result figure per sub-problem.

### Can I run only the modelling analysis stage of math-modeling-skill?

Yes. Single stage prompts let you stop after 题目分析报告.md and 术语表格.md, implement an existing model only, or write the paper from results you already have. Phases that already passed are not repeated when a later phase sends work back.

### What licence does math-modeling-skill use?

No LICENSE file appears among the top-level entries and no licence identifier is given. Copying the dsh preset or the reference material into another project therefore has no stated terms, so ask the author before redistributing.

## Sources

- [Issues](https://github.com/XiaoMaColtAI/math-modeling-skill/issues)
- [Project website](https://mms.weseeworld.cn)
- [README](https://github.com/XiaoMaColtAI/math-modeling-skill/blob/main/README.md)
- [Releases](https://github.com/XiaoMaColtAI/math-modeling-skill/releases)
- [XiaoMaColtAI/math-modeling-skill on GitHub](https://github.com/XiaoMaColtAI/math-modeling-skill)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/xiaomacoltai-math-modeling-skill