AGENT SKILL

matlab-define-toolbox-api

Scan a folder, triage files into include/exclude, identify the public API, and produce a toolboxSpecification.m Interface Spec — all in one pass. Use when turning loose code into a toolbox.

License 许可
BSD-2-Clause
最近更新
2026-11-14
Stars
★ 12
Forks
5

01 前言 Front Matter

name
matlab-define-toolbox-api
license
MathWorks BSD-3-Clause
metadata
{ "author": "MathWorks", "version": "1.0" }
description
Scan a folder, triage files into include/exclude, identify the public API, and produce a toolboxSpecification.m Interface Spec — all in one pass. Use when turning loose code into a toolbox.

02 资源文件 3

03 SKILL.md 正文

matlab-define-toolbox-api — Toolbox Scope & Spec Generator

You take a folder of code, figure out what belongs in the toolbox, identify the public API, and produce the Interface Spec — the contract defining what the toolbox exposes. One skill, one artifact.

When to Use

  • User wants to turn code into a toolbox
  • User points at a folder and says "make this a toolbox" or "package this"
  • User has a mix of scripts, functions, tests, data, and scratch files
  • Starting the files-to-package pipeline from scratch

When NOT to Use

  • Adding files to an existing spec — edit buildUtilities/toolboxSpecification.m directly
  • Analyzing dependencies — use matlab-analyze-dependencies after the spec is approved
  • Building the .mltbx package — use matlab-build-toolbox
  • Documenting the toolbox — use matlab-document-toolbox

Key Functions

Function Purpose
dir Recursive file listing for inventory
which Resolve function locations on path
exist Check whether a name resolves to a file, folder, or built-in
matlab.codetools.requiredFilesAndProducts Trace caller/callee relationships for Support classification

Inputs

Input Required Description
path No Folder or list of files to analyze. If not provided, prompt the user.
purpose No What the toolbox does and who uses it. If not provided, prompt the user.

Workflow

Step 1 — Gather Inputs

If path is not provided:

What folder or files would you like to package as a toolbox?

If purpose is not provided:

In a sentence or two, what does this toolbox do? Who will use it?

Do not proceed until both are provided.

Step 2 — Inventory the Folder

Scan the path recursively. Classify every file:

Category Detection Rule
Function .m file with function keyword on first non-comment line
Class .m file with classdef keyword
Script .m file with no function/classdef keyword
Live Script .mlx file
Test In tests//test/ folder, or name matches *Test.m, *_test.m, test_*.m
Data .mat, .csv, .xlsx, .json, .xml (non-config)
Config/Meta buildfile.m, projectStartup.m, Contents.m, .prj, resources/
Scratch/Temp In scratch/, tmp/, or names like untitled*.m, Copy_of_*
Other READMEs, images, licenses, etc.

Step 3 — Classify Relevance

Using the purpose as guide, classify each file:

  • Include — directly serves the toolbox's stated purpose
  • Support — needed by included files (helper/utility called internally)
  • Exclude — not relevant (tests, scratch, unrelated code)
  • Uncertain — needs user input

Heuristics:

Signal Disposition
Function name aligns with purpose keywords Include
H1 text mentions concepts from purpose Include
Called by an included file Support
In private/ or +internal folder Support
Test file for an included function Exclude
Script with no connection to purpose Exclude
Data file referenced by included code Include
Scratch/temp naming pattern Exclude

Step 4 — Identify Public API

From the Include set, determine visibility:

Signal Classification
Has H1 help text Likely public
Has arguments block or input validation Likely public
Descriptive action-oriented name Likely public
Classdef with public methods Public
Called by others but not standalone Internal
In private/ or generic utility name Internal
Script Example/entry point

Step 5 — Present Report & Get Confirmation

Display a combined scope + API report:

## Toolbox Scope & API — [Name]

**Purpose:** [user's stated purpose]
**Source:** [path]
**Total files:** N

### Public API (N functions)
| Function | Signature | H1 | Category |
|----------|-----------|-----|----------|

### Internal Support (N files)
| File | Type | Reason |
|------|------|--------|

### Excluded (N files)
| File | Reason |
|------|--------|

### Uncertain — Need Your Input
| File | Why Uncertain |
|------|--------------|

Then ask:

Please review:

  1. Should any excluded files be included?
  2. Should any included files be removed?
  3. For uncertain files — include or exclude?
  4. Is the public API surface correct?
  5. What categories should functions be grouped into? (e.g., "Analysis", "I/O", "Visualization")

Incorporate feedback before proceeding.

Step 6 — Generate Interface Spec

Produce toolboxSpecification.m using scripts/toolboxSpecificationTemplate.m as the structure. spec.entries is a cell array (not a struct array) because classdef entries have extra fields (methods, properties) that function entries lack — MATLAB cannot concatenate structs with mismatched fields. Access entries via spec.entries{i}. Each entry has a "type" field — either "function" or "classdef". See the template for the full field conventions for both types.

Save to buildUtilities/toolboxSpecification.m in the project root (create the folder if needed). This folder is excluded from the toolbox package via toolbox.ignore or package.ignore.

Output

  • Single artifact: buildUtilities/toolboxSpecification.m — executable spec as a MATLAB struct
  • Display: Markdown report shown during the session for review
  • Downstream: Other skills (matlab-assess-toolbox, matlab-build-toolbox, matlab-analyze-dependencies) consume toolboxSpecification.m

Checkpoint

This skill always pauses for user approval at Step 5. The user must confirm scope and public API before the spec is generated. Nothing is written until confirmation.

Key Rules

  • Always prompt if inputs are missing. Never guess the path or purpose.
  • Every file is accounted for. Nothing is silently dropped — files are included, excluded (with reason), or flagged as uncertain.
  • Purpose drives classification. The user's stated intent is the primary filter.
  • Uncertain is valid. Surface ambiguity rather than guessing wrong.
  • Reasons are mandatory. Every include/exclude decision has a stated reason.
  • Tests are excluded but acknowledged. They're handled by matlab-assess-toolbox later.
  • Scripts become examples. Files without function keyword are examples/entry points, not public API.
  • User decides visibility. Heuristics suggest, user confirms.
  • One artifact, build utilities. Only toolboxSpecification.m is written, to buildUtilities/ — keeps source clean and is excluded from the packaged toolbox.

Next Steps

  • /matlab-analyze-dependencies — resolve external dependencies identified in the Interface Spec
  • /matlab-create-project — organize files into a MATLAB project using the spec as a guide

Copyright 2026 The MathWorks, Inc.


04 同仓库更多 Skills

stanfish06
stanfish06/skillquarium

zarr-python

Stores and queries chunked N-D scientific arrays with Zarr-Python 3, including codecs, sharding, S3/GCS storage, and NumPy/Dask/Xarray integration. Use for array layout, bounded I/O, format migration, or scientific metadata preservation.

★ 12
stanfish06
stanfish06/skillquarium

yeet

Publish local changes to GitHub by confirming scope, committing intentionally, pushing the branch, and opening a draft PR through the GitHub app from this plugin, with `gh` used only as a fallback where connector coverage is insufficient.

★ 12
stanfish06
stanfish06/skillquarium

xarray

N-dimensional labeled arrays and datasets in Python. Built on top of NumPy and Dask. It introduces labels in the form of dimensions, coordinates, and attributes on top of raw NumPy-like arrays, making data analysis in physical sciences more intuitive and less error-prone. Use for working with multi-dimensional scientific data, NetCDF/GRIB/Zarr files, climate/weather/oceanographic datasets, remote sensing, geospatial imaging, large out-of-memory datasets with Dask, and labeled array operations.

★ 12
stanfish06
stanfish06/skillquarium

writing-mstest-tests

Use when asked to fix, rewrite, update, improve, modernize, show corrected code for, or explain existing MSTest tests or MSTest-specific configuration. Use for "review" when corrected code or edits are wanted, even for one pasted assertion or passing tests with bad failure output. Covers expected/actual labels; generic Boolean, collection, string, numeric, null, identity, exception, hard-cast, and object[] checks; TestContext/lifecycle; timeout/cancellation; OS/CI conditions, retry, cleanup, parallelization, MSTest.Sdk project setup, and MSTESTxxxx. Honor the installed MSTest version. DO NOT USE to design new test cases (code-testing), perform report-only audits, create project files rather than explain MSTest setup, run tests, migrate frameworks, or handle non-MSTest/non-.NET code.

★ 12
stanfish06
stanfish06/skillquarium

wgs-prs

End-to-end WGS to polygenic risk score pipeline. Takes paired-end FASTQ files (or a pre-existing VCF) through nf-core/sarek for variant calling, applies VCF QC (normalisation, hard filtering, Ti/Tv and Het/Hom checks), then computes polygenic risk scores via the PGS Catalog. Fills the FASTQ to VCF gap upstream of the gwas-prs skill.

★ 12
stanfish06
stanfish06/skillquarium

webapp-testing

Toolkit for interacting with and testing local web applications using Playwright. Supports verifying frontend functionality, debugging UI behavior, capturing browser screenshots, and viewing browser logs.

★ 12