Matlab Project

MATLAB Project — Setup, Conventions, and Build-Script Patterns

A MATLAB Project (.prj) is a single file that manages path, tracked artifacts,

shortcuts, derived-output locations, and health checks. This skill covers the

mechanics so every downstream workflow (requirements, architecture, analysis,

anything else) can rely on a predictable project shape.

Domain skills reuse this skill's helpers (setupProject, registerWithProject)

and conventions (idempotent build scripts, removeFile before delete,

runChecks at the end of buildAll). They may override the living-doc

templates with domain-specific versions.

Creating a project

Use code/setupProject.m to create the project inline

(not as a saved script — the scripts/ folder doesn't exist yet):

setupProject(projectName, projectFolder, subfolders, derivedSubfolders)

• subfolders — cell array of folders that are created, added as tracked

project files, and placed on the MATLAB path. Callers choose the layout.

• derivedSubfolders — cell array of folders for build outputs. Created but

not tracked. The first two entries are wired to SimulinkCacheFolder

and SimulinkCodeGenFolder if supplied, so Simulink cache / codegen stays

out of source control.

Example (MBSE shape):

setupProject("MySystem", "C:\work\MySystem", ...
    {'requirements','architecture','analysis','verification','scripts'}, ...
    {fullfile('derived','cache'), fullfile('derived','codegen')});

Path management rule

**Every tracked folder that is supposed to be on the path must be registered

with both addFolderIncludingChildFiles *and* addPath.** If you only do the

first, runChecks later fails with Project:Checks:ProjectPath ("a folder is

on the MATLAB path but not registered as a project path folder"). setupProject

handles this for the initial folder set; any folder added later must follow the

same pattern.

Why no startup.m

A startup.m is unnecessary when build scripts are idempotent and self-cleaning

(each script clears its own state at the top — see below). Adding one introduces

hidden state that survives between runs and tends to mask bugs. Leave it out.

File lifecycle — tracking, shortcuts, removal

Tracking files as they're created

Use the code/registerWithProject.m helper from

every build script. It is idempotent and a no-op if no project is open:

registerWithProject({fileA, fileB, ...}, {folderA, ...})

Each build script should call this at the end, passing the files it created.

buildAll.m additionally registers all script files. This keeps the project

in sync with the file system without any manual addFile bookkeeping.

Shortcuts

addShortcut(proj, filePath) (no label argument) adds a file to the project's

Shortcuts panel. Add shortcuts progressively as key files are created — typical

targets: the top-level build script, the main model, the primary data file.

Removing tracked files

Always call removeFile before delete when getting rid of a tracked file.

A bare delete() removes the file from disk but leaves a broken reference in

the project, causing runChecks failures:

proj = currentProject();
removeFile(proj, fullfile(archDir, 'OldArtifact.sldd'));  % untrack first
delete(fullfile(archDir, 'OldArtifact.sldd'));             % then remove from disk

This matters whenever a build script replaces an artifact with a new name — the

old tracked entry must be removed explicitly.

Build-script idempotency conventions

Any build script that writes tracked artifacts should follow these rules so

buildAll.m can run any phase in any order without accumulating stale state:

• Clear state at the top. For MATLAB it is often enough to clear nothing

and rely on the delete-and-recreate step. For toolboxes with in-memory

state (e.g. slreq.clear(), Profile.closeAll()), call their reset APIs

as the first action.

• Delete the target artifacts before recreating them. Guard every file

op with isfile / isfolder so the first run (when files don't exist)

and later runs (when they do) take the same path.

• Recreate artifacts from scratch. Never mutate an existing file in place.
• Call registerWithProject at the end, passing every artifact the

script produced. The helper is a no-op if a file doesn't exist, so

conditional artifacts (link-store files that only appear when links are

created) are safe to pass unconditionally.

This pattern is what lets users rebuild everything cleanly by calling

buildAll() — there is no state to undo, just regenerate.

buildAll.m shape

The top-level orchestrator script calls each phase / build script in order,

then registers the script files themselves, then runs project health checks:

%% Register all scripts with the project
scriptsDir = fileparts(mfilename('fullpath'));
scriptFiles = { ...
    fullfile(scriptsDir, 'buildAll.m'), ...
    % ... every other script the project uses ...
    fullfile(scriptsDir, 'registerWithProject.m'), ...
};
registerWithProject(scriptFiles);

%% Project health check
proj = matlab.project.currentProject();
if ~isempty(proj.Name)
    results = runChecks(proj);
    nFail = 0;
    fprintf('\nProject checks:\n');
    for i = 1:numel(results)
        if results(i).Passed
            fprintf('  [PASS] %s\n', results(i).Description);
        else
            fprintf('  [FAIL] %s\n', results(i).Description);
            for j = 1:numel(results(i).ProblemFiles)
                fprintf('           %s\n', results(i).ProblemFiles(j));
            end
            nFail = nFail + 1;
        end
    end
    if nFail == 0
        fprintf('All checks passed.\n');
    else
        fprintf('%d check(s) failed — review output above.\n', nFail);
    end
end

runChecks runs 8 built-in project checks including file existence, path

consistency (Project:Checks:ProjectPath), unsaved files, and SLPRJ folder

placement. The most common failure is Project:Checks:ProjectPath — fix with

addPath(proj, folderPath) on the offending folder.

Living documentation: plan.md and decisions.md

Projects built with this skill carry two hand-curated markdown files at the

project root. They are *not* build outputs — they preserve context a future

reader otherwise couldn't recover from the code alone.

| File | Purpose | Update cadence |

|---|---|---|

| plan.md | Canonical overview: scope, source artifacts, milestone status, open questions, known risks. | At each milestone and whenever scope or constraints change. |

| decisions.md | Append-only log of non-obvious decisions — each with context, options, rationale, revisit trigger. | Append at any checkpoint where the chosen approach wasn't forced by the inputs, and at every rollback. |

Templates live at templates/plan.md and

templates/decisions.md. Copy both into the project

root during setup, fill placeholders, and register them with the project so

they ship with the repo:

proj = currentProject();
addFile(proj, fullfile(proj.RootFolder, 'plan.md'));
addFile(proj, fullfile(proj.RootFolder, 'decisions.md'));

Override for domain skills. Any domain skill (e.g. mbse-workflow) may

ship its own plan.md / decisions.md templates under its own templates/

folder and use those *instead* of the generic ones here. Overrides should

keep the core section order (Overview → Source artifacts → Status → Open

questions → Known risks) so readers moving between projects find familiar

anchors. Add domain-specific sections below the core set.

When to append a decisions entry: only when a judgment call was made.

Mechanical steps and input-forced decisions don't belong. Good examples:

"shortened artifact prefix from full system name to make filenames

manageable"; "split module X into four sub-modules per user preference"; "added

property Y mid-project after initial scope excluded it". Bad examples: "created

the .prj file"; "imported 27 rows from xlsx".

When to skip an entry: bug fixes, API iteration, rerunning a script after

an error, or anything that reflects tooling friction rather than design

judgment.

Quick reference

| Task | Call |

|---|---|

| Create project | setupProject(name, folder, subfolders, derivedSubfolders) |

| Track files/folders after creation | registerWithProject(files, folders) |

| Add a shortcut | addShortcut(proj, filePath) |

| Remove a tracked file | removeFile(proj, path) then delete(path) |

| Ensure folder is on path | addPath(proj, folderPath) |

| Health check | runChecks(proj) (see buildAll.m shape above) |