Matlab Create Live ScriptSAFE

The MATLAB Agentic Toolkit brings proven MATLAB capabilities to AI agents, making engineering and scientific workflows agent-ready.

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: matlab-create-live-script
description: Create, edit, and run plain-text MATLAB live scripts (.m files) with rich text formatting, LaTeX equations, section breaks, and inline figures. Use when generating tutorials, analysis notebooks, reports, documentation, or educational content, when modifying existing live scripts, or when converting existing binary .mlx files to .m for version control. Requires R2025a+.
license: https://www.mathworks.com/content/dam/mathworks/license/pmrl/license.md
metadata:
  author: MathWorks
  version: "2.2"
---

# Live Scripts

Plain-text `.m` files that render as rich documents in the MATLAB Live Editor. Version-control friendly — never use binary `.mlx`.

## When to Use

- Tutorials, reports, analysis notebooks, or documentation
- Interactive exploration with inline figures and equations
- Version-controlled content (plain-text `.m`, not binary `.mlx`)
- Converting an existing binary `.mlx` file to plain-text `.m`

## When NOT to Use

- Regular scripts without rich formatting
- Function files
- MATLAB older than R2025a

## Converting from `.mlx`

To convert a binary `.mlx` file to a plain-text `.m` live script, run the following at the MATLAB Command Window. The recipe is **not** part of the resulting `.m` file:

```matlab
editor = matlab.desktop.editor.openDocument(mlxPath, Visible=0);
editor.saveAs(newMPath);  % use .m extension
editor.closeNoPrompt;
```

## Rules

- Text lines use `%[text]` — NOT bare `%`
- One paragraph = one `%[text]` line — do not hard-wrap; let the Live Editor handle line width
- No empty `%[text]` lines — they render as unwanted blank space
- Section headers: `%%` on its own line, then `%[text] ## Title` on next line
- No blank lines in the file, except a single blank line directly before `%[appendix]`
- No `figure` command — implicit figure creation only
- No more than one plot per section (unless using tiled layouts)
- No `close all` or `clear`
- No `mfilename` — does not work as intended in live scripts. Hardcode filenames or use `pwd`.
- Escape these characters when used as **literal text** (not as markdown syntax): `*`, `_`, `[`, `]`, `` ` ``, `\`. Also escape `.` after a digit and `#` at line start.
- Equations use single-`$` inline form only: `$ a = \\pi r^2 $` (no `$$ ... $$`). For a centered/display equation, wrap the line: `%[text]{"align":"center"} $ X(k) = \\sum\_{n=0}^{N-1} x(n) e^{-j2\\pi kn/N} $`
- Inside an equation, LaTeX commands take double backslashes (`\\sin`, `\\frac`, `\\pi`) and markdown characters take single (`\_`, `\*`). Use a tool that takes literal text (Edit, Write, fwrite) — **don't** use Bash heredocs; they collapse `\\` to `\` even when quoted, which corrupts LaTeX equations.
- Last list item (bulleted or numbered) ends with `\`
- Every file ends with the required appendix
- Avoid `fprintf` — drop the semicolon or use `disp()`. Output appears inline below the code that produced it, not in the Command Window.
- Outputs should serve the reader's understanding, not verify execution

## Required Appendix

Every live script must end with:

```matlab
%[appendix]{"version":"1.0"}
%---
%[metadata:view]
%   data: {"layout":"inline"}
%---
```

## Reading live scripts (Token Optimization)

When reading a live script file, ignore everything below the `%[appendix]` marker. The appendix contains embedded images and metadata that consume tokens without adding useful information. All code and text content appears before it.

## Format Reference

| Syntax | Renders as |
|--------|-----------|
| `%%` | Section break |
| `%[text] # Title` | H1 heading |
| `%[text] ## Section` | H2 heading |
| `%[text] **bold**` | **Bold** |
| `%[text] *italic*` | *Italic* |
| `` %[text] `code` `` | `Monospace` |
| `%[text] <u>text</u>` | Underlined text |
| `%[text] $ a = \\pi r^2 $` | Inline equation |
| `%[text]{"align":"center"} $ ... $` | Centered/display equation |
| `%[text] - item` | Bullet |
| `%[text] - last \` | Last bullet |
| `%[text] 1. item` | Numbered list |
| `%[text] 2. last \` | Last numbered item |
| `%[text] [text](url)` | External hyperlink |
| `%[text] [text](internal:id)` | Internal link to an anchor |
| `%[text] %[text:anchor:id] ...` | Anchor (link target) |
| `%[text:tableOfContents]{"heading":"..."}` | Table of Contents |

**IDs (anchors, and any other id-bearing element):** letters, digits, and underscores only. No hyphens — `my-section` won't bind; use `my_section`. For anchors, place the marker immediately after `%[text]` at the start of the line.

### Tables

```matlab
%[text:table]
%[text] | Method | Result |
%[text] | --- | --- |
%[text] | Trapezoidal | 1.9998 |
%[text:table]
```

## Example

```matlab
%[text] # Sinusoidal Signals
%[text] Examples of sinusoidal signals in MATLAB.
%[text:tableOfContents]{"heading":"Contents"}
%[text] - sine waves
%[text] - cosine waves \
x = linspace(0,8*pi);
%%
%[text] ## Sine Wave
plot(x,sin(x))
title('Sine Wave')
xlabel('x (radians)')
ylabel('sin(x)')
grid on
%%
%[text] ## Cosine Wave
plot(x,cos(x))
title('Cosine Wave')
xlabel('x (radians)')
ylabel('cos(x)')
grid on
%%
%[text] ## Summary
%[text] The sine and cosine functions are $ \\pi/2 $ radians out of phase.

%[appendix]{"version":"1.0"}
%---
%[metadata:view]
%   data: {"layout":"inline"}
%---
```

## Common Patterns

### Mathematical Explanations with Equations

```matlab
%[text] ## Theory
%[text] The discrete Fourier transform is defined as:
%[text]{"align":"center"} $ X(k) = \\sum\_{n=0}^{N-1} x(n) e^{-j2\\pi kn/N} $
%[text] where $ x(n) $ are the time-domain samples and $ k $ indexes the frequency bins.
```

### Code with Inline Comments

```matlab
%%
%[text] ## Data Processing
%[text] Load and filter the data, then visualize the results.
data = load('measurements.mat');
filtered = lowpass(data, 0.5);  % Apply lowpass filter
plot(filtered)
title('Filtered Data')
```

### Tiled Layouts for Comparison

Use only when side-by-side comparison is important to the illustration:

```matlab
%%
%[text] ## Comparis

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (1)

executeLiveScript.p

Gates applied: no_behavioural_pass.