MATLAB Project Creation

Creates a fully configured MATLAB project from an existing folder of MATLAB code using matlab.project.* APIs via the MATLAB MCP server.

When to Use

• User says "create a project", "set up a MATLAB project", or "initialize project"
• User has a folder of MATLAB files that needs project infrastructure
• Before matlab-create-buildfile — a project must exist first

When NOT to Use

• A MATLAB project already exists (.prj file with resources/project/ folder) — use openProject instead
• User wants to create a toolbox spec — use matlab-define-toolbox-api
• User wants build automation — use matlab-create-buildfile (after the project exists)

Key Functions

| Function | Purpose | |----------|---------| | matlab.project.createProject | Create a new project with specified definition type | | openProject | Open an existing project (fallback if one already exists) | | addFile | Add files to the project | | addPath | Add folders to the project path | | genpath | Generate path string for folder tree (excludes +pkg, @class, private) |

Critical Rules

1. NEVER overwrite existing files. Before creating any file (README.md, etc.), check if it already exists. If it does, skip or ask the user.
2. ALWAYS prompt the user before creating new folders. Present recommended folders in a table with their purpose and wait for confirmation before mkdir.
3. Do NOT move or rename any existing files.

Inputs

| Input | Required | Description | |-------|----------|-------------| | Project path | Yes | Absolute path to the folder to make into a project | | Project name | No | Override auto-detected name (default: inferred from code) |

Workflow

1. Discover Existing Content

• List all files in the project folder (recursively)
• If a .prj file exists, ask the user — it could be a MATLAB project or a legacy deploytool file:

> A) This is a MATLAB project — open it with openProject instead of creating a new one > B) This is a legacy deploytool file — proceed with creating a new MATLAB project

• Read Contents.m if present — it provides authoritative function descriptions and categorization
• If no Contents.m, read the H1 line (first % comment) of each .m file to understand purpose
• Identify file types: .m (functions/scripts), data (.mat, .dat, .csv), text (.txt), images (.png, .jpg), other
• Identify any existing subfolders

2. Determine Project Identity

Based on the code analysis:

• Name: Derive from Contents.m title line, folder name, or dominant theme of functions
• Description: 1–3 sentence summary covering the scope, domain, and purpose of the code

3. Create the MATLAB Project

Use MATLAB MCP (mcp__matlab__evaluate_matlab_code) to execute:

matlab
proj = matlab.project.createProject("Folder", '<projectFolder>', ...
    "Name", "<inferred name>", ...
    "DefinitionType", "FixedPathMultiFile");
proj.Description = "<generated description>";

Why FixedPathMultiFile: Produces a .prj + resources/project/ structure that is SCM-friendly (isolated XML files, no merge conflicts). This is the target format for toolbox projects.

4. Add All Existing Files

Add every file in the project folder to the project. Process by extension category:

matlab
% Add .m files
mFiles = dir(fullfile(proj.RootFolder, '*.m'));
for i = 1:numel(mFiles)
    addFile(proj, fullfile(mFiles(i).folder, mFiles(i).name));
end

% Repeat for data/text/image/other file extensions found
% Also recursively add files from any existing subfolders

Important: Use dir(..., '**', '*.<ext>') for recursive discovery in subfolders.

5. Configure Project Path

Add folders to the project path based on layout:

matlab
% Determine path root based on project layout
if isfolder(fullfile(proj.RootFolder, "toolbox"))
    % toolbox/ layout — only toolbox content goes on path
    % (project root, tests/, buildUtilities/ stay OFF the path)
    pathRoot = fullfile(proj.RootFolder, "toolbox");
else
    % Flat layout — all subfolders go on path
    pathRoot = proj.RootFolder;
end

allFolders = strsplit(genpath(pathRoot), pathsep);
for i = 1:numel(allFolders)
    if ~isempty(allFolders{i}) && ~contains(allFolders{i}, filesep + "internal")
        addPath(proj, allFolders{i});
    end
end

Why this logic: genpath already excludes +pkg/, @class/, private/, and dot-folders — but NOT internal/ folders. The internal/ folder uses MATLAB's scoping convention: functions inside are only visible from the parent folder, never from the global path. The filter above ensures internal/ is never added via addPath. When toolbox/ exists, only its contents should be on the MATLAB path — this matches what end users get when the toolbox is installed. If toolbox/ doesn't exist yet (flat layout), adding root and subfolders is correct since the user's code lives at root.

If the user later adopts toolbox/ (via Step 7), the path should be reconfigured — suggest re-running this skill or manually adjusting path entries.

6. Create README.md

Only if README.md does not already exist at the project root.

Generate a README.md containing:

• Project title (H1)
• Description paragraph
• Project organization overview
• Function table grouped by category (GUI demos, algorithm implementations, utilities, data files, etc.)
• Each row: | function_name | one-line description |
• Getting Started section (how to open/use the project)
• License/copyright note if license.txt or copyright info exists

Add the README.md to the project after creation:

matlab
addFile(proj, fullfile(proj.RootFolder, 'README.md'));

7. Suggest Best-Practice Folders

Based on mathworks/toolboxdesign conventions, present the user with a table of recommended folders:

| Folder | Purpose | |--------|---------| | tests/ | Unit tests using the MATLAB Testing Framework | | examples/ | Live Script examples and tutorials | | doc/ | Documentation (e.g., GettingStarted.m) | | toolbox/ | Distributable content separated from dev infrastructure |

ASK the user which (if any) they want created. Do not create them without confirmation. Present as lettered options: > A) All — create all recommended folders > B) Select — pick specific folders (e.g., "tests and examples") > C) Skip — don't create any new folders

When confirmed, create the folders and add them to the project path:

matlab
mkdir(fullfile(proj.RootFolder, '<folderName>'));
addPath(proj, fullfile(proj.RootFolder, '<folderName>'));

8. Final Verification

Run a summary check:

matlab
proj = currentProject;
disp("Name: " + proj.Name);
disp("Files: " + numel(proj.Files));
disp("Path entries: " + numel(proj.ProjectPath));

Report the final state to the user.

Error Handling

• If matlab.project.createProject fails because a project already exists, use openProject instead and inform the user
• If addFile fails for a specific file (e.g., it's already tracked), catch and continue
• If addPath fails for a folder, catch the error and report which folder was skipped

Output

Provide the user with:

1. Confirmation that the project was created
2. Project name, description, file count, and path entries
3. Location of the .prj file for opening in MATLAB
4. The recommended-folders prompt (Step 7)

Next Steps

• /matlab-document-toolbox — generate README, function signatures, GettingStarted guide, and examples
• /matlab-create-buildfile — define the build plan with code checks, tests, and packaging tasks

Copyright 2026 The MathWorks, Inc.