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.
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.
$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:
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
- Prefer the official MATLAB MCP auto mode for MATLAB work on this machine.
- Do not silently fall back to
matlab -batchwhen MCP is expected. - Capture logs, version info, working directory, and artifact paths where applicable.
- Run from a project root, not from a random temporary folder, unless isolation is required.
- Put generated files under
artifacts/or a user-specified output folder. - Keep scripts deterministic: seed random generators and record data sources.
- 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:
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 -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:
# 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 -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:
matlab -batch "disp(version); v=ver; disp({v.Name}')"
MATLAB Discovery
Use this order to find MATLAB:
- Official MATLAB MCP auto configuration
- Existing official MATLAB shared session metadata when present
$env:MATLAB_EXE,Get-Command matlab, and known install paths only for setup/verification of the MCP environment
Verify before running expensive work:
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 R2026alicense('test','Deep_Learning_Toolbox')returns0whilelicense('test','Neural_Network_Toolbox')returns1for the same installed product. The verified product→feature map, with its provenance, is inreferences/toolbox-feature-map.md.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, andmas_capability_checknow 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:
- Record paper URL, commit hash, dataset URL, MATLAB release, toolbox list.
- Run the smallest official example first.
- Reproduce one figure or table before scaling to the whole paper.
- Save
manifest.json, raw logs, processed data, and generated figures. - 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.
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: 322k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 322k | 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 |