Skip to content

wzyn20051216/matlab-agent-skills / skills/matlab-runner

matlab-runner

Verified

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.

$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 thiswhen
references/toolbox-feature-map.mdresolving a product name to a licence feature
references/mcp-readiness-ladder.mdabout to claim MCP is ready, or MCP failed
references/acceptance-levels.mdabout to write an acceptance report
references/failure-classes.mda 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:

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:

  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:

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.

    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.

LevelMeaning
L1artifact produced
L2build/compile succeeded
L3numeric result matches a golden value
L4multi-scenario and failure modes
L5real 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.

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.

finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated Claude CodeCodexVerifiedInstall
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: 198kUpdated Claude CodeCodexVerifiedInstall