wzyn20051216/matlab-agent-skills / skills/matlab-runner
matlab-runner
VerifiedRun MATLAB tasks from Codex with reliable MCP-based execution, logs, artifacts, toolbox inventory, smoke tests, and reproducible validation. Use whenever MATLAB code, .m/.mlx scripts, MATLAB tests, local toolbox probing, or command-line automation is needed.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 13.5 KB |
| references/acceptance-levels.md | markdown | 3.0 KB |
| references/failure-classes.md | markdown | 2.5 KB |
| references/mcp-readiness-ladder.md | markdown | 6.4 KB |
| references/toolbox-feature-map.md | markdown | 1.1 KB |
| scripts/mas_dep_probe.m | other | 11.4 KB |
| scripts/mas_precheck.m | other | 7.5 KB |
| scripts/mas_product_map.m | other | 6.2 KB |
| scripts/mas_toolbox_map.m | other | 2.8 KB |
| tests/test_dep_probe.m | other | 6.2 KB |
| tests/test_precheck.m | other | 3.6 KB |
SKILL.md
View on GitHub---
name: matlab-runner
description: Run MATLAB tasks from Codex with reliable MCP-based execution, logs, artifacts, toolbox inventory, smoke tests, and reproducible validation. Use whenever MATLAB code, .m/.mlx scripts, MATLAB tests, local toolbox probing, or command-line automation is needed.
---
# MATLAB Runner
Use this skill to execute MATLAB work safely and repeatably through the official MATLAB MCP server, preferably in `auto` mode, and only use terminal batch workflows when the user explicitly asks for them. It is the foundation skill for all other MATLAB skills.
## Skill Root Resolution
The installed Skill is self-contained: the probe, batch wrapper, their modules, the
acceptance schema, and the pinned MCP server release manifest all live **inside this
Skill directory**, next to this
`SKILL.md`. The caller's current working directory is never the Skill root, so every
command below resolves resources from the Skill root first.
`$skillRoot` means the absolute path of the installed Skill directory that contains
this `SKILL.md` (the directory reported by the client's Skill loader). Set it once
per shell session; do not derive it from the caller cwd and do not assume a
repository checkout exists.
```powershell
$skillRoot = '<absolute path to the installed matlab-runner Skill directory>'
$probe = Join-Path $skillRoot 'scripts\Test-MatlabMcpExistingSession.ps1'
```
The MATLAB helpers (`mas_precheck`, `mas_dep_probe`) live in the same root. Add them
for the current MATLAB session only; never edit `savepath`, `startup.m`, or a global
MATLAB preference:
```matlab
skillRoot = '<absolute path to the installed matlab-runner Skill directory>';
addpath(fullfile(skillRoot, 'scripts'));
```
If `$skillRoot\scripts\Test-MatlabMcpExistingSession.ps1` is missing, the Skill was
installed incompletely. Report that exact path and ask the user to reinstall the
Skill with the project installer; do not search the disk for another copy, do not
fall back to a development checkout, and do not run an unknown script found nearby.
## References — load on demand
This file carries the workflow. The tables below are **not** loaded unless the task
actually reaches them, because each is a few hundred tokens of detail that costs
context on every run and goes stale on every MATLAB release.
| Load this | when |
|---|---|
| `references/toolbox-feature-map.md` | resolving a product name to a licence feature |
| `references/mcp-readiness-ladder.md` | about to claim MCP is ready, or MCP failed |
| `references/acceptance-levels.md` | about to write an acceptance report |
| `references/failure-classes.md` | a run failed and you are deciding whether to retry |
## Execution Rules
1. Prefer the official MATLAB MCP auto mode for MATLAB work on this machine.
2. Do not silently fall back to `matlab -batch` when MCP is expected.
3. Capture logs, version info, working directory, and artifact paths where applicable.
4. Run from a project root, not from a random temporary folder, unless isolation is required.
5. Put generated files under `artifacts/` or a user-specified output folder.
6. Keep scripts deterministic: seed random generators and record data sources.
7. Record the provenance of every non-trivial parameter or component value: pull physical parameters from real datasheets and reference designs, and note the source (URL, app-note number, or datasheet part number) in a comment or manifest. Do not leave a plausible-but-unsourced number in the model without marking it as a placeholder.
## Precheck Before A Long Run
Phase 3B.1 shipped five scripts and none ran on the first attempt; most of those
failures were detectable in seconds. Run the cheap checks first, in this order:
```matlab
r = mas_precheck('function', 'boost_params'); % exists?
r = mas_precheck('struct', cfg, {'Vin','L','C'}); % fields present?
r = mas_precheck('numeric', x, struct('finite',true)); % NaN/Inf?
r = mas_precheck('index', mask, numel(target)); % mask length
r = mas_precheck('toolbox', 'Control System Toolbox'); % product vs feature
r = mas_precheck('model', fullfile(pwd, 'models', 'boost_avg.slx'));
```
The `index` check exists because MATLAB does **not** error when a logical mask is
shorter than the array it indexes: it silently returns the first `numel(mask)`
elements. In Phase 3B.2 that turned every `iLref` reading into `0` and nearly
produced the conclusion "the current command is railed". A length check makes it
loud. `tests/test_precheck.m` covers positive and must-fail cases.
Never start a 20-minute matrix after a failed precheck; fix the precheck first.
## MCP Required By Default
A config file never proves MCP works, and `sessionDetails.json`, a listening `pid`
or a client entry in `.mcp.json` all look identical to a file-existence check.
`sessionDetails.json` is a credential descriptor, not plain configuration: it holds
the live MCP `apiKey` and certificate. Never read, print, echo, copy, or archive its
contents, and never paste it into prompts, logs, or reports. Use the probe below,
which reads only the fields it needs. If a credential may have been exposed, report
the file path and field name without reproducing the value, then ask the user to
rotate it — a redacted report does not mean the underlying key is invalid.
Before claiming readiness, run the staged probe and read its verdict:
```powershell
powershell -ExecutionPolicy Bypass -File $skillRoot\scripts\Test-MatlabMcpExistingSession.ps1 -ProjectRoot (Get-Location).Path -Json
```
**Before a long task, run the readiness gate instead — it fails in seconds, not minutes:**
```powershell
# exit 0 = provably executable; exit 1 = not ready, and nextAction prints the exact two commands
powershell -ExecutionPolicy Bypass -File $skillRoot\scripts\Ensure-MatlabMcpReady.ps1 -Work (Join-Path (Get-Location).Path 'artifacts\runtime') -Json
```
`Ensure-MatlabMcpReady.ps1` exists because the failure mode is otherwise very expensive: in
`existing` mode a dead shared session still completes `initialize` and `tools/list`, then
`tools/call` blocks silently until the client's timeout (120 s or more) and the task ends
BLOCKED. The gate therefore treats three cheap conditions (`sessionDetails.json` exists,
recorded pid is a live MATLAB, recorded port is listening) only as early exits, and
accepts **one** proof of readiness: `mcp.readonly-exec` = `PASS` from a real `tools/call`
with `-TimeoutSeconds` (default 20 s). Never report MCP as ready on pid+port alone — a
`pause()`-held session answers `200` on the port while every `tools/call` hangs.
When the gate reports `NOT_READY`, do not start work and do not silently fall back to
`matlab -batch`: report the gate's `reasons` verbatim, then run `startCommand` **as a
background task** (the held session must outlive this shell), wait for
`<Work>\session_ready.json` (~30 s), and re-run `recheckCommand`. The gate deliberately
does not spawn MATLAB itself: a managed host rejects `Start-Process` of an interpreter,
and a script cannot outlive the session it would hold.
The probe writes only into the current project's `artifacts/` directory. It never
reads the source repository, never needs the caller cwd to be the Skill root, and
never prints the session credential.
By default (`-Transport auto`) the probe drives the official MATLAB MCP server over
**stdio** — that is the only path the server supports — and only falls back to a
loopback `https` observation when no manifest-verified server binary exists on the
machine. Run it as-is: do not add `-SkipTlsValidation`, and do not read an `https`
`403` as a broken Skill. When the stdio channel cannot be built, stages 3–5 report
SKIP with the real reason instead of a fallback.
The seven-stage ladder, the rules that must not be relaxed (only stage 4 upgrades a
licence SKIP to PASS; a failed stage makes every later stage SKIP), and the
machine-specific decision rule are in `references/mcp-readiness-ladder.md`. Load it
when you are about to make a readiness claim — not before.
If MCP is unavailable, **report the blocker** instead of silently changing execution
mode. A batch rerun that succeeds hides the problem the user needs to see.
## Preferred Wrapper
If the user explicitly requests batch execution, prefer the wrapper shipped in this
Skill:
```powershell
powershell -ExecutionPolicy Bypass -File $skillRoot\scripts\Invoke-MatlabBatch.ps1 -Script .\path\to\script.m -TimeoutSeconds 1800
```
`-TimeoutSeconds` is mandatory in spirit: a batch run without a timeout can hang forever. The wrapper exits `124` on timeout, `2` when MATLAB cannot be found, and otherwise returns the real MATLAB exit code. A timed-out run terminates the whole process tree and still keeps the partial logs.
`Setup-MatlabMcpExistingSession.ps1` and `Test-MatlabSkills.ps1` are
repository-only developer operations. They are **not shipped** inside the installed
Skill, so an installed user must not be asked to run them or to find a development
checkout. The installed workflow is the shipped probe above plus the user's own MCP
client configuration.
If the wrapper is not available, call MATLAB directly:
```powershell
matlab -batch "disp(version); v=ver; disp({v.Name}')"
```
## MATLAB Discovery
Use this order to find MATLAB:
1. Official MATLAB MCP auto configuration
2. Existing official MATLAB shared session metadata when present
3. `$env:MATLAB_EXE`, `Get-Command matlab`, and known install paths only for setup/verification of the MCP environment
Verify before running expensive work:
```matlab
disp(version)
v = ver;
{v.Name}'
```
## Error Handling
When MATLAB fails:
- Read the first error and the deepest stack frame.
- Check a missing toolbox with `mas_precheck('toolbox', X)` rather than by hand.
`license('test', ...)` takes a **feature** name, not the product display name, and
the two differ often enough to burn a run: on R2026a
`license('test','Deep_Learning_Toolbox')` returns `0` while
`license('test','Neural_Network_Toolbox')` returns `1` for the same installed
product. The verified product→feature map, with its provenance, is in
`references/toolbox-feature-map.md`.
```matlab
r = mas_precheck('toolbox', 'Deep Learning Toolbox');
r.pass, r.detail % 1, "installed 1, feature Neural_Network_Toolbox licensed 1"
```
A product missing from the map returns a failure that says so, rather than
guessing. (An earlier revision of this file told the agent to call
`masacc.availability`. No such package exists in this repository or in any
installed toolbox — a call to it fails immediately. That instruction is removed,
and `mas_capability_check` now fails the build if any file references it again.)
- Check path ambiguity with `which functionName -all`.
- Re-run a minimal reproduction before editing large code.
- Save the failing command and log path.
- If the failure was on MCP, report the exact MCP blocker and stop hiding it behind a batch rerun.
## Acceptance Checks
Report which level was actually proven, not a vague "it works". The levels are
cumulative and **never upgrade themselves**: producing a file is an L1 claim, and
calling that "deployed" is the most common overstatement here because the file
really is there.
| Level | Meaning |
|---|---|
| L1 | artifact produced |
| L2 | build/compile succeeded |
| L3 | numeric result matches a golden value |
| L4 | multi-scenario and failure modes |
| L5 | real hardware run, read back |
`SKIP` means "not executed" and is not a pass; a report containing any SKIP has
`overallStatus = SKIP` and exit code `3`. `FAIL` or `SKIP` without a `reason` is
rejected at construction time. Which single checks are worth running per situation
is in `references/acceptance-levels.md` — load it before writing the report, not
before every command.
## Failure Classification
Classify before retrying. Retrying a `LICENSE_ERROR` or an `ENVIRONMENT_ERROR` only
wastes time, and a retried `VALIDATION_ERROR` can turn a clear numeric mismatch into
a vague "flaky". The eight classes, which are auto-retryable, and the cap of 5
attempts are in `references/failure-classes.md`. The rule that matters most:
**non-idempotent or destructive operations (downloads, installs, writes) are never
retried without explicit user approval**, because the retry is the part that causes
damage.
## Paper Reproduction Mode
For open-source paper projects:
1. Record paper URL, commit hash, dataset URL, MATLAB release, toolbox list.
2. Run the smallest official example first.
3. Reproduce one figure or table before scaling to the whole paper.
4. Save `manifest.json`, raw logs, processed data, and generated figures.
5. Mark differences from the paper explicitly instead of smoothing them over.
## One Dependency Mechanism, Five Failure Classes
`mas_precheck('toolbox', X)` and `mas_dep_probe` now share a single product table
(`mas_product_map.m`). Before this there were two copies and they could drift; the
old one lived inside `mas_precheck` and the new one inside the probe.
```matlab
d = mas_dep_probe('product', 'Deep Learning Toolbox');
d.state % OK | NOT_INSTALLED | NOT_LICENSED | UNKNOWN_PRODUCT | EXEC_FAILED
d.level % 1 function resolved, 3 product installed, 4 feature licensed, 5 probe ran
```
`NOT_INSTALLED`, `NOT_LICENSED` and `UNKNOWN_PRODUCT` are different problems with
different fixes, so they are different states. The probe reports which level it
reached, so "it does not work" becomes a specific sentence.
Historical product names are aliases of the current row (`Neural Network Toolbox` ->
`Deep Learning Toolbox`, `Statistics Toolbox` -> `Statistics and Machine Learning
Toolbox`), because a user typing the old name must not get "not licensed". Covered
by `tests/test_dep_probe.m`, including must-fail dependency cases.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |