matlab-build-toolbox - SKILL.md Agent Skill

name: matlab-build-toolbox description: "Execute the build plan — introspect buildfile.m, run its dependency chain, and produce the .mltbx toolbox package. Mechanical execution with no human checkpoint. Works with any buildplan shape." license: MathWorks BSD-3-Clause metadata: author: MathWorks version: "1.0"

matlab-build-toolbox — Build Executor

You execute the build pipeline. You are an operator — you introspect the plan to find the right task to invoke, run it, report results at each stage, and stop on failure. This is the only skill in the pipeline with no human checkpoint.

When to Use

After matlab-assess-toolbox reports READY (no blockers)
User says "build it", "run the build", or "build package"
User has their own buildfile.m and wants to execute it
As part of the full pipeline after readiness gate passes

When NOT to Use

No buildfile.m exists — use matlab-create-buildfile first
User wants to create or modify build tasks — use matlab-create-buildfile
User wants to publish/release — use matlab-publish-toolbox after a successful build
User wants a readiness check — use matlab-assess-toolbox

Key Functions

Function	Purpose
`matlab.buildtool.Plan.load`	Introspect the build plan to discover tasks and dependencies
`buildtool`	Execute the build pipeline (runs task dependency chain)
`dir`	Locate and verify the `.mltbx` artifact after packaging

Inputs

project_root: Path to the project (default: current directory)
target (optional): The buildtool task to execute. If omitted, auto-detected from the plan (see Step 2).

Workflow

Step 1 — Verify Preconditions

Before executing:

Confirm buildfile.m exists at the project root
Determine pipeline context:
- Full pipeline (buildUtilities/toolboxSpecification.m and buildUtilities/tbxManifest.m exist): readiness was run, proceed with full context
- Standalone buildplan (only buildfile.m exists): user has their own plan not generated by matlab-create-buildfile. Skip spec/manifest checks, proceed with introspection.
If full pipeline context exists, confirm no blockers from last readiness check

If buildfile.m does not exist, stop and direct the user to matlab-create-buildfile or ask them to provide one.

Step 2 — Introspect the Build Plan

Load the plan and discover its structure:

plan = matlab.buildtool.Plan.load("buildfile.m");
disp({plan.Tasks.Name})

Identify the target task (in priority order):

Use the target input if provided
Look for a task named package
Find the terminal task — one with no downstream dependents that produces the .mltbx
If ambiguous (multiple candidates), ask the user which to run

Identify the dependency chain leading to the target:

% The chain executes in topological order when you run the target
% e.g., buildtool package → runs check, test, package

Report what will execute:

Build target: "package"
Dependency chain: check → test → package

Step 3 — Execute Build Pipeline

Run via MATLAB, stopping on first failure:

buildtool <target>

Monitor each stage dynamically based on what's in the chain:

Task Type	Success Condition	On Failure
`CodeIssuesTask` or "check"	0 error-severity findings	Report findings, stop
`TestTask` or "test"	All tests pass	Report failures, stop
Coverage (if present)	Reports coverage	Log warning if below threshold (does not stop)
`MexTask`	MEX file produced	Report error, stop
`PcodeTask`	P-code files produced	Report error, stop
Packaging task	`.mltbx` file produced	Report error, stop

Not all chains have all stages. Report only what exists in this plan.

Step 4 — Verify Artifact

After successful packaging, locate and verify the .mltbx. First check the task's declared Outputs (authoritative), then fall back to scanning release/ and the project root:

mltbxFile = dir(fullfile("release", "*.mltbx"));
assert(~isempty(mltbxFile), "No .mltbx file found in release/");
assert(mltbxFile(1).bytes > 0, "Package file is empty");
fprintf("Package: %s (%.1f KB)\n", fullfile(mltbxFile(1).folder, mltbxFile(1).name), mltbxFile(1).bytes / 1024);

If no .mltbx in release/, check the task's declared Outputs or scan the project root. A zero-byte file counts as a failure.

Step 5 — Report Results

## Build Complete

- Package: release/MyToolbox.mltbx (142.3 KB)
- Target: "package"
- Chain: check → test → package
- Static analysis: 0 errors, 2 warnings
- Tests: 25/25 passed
- Coverage: 85%
- Duration: 12.3s

### Next Steps
- Run `matlab-publish-toolbox` to version-tag and release
- Test installation: matlab.addons.toolbox.installToolbox("release/MyToolbox.mltbx")

Adapt the report to what actually ran — omit sections for stages not in this plan (e.g., if no coverage task, don't report coverage).

On failure:

## Build Failed — [Stage]

### What happened
[error details]

### Suggested fix
[actionable suggestion]

### To retry
Run `matlab-build-toolbox` after fixing the issue.

Output

.mltbx toolbox package
Build report (pass or fail with details)

Checkpoint

No — this skill is mechanical. It executes an already-approved plan. If it fails, it reports why and stops.

Key Rules

Introspect first. Read the buildplan before executing. Never assume the task name or dependency chain — discover it.
Stop on first failure. Never continue past a failing stage. A package from broken code is worse than no package.
Report everything. Show counts, percentages, durations. The user should be able to verify the build quality.
Verify the artifact. Check .mltbx exists and has non-zero size. A zero-byte package is a silent failure.
No decisions. You execute the plan. You do not modify code, skip tests, or lower thresholds. If something fails, report it and stop.
Idempotent. Running this skill again after fixing an issue should work cleanly.

Next Steps

/matlab-publish-toolbox — version-stamp and distribute the release