jblanco89/matlab-mlx-docs-skill
matlab-mlx-docs-skill
UnverifiedCreates custom binary MATLAB Live Code (.mlx) documents programmatically for MATLAB R2024a by authoring the OPC/WordprocessingML package directly — text, headings, LaTeX equations, code cells, and embedded images — then packing, structurally verifying, and word-counting them with bundled PowerShell scripts. Use when the user asks to generate a .mlx report, paper, or notebook with equations and figures for MATLAB R2024a, or to build a .mlx without the Live Editor. Do NOT use for R2025a+ plain-text .m live scripts (use matlab-create-live-script).
Write MLX Docs (custom)
Author binary MATLAB Live Code documents (.mlx) for MATLAB R2024a by hand-crafting the OPC package, then validate with the bundled PowerShell scripts. Every step and gotcha below was empirically verified on MATLAB R2024a Update 6.
When to Use
- User wants a .mlx paper, report, or notebook with LaTeX equations and embedded figures
- User needs a .mlx for MATLAB R2016a–R2024a that cannot use the R2025a+ plain-text live format
- User wants reproducible, script-driven .mlx generation with verification
When NOT to Use
- R2025a+ plain-text
.mlive scripts — usematlab-create-live-script(different format) - Editing an existing .mlx in place — open/saveAs in MATLAB instead
- Regular
.mscripts or function files
Instructions
Follow the steps in order. Each step ends in a check you can re-run with the bundled scripts.
Step 1: Plan the document
Define: title, sections, equations (LaTeX source), code cells, image files, and references. Respect the word budget: body text ≤ 1000 words, excluding references, code cell, equations, and images (headings/captions count).
Step 2: Author matlab/document.xml
WordprocessingML in the w namespace. One <w:p> per block. See references/mlx-format.md for exact markup:
- Title:
<w:pPr><w:pStyle w:val="title"/></w:pPr> - Text:
<w:pStyle w:val="text"/>(+ optional<w:jc w:val="center"/>) - H1 heading:
<w:pStyle w:val="heading"/> - H2 heading:
<w:pStyle w:val="heading2"/>wrapped inmc:AlternateContentwithRequires="R2018b"and anmc:Fallbacktoheading(do not copy this by hand — copy the exact block fromreferences/mlx-format.md) - Equation:
<w:customXml w:element="equation">with<w:attr w:name="displayStyle" w:val="true"/>and LaTeX in<w:t> - Image:
<w:customXml w:element="image">withheight,width,verticalAlign,altText,relationshipIdattrs - Code cell:
<w:pStyle w:val="code"/>with<w:t><![CDATA[...]]></w:t> - Trailing section break:
<w:p><w:pPr><w:sectPr/></w:pPr></w:p>
Use literal-text tools (Write/Edit) — never Bash heredocs, which collapse \\ to \ and corrupt LaTeX. Escape XML entities (<, >, &) in body text.
CRITICAL: The entire matlab/document.xml MUST be a single line after the XML declaration (no newlines between <w:p> elements). MATLAB R2024a's Live Editor importer silently discards content if newlines are present between paragraphs — the file opens but saveAs produces an empty 235-byte shell. Use literal-text tools (Write/Edit) with no newline separators; never Bash heredocs or multi-line writes. Escape XML entities (<, >, &) in body text.
Step 3: Assemble the package
Copy the skeleton from assets/package-skeleton/, then:
- Place your authored
matlab/document.xml - Put images at
media/image1.png,media/image2.png, ... - Add one
<Relationship>per image inmatlab/_rels/document.xml.rels, with INCREMENTING Ids starting atrId10(rId10,rId11, ...) and matchingTarget="../media/imageN.png"andType="http://schemas.mathworks.com/matlab/code/2013/relationships/image" - Keep exactly 3 metadata files:
metadata/coreProperties.xml,metadata/mwcoreProperties.xml,metadata/mwcorePropertiesExtension.xml
CRITICAL: do NOT add metadata/mwcorePropertiesReleaseInfo.xml — a heading plus that R2019b file hangs the R2024a editor with MATLAB:Editor:Document:OpenLoadTimeout. MATLAB re-adds it harmlessly on saveAs.
Step 4: Pack
Run:
powershell scripts/pack-mlx.ps1 -SourceDir <package-folder> -OutputMlx <out.mlx>
Zip entry names MUST use forward slashes. The script enforces this. If <out.mlx> already exists, pass -Force to overwrite it — never point -OutputMlx at a file outside the user's workspace, and never run the script against a -SourceDir outside the workspace without explicit user confirmation.
Step 5: Verify structure
Run:
powershell scripts/verify-mlx.ps1 -MlxPath <out.mlx>
Confirms: valid zip, forward-slash entries, required files present, ReleaseInfo absent, correct Content_Types overrides and .rels, well-formed XML (no DTD/XXE), unique image rels that resolve, and element counts (title/heading/heading2/text/code/equation/image/sectPr).
To inspect an existing .mlx (e.g. to edit or diagnose one), unpack it first:
powershell scripts/unpack-mlx.ps1 -MlxPath in.mlx -DestDir <folder> # add -Force to overwrite a non-empty folder
unpack-mlx.ps1 refuses to overwrite an existing non-empty -DestDir without -Force, and rejects zip entries that try to escape the destination (zip-slip).
Step 6: Count words
Run:
powershell scripts/count-words.ps1 -DocumentXml <package-folder>\matlab\document.xml
Confirms body ≤ 1000 words, excluding code cell, equations, images, and the references section.
Step 7: Open in MATLAB and normalize (if MATLAB is attached)
ed = matlab.desktop.editor.openDocument('path\out.mlx'); % must open fast (< ~1 s)
disp(numel(ed.Text)); % code cell text
ed.saveAs('path\normalized.mlx'); ed.closeNoPrompt;
The saveAs round-trip normalizes the package (renumbered rels, ReleaseInfo re-added). Deliver the normalized copy. If openDocument hangs, fix the package per Troubleshooting.
Examples
Example 1: Minimal paper
User: "Crea un .mlx con título, una ecuación y una figura."
Actions: author document.xml (title → equation \frac{dx}{dt} = \sigma (y - x) → image), assemble package with 1 image, pack, verify, count words, open+saveAs in MATLAB.
Result: a valid .mlx that opens in the R2024a Live Editor showing the rendered equation and figure.
Common Issues
MATLAB:Editor:Document:OpenLoadTimeout (hang on open)
Cause: metadata/mwcorePropertiesReleaseInfo.xml present together with any heading.
Solution: delete that file from the package and repack (keep 3-metadata skeleton).
Modal dialog / hang after sim or open
Cause: backslash in a zip entry name (matlab\document.xml).
Solution: repack with pack-mlx.ps1 (forward slashes) and re-verify.
Images don't show
Cause: relationshipId in document.xml doesn't match the Id in matlab/_rels/document.xml.rels, or Target wrong.
Solution: check verify-mlx.ps1 output for unresolved image rels.
Word count over budget
Cause: references/equations/code counted.
Solution: count-words.ps1 excludes those categories; trim prose to ≤ 1000 body words.
Empty document after saveAs (content silently dropped)
Cause: matlab/document.xml contains newlines between <w:p> elements. MATLAB R2024a's Live Editor importer requires the entire document body to be a single line after the XML declaration. If newlines are present, the file opens but content is silently discarded — saveAs yields an empty 235-byte shell.
Solution: ensure matlab/document.xml is a single line (XML declaration on line 1, all body content on line 2). Use Write/Edit tools with no newline separators; avoid multi-line writes or Bash heredocs. Verify with verify-mlx.ps1 and a quick open+saveAs test.
Checklist
-
pack-mlx.ps1succeeds (forward slashes) -
verify-mlx.ps1all PASS (no ReleaseInfo, counts sane) -
count-words.ps1body ≤ 1000 words - Opens fast in MATLAB;
saveAsround-trip delivered
Path safety
- Keep
-OutputMlx/-DestDir/-SourceDirinside the user's workspace unless they explicitly ask otherwise unpack-mlx.ps1refuses to overwrite an existing non-empty-DestDirunless-Forceis given (with-Forceit deletes that directory's contents — confirm before doing so)pack-mlx.ps1refuses to overwrite an existing-OutputMlxunless-Forceis givenverify-mlx.ps1andcount-words.ps1are read-only;count-words.ps1rejectsdocument.xmlfiles containing a<!DOCTYPE>(XXE risk)- Relative paths resolve against the caller's current directory — prefer absolute workspace paths
References
references/mlx-format.md— exact OPC/WordprocessingML markup, copied blocks for heading2/equation/imagereferences/version-compat.md— which .mlx features need which MATLAB release
Copyright 2026 Javier Blanco
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| deprecation-and-migrationaddyosmani/agent-skillsManages deprecation and migration. Use when removing old systems, APIs, or features. Use when migrating users from one implementation to another. Use when migrating a database schema in production, such as renaming or dropping a column without downtime (expand/contract). Use when deciding whether to maintain or sunset existing code. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| performance-optimizationaddyosmani/agent-skillsOptimizes application performance across frontend, backend, queries, and databases. Use when performance requirements exist, when you suspect performance regressions, when Core Web Vitals or load times need improvement, when N+1 query patterns need fixing, or when profiling reveals bottlenecks. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| Agent Cost Reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json. | Stars: 117k | Updated | Claude CodeCodex | Unverified | Install |
| Agent Cost Reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json. | Stars: 117k | Updated | Claude CodeCodex | Unverified | Install |