wzyn20051216/matlab-agent-skills / skills/matlab-orchestrator
matlab-orchestrator
VerifiedMATLAB agentic workflow router. Use this whenever the user asks for MATLAB, Simulink, .m/.mlx/.slx work, toolbox-driven engineering, paper reproduction, simulation, code generation, data analysis, control, robotics, signal/image/AI workflows, or wants an end-to-end automated MATLAB task with validation. For Simulink tasks on this machine, default to a visible workflow: open MATLAB/Simulink windows first so the user can watch modeling, simulation, tuning, and plotting progress.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 13.4 KB |
| assets/routing.json | config | 13.4 KB |
| assets/tasks.json | config | 4.9 KB |
| references/routing-contract.md | markdown | 6.5 KB |
| scripts/mas_pipeline.m | other | 8.0 KB |
| scripts/mas_route.m | other | 15.9 KB |
| scripts/mas_skill_graph.m | other | 15.1 KB |
| tests/test_routing.m | other | 3.5 KB |
| tests/test_routing_contract.m | other | 10.1 KB |
| tests/test_skill_graph.m | other | 5.3 KB |
references/routing-contract.md
View on GitHub# Routing output contract (schema 1.1)
`mas_route(prompt)` returns a struct with a stable, versioned shape. Consumers
must branch on `decision` before doing anything else. The scoring is lexical,
not semantic: the contract says what the router can promise, and where it can
only ask.
## Required fields
| Field | Type | Meaning |
| --- | --- | --- |
| `schemaVersion` | char | `'1.1'`. A consumer that needs a different major version must stop. |
| `decision` | char | `ROUTE`, `CLARIFY`, `AMBIGUOUS`, or `BLOCKED`. |
| `primary` | char | Primary domain, `''` unless `ROUTE`. |
| `secondary` | cell | Score-based secondary domains; never dependencies. |
| `loadOrder` | cell | Topological order, dependencies first. Empty when not `ROUTE`. |
| `matched` | struct array | `skill`, `term`, `weight` for each scored hit. |
| `missing` | struct array | `kind`, `name`, `detail`, `hard` for each blocker. |
| `reason` | char | Human-readable explanation of the decision. |
| `nextAction` | char | `load`, `ask`, or `stop`. |
| `available` | struct array | `id`, `installed`, `loadable`, `problem` per selected skill. |
| `alwaysLoaded` | cell | Skills loaded on every route (currently `matlab-runner`). |
| `ranked` | struct array | `id`, `score`, `hits`, `priority`, highest first. |
| `notes` | cell | Non-blocking warnings, e.g. an unlicensed soft toolbox. |
| `prompt` | char | Original prompt, case preserved. |
| `tableSource` | char | Routing table path, or `opts.table` in tests. |
| `tableVersion` | char | Version of the table that produced the decision. |
The pre-1.0 fields `decision`, `primary`, `loadOrder`, `ranked`, `matched`,
`reason` and `prompt` are unchanged. Everything else is additive, so a caller
written against the old shape keeps working; a caller that never checked
`decision` was already wrong.
## Decisions
| Decision | `nextAction` | What the agent does |
| --- | --- | --- |
| `ROUTE` | `load` | Load `loadOrder` in order, then execute the primary skill's workflow. |
| `CLARIFY` | `ask` | Ask one question. Do not pick a domain from the top-ranked guess. |
| `AMBIGUOUS` | `ask` | Ask which of the tied domains carries the core work. |
| `BLOCKED` | `stop` | Stop. Report `missing` verbatim. Do not substitute another skill. |
`CLARIFY` and `AMBIGUOUS` still fill `loadOrder` with the always-loaded skills
so that a caller can prepare the execution layer, but `primary` stays empty.
`BLOCKED` clears `primary`, `secondary`, and `loadOrder`. A blocked pipeline
must not run a partial workflow: a route that cannot load the skill that owns
the work has no honest partial answer.
## Scoring and refusals
- Each domain sums the weights of its matched terms from
`assets/routing.json`. `matched` lists exactly those terms and weights, and
their sum equals `ranked(k).score` for that skill.
- A score below `minScore` is `CLARIFY`, even if one term matched.
- A tie at the top is `AMBIGUOUS`, evaluated before secondary selection.
- Secondary skills join at `score >= multiSkillRatio * top`.
- `matlab-testing-ci` joins when the prompt asks for acceptance/regression or
when a secondary already includes it.
- `matlab-runner` is always loaded and is never scored.
### Negation and short tokens
A term preceded by a negator in the same clause does not score. The lookback is
24 characters, cut at clause separators (`,`, `,`, `。`, `;`, `而是`, `只做`,
`仅做`, ...), so `不做图像处理,只做 PID 控制` keeps PID and drops image
processing. This is a lexical guard for the common misleading keyword, not
natural-language understanding; a negator outside the window is still missed.
ASCII terms of three characters or fewer (`ci`, `ros`, `dh`, `mex`) match on
word boundaries, so `specific` does not activate CI.
## Dependencies and availability
`dependsOn` in the routing table declares execution dependencies. The router
takes the closure of the selected skills, orders it topologically, and places
dependencies before dependents. `matlab-runner` is normally first because every
non-runner skill declares it.
Before returning `ROUTE`, the router checks every skill in the closure:
| `missing.kind` | Cause | Result |
| --- | --- | --- |
| `skill` | skill directory absent | `BLOCKED` |
| `content` | `SKILL.md` absent or empty | `BLOCKED` |
| `toolbox` | hard requirement fails `license('test', feature)` | `BLOCKED` |
| `dependency` | `dependsOn` names a skill not in the table | `BLOCKED` |
| `dependency_cycle` | topological sort finds a cycle | `BLOCKED` |
A soft requirement (`"hard": false`) that is unlicensed does not block; its
warning goes into `notes`. `available(k).loadable` is `false` for both missing
and damaged skills, so a consumer can inspect availability even when the
decision is `ROUTE` in a test fixture.
The router never invents a skill name. Test fixtures are the only place where
skill ids such as `alpha`/`beta` exist, and they are passed through `opts.table`
and `opts.skillStatus` rather than being added to `routing.json`.
## Consumer recipe
```matlab
r = mas_route(prompt);
switch r.decision
case 'ROUTE'
for k = 1:numel(r.loadOrder)
load_skill(r.loadOrder{k}); % dependency order is already correct
end
case {'CLARIFY', 'AMBIGUOUS'}
ask_one_question(r.reason); % do not guess
case 'BLOCKED'
report_and_stop(r.missing); % do not fall back to another domain
end
```
Never override a `BLOCKED`, never reorder `loadOrder`, and never treat
`CLARIFY` as permission to use `ranked(1)`.
## Coverage
`tests/test_routing_contract.m` 16/16 pins the contract: real route, single
domain, multi-skill, similar-domain ambiguity, unknown prompt, negation and
clause scope, short-token boundaries, missing toolbox, uninstalled skill,
damaged skill, dependency order, missing dependency, dependency cycle, blocked
output shape, and the `matched`-sum invariant.
`tests/test_routing.m` 9/9 is the historical regression, unchanged: the Phase 4
brief examples, the two must-not-guess cases, and the runner-always-first rule.
## Known limits
- The table is curated. A domain with no terms cannot be routed even if the
request is plainly in that domain; the honest output is `CLARIFY`.
- Negation is clause-local and lexical; double negation and indirect phrasing
are outside the contract.
- Availability is checked from the filesystem and license features, not by
loading the skill. A skill that is present but internally broken is only
caught when its own tests or prechecks run.
- The router validates `dependsOn` against the routing table, not against the
SKILL.md prose. Keep the two in sync; `mas_skill_graph` checks the call graph.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |