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 |
scripts/mas_dep_probe.m
View on GitHubfunction r = mas_dep_probe(what, target, opts)
%MAS_DEP_PROBE Five-level dependency discovery with explicit failure classes.
%
% r = mas_dep_probe('function', 'butter')
% r = mas_dep_probe('product', 'Deep Learning Toolbox')
% r = mas_dep_probe('feature', 'Signal_Toolbox')
% r = mas_dep_probe('exec', 'tf(1,[1 1])')
%
% r.state % OK | FN_NOT_FOUND | IS_A_DIRECTORY | NOT_ON_PATH | NOT_INSTALLED
% % | NOT_LICENSED | EXEC_FAILED | UNKNOWN_PRODUCT | BAD_CALL
% r.level % how deep the probe got: 0 nothing, 1 function resolved,
% % 3 product installed, 4 feature licensed, 5 probe executed
%
% WHY FIVE LEVELS AND NOT A BOOLEAN
% "It does not work" has five different causes with five different fixes, and the
% previous phase collapsed them into a boolean:
%
% 1 function not found -> the name is wrong, or the folder is not on path
% 2 name resolves to a dir -> `robotics` is a toolbox FOLDER; exist()=7, which
% a naive `exist(...)==2` reports as "missing"
% 3 file exists off path -> `which` empty; addpath is the fix, not install
% 4 product not installed -> ver() does not list it; install
% 5 product installed but -> license('test', FEATURE) = 0; the feature string
% not licensed is the usual culprit, see mas_product_map
% 6 licensed but throws -> the product is there and the call is wrong
%
% Level 3-5 are only attempted for 'product' probes, because they are the expensive
% ones (license checkout has real cost, and executing a probe can have side
% effects). 'function' probes stop at level 1 unless opts.deep is set.
%
% opts:
% .deep (false) continue past level 1 for function probes
% .throw (false) rethrow execution errors after recording them
% .skipExec (false) do not run the representative probe expression
if nargin < 3 || isempty(opts), opts = struct(); end
opts = with_defaults(opts);
r = struct('what', what, 'target', char(target), 'state', 'BAD_CALL', 'level', 0, ...
'pass', false, 'detail', '', 'product', '', 'feature', '', 'evidence', {{}});
switch lower(what)
case 'function'
r = probe_function(r, char(target), opts);
case 'product'
r = probe_product(r, char(target), opts);
case 'feature'
r = probe_feature(r, char(target), opts);
case 'exec'
r = probe_exec(r, char(target), opts);
otherwise
error('mas_dep_probe:what', 'unknown probe type "%s"', what);
end
r.pass = strcmp(r.state, 'OK');
end
% ---------------------------------------------------------------------------
function r = probe_function(r, name, opts)
% Level 1: does the name resolve to something callable?
%
% Resolution is done with `which`, NOT with `exist(name,'file')`. The first version
% used the latter and reported core MATLAB built-ins as missing:
%
% exist('chol','file') -> 0 exist('chol','builtin') -> 5
% exist('svd','file') -> 7 which('svd') -> built-in (@double/svd)
%
% The 'file' option searches for files and folders only and explicitly excludes
% built-ins, so `chol`, `eig`, `inv` were classified FN_NOT_FOUND and `svd`
% (which dispatches through @double/@single/@gpuArray folders) was classified
% IS_A_DIRECTORY -- both false, and both pointing the caller at a fix (rename,
% addpath, install) for a problem that did not exist. `which` resolves every one
% of them correctly, so it is the primary test and `exist` is only used
% afterwards to say WHY a name that `which` cannot resolve is unavailable.
w = which(name);
if ~isempty(w)
r.level = 1;
e = exist(name); % plain: 5 builtin, 2 .m, 3 mex, 6 p
r.state = 'OK';
r.detail = sprintf('%s resolves to %s', name, w);
r.evidence{end+1} = sprintf('which=%s', w);
r.evidence{end+1} = sprintf('exist=%d', e);
else
e = exist(name); % 0 nowhere, 7 folder/package
if e == 7
r.state = 'IS_A_DIRECTORY'; r.level = 0;
r.detail = sprintf('"%s" is a FOLDER (exist=7) with no callable of that name: it cannot be called', name);
elseif ismember(e, [2 3 6])
% A file that exists but is not visible to the path resolver. This happens
% after `cd` into a folder whose parent was removed from the path.
r.state = 'NOT_ON_PATH'; r.level = 0;
r.detail = sprintf('"%s" is a file (exist=%d) but `which` cannot resolve it: add its folder to the path', name, e);
else
r.state = 'FN_NOT_FOUND'; r.level = 0;
r.detail = sprintf('"%s" not found: not a file, not a builtin, not a folder', name);
end
return;
end
if ~opts.deep, return; end
% Level 3-5: attribute the function to a product and check the license.
pm = mas_product_map(name);
if pm.found
r.product = pm.name; r.feature = pm.feature;
else
% Unknown owner is not a failure: many core functions live in MATLAB itself.
r.evidence{end+1} = 'owner product unknown; treated as core MATLAB';
return;
end
[r, okOwn] = check_product_levels(r, pm, opts);
if ~okOwn, return; end
% Level 5: execute the representative probe of the OWNING product, if any. The
% function itself is not called, because calling it needs valid arguments; a
% product-level probe answers "is this product usable at all".
if ~isempty(pm.probe)
[okx, msg] = run_probe(pm.probe);
if ~okx
r.state = 'EXEC_FAILED'; r.detail = sprintf('%s licensed but probe "%s" failed: %s', ...
pm.name, pm.probe, msg);
return;
end
r.level = 5;
r.evidence{end+1} = sprintf('probe "%s" executed', pm.probe);
end
end
% ---------------------------------------------------------------------------
function r = probe_product(r, name, opts)
pm = mas_product_map(name);
if ~pm.found
r.state = 'UNKNOWN_PRODUCT'; r.level = 0;
r.detail = sprintf('"%s" is not in the product map', name);
if ~isempty(pm.candidates)
r.detail = sprintf('%s; did you mean: %s', r.detail, strjoin(pm.candidates, ' | '));
end
return;
end
r.product = pm.name; r.feature = pm.feature;
r.evidence{end+1} = sprintf('canonical=%s', pm.name);
if ~isempty(pm.aliases)
r.evidence{end+1} = sprintf('aliases=%s', strjoin(pm.aliases, ','));
end
[r, ok] = check_product_levels(r, pm, opts);
if ~ok, return; end
if opts.skipExec || isempty(pm.probe)
r.state = 'OK';
if isempty(pm.probe)
r.detail = sprintf('%s installed and licensed (no executable probe defined)', pm.name);
else
r.detail = sprintf('%s installed and licensed (probe skipped)', pm.name);
end
return;
end
[okx, msg] = run_probe(pm.probe);
if okx
r.state = 'OK'; r.level = 5;
r.detail = sprintf('%s usable: installed, licensed, probe "%s" ran', pm.name, pm.probe);
r.evidence{end+1} = sprintf('probe "%s" OK', pm.probe);
else
r.state = 'EXEC_FAILED';
r.detail = sprintf('%s installed and licensed but probe "%s" failed: %s', pm.name, pm.probe, msg);
end
end
% ---------------------------------------------------------------------------
function r = probe_feature(r, feat, opts)
installed = ver_has_feature(feat);
lic = license('test', feat);
r.feature = feat;
r.level = 4;
r.evidence{end+1} = sprintf('license(''test'',''%s'')=%d', feat, lic);
if installed && lic
r.state = 'OK'; r.detail = sprintf('feature %s licensed', feat);
elseif ~installed && lic
r.state = 'OK'; r.detail = sprintf('feature %s licensed (not listed in ver: a shared feature)', feat);
elseif installed && ~lic
r.state = 'NOT_LICENSED'; r.detail = sprintf('feature %s installed but not licensed', feat);
else
r.state = 'NOT_INSTALLED'; r.detail = sprintf('feature %s neither installed nor licensed', feat);
end
end
% ---------------------------------------------------------------------------
function r = probe_exec(r, expr, opts)
r.level = 0;
[ok, msg] = run_probe(expr);
if ok
r.state = 'OK'; r.level = 5; r.detail = sprintf('"%s" ran', expr);
else
r.state = 'EXEC_FAILED'; r.detail = sprintf('"%s" failed: %s', expr, msg);
if opts.throw, error('mas_dep_probe:exec', '%s', msg); end
end
end
% ---------------------------------------------------------------------------
function [r, ok] = check_product_levels(r, pm, opts)
% Level 3: installed. Level 4: licensed. Writes the state and returns ok=false when
% the chain stops.
installed = any(strcmpi({ver().Name}, pm.name));
r.evidence{end+1} = sprintf('installed=%d', installed);
r.level = 3;
if ~installed
r.state = 'NOT_INSTALLED';
r.detail = sprintf('%s is not listed by ver()', pm.name);
ok = false; return;
end
if pm.installationOnly
r.state = 'OK';
r.detail = sprintf('%s installed (installation-only; license(''test'') not applicable)', pm.name);
r.evidence{end+1} = 'license not applicable';
ok = true; return;
end
lic = license('test', pm.feature);
r.level = 4;
r.evidence{end+1} = sprintf('license(''test'',''%s'')=%d', pm.feature, lic);
if ~lic
% A failed licence check is NOT the end of the investigation: the feature
% name in our table is a GUESS, and a wrong guess turns a working product
% into a false "NOT_LICENSED". The evidence here is concrete: on R2026a
% Communications Toolbox is installed, `license('test','Communications_Toolbox')`
% returns 0, and yet `qammod` runs -- so the product IS usable and our
% feature name is wrong.
%
% So when the product has an EXECUTABLE probe, run it. If the probe works,
% the product works, whatever the licence feature string says. The probe is
% the stronger evidence; the feature string is bookkeeping.
if ~opts.skipExec && ~isempty(pm.probe)
[pok, pmsg] = run_probe(pm.probe);
r.evidence{end+1} = sprintf('probe(''%s'')=%d', pm.probe, pok);
if pok
r.state = 'OK';
r.level = 5;
r.detail = sprintf(['%s usable: installed, and probe "%s" ran ' ...
'although license(''test'',''%s'') returned 0 -- the feature ' ...
'name in the map is wrong, the product itself works'], ...
pm.name, pm.probe, pm.feature);
ok = true; return;
end
r.evidence{end+1} = sprintf('probe failed: %s', pmsg);
end
r.state = 'NOT_LICENSED';
r.detail = sprintf('%s installed but feature %s not licensed', pm.name, pm.feature);
ok = false; return;
end
ok = true;
end
% ---------------------------------------------------------------------------
function [ok, msg] = run_probe(expr)
% Evaluate an expression in a private workspace with output captured, so a
% successful probe can neither pollute the caller's variables nor print.
ok = false; msg = '';
try
evalc(expr);
ok = true;
catch ME
msg = sprintf('%s: %s', ME.identifier, ME.message);
end
end
% ---------------------------------------------------------------------------
function tf = ver_has_feature(feat)
% ver() lists product NAMES, so an exact feature string rarely appears. Map it back
% through the table when possible; otherwise report "not listed" without claiming
% the feature is absent from the license.
m = mas_product_map('', 'all');
tf = false;
for k = 1:size(m,1)
if strcmpi(m{k,2}, feat)
tf = any(strcmpi({ver().Name}, m{k,1}));
return;
end
end
end
% ---------------------------------------------------------------------------
function o = with_defaults(o)
d = struct('deep', false, 'throw', false, 'skipExec', false);
fn = fieldnames(d);
for k = 1:numel(fn)
if ~isfield(o, fn{k}), o.(fn{k}) = d.(fn{k}); end
end
end
function s = tern(c, a, b)
if c, s = a; else, s = b; end
end
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 |