---
name: markdownto-matrix
description: Author, repair, validate, and review portable matrix documents and their rendered results.
---
# Working with matrix

Use this skill when the user wants the matrix workflow. Read [SPEC.md](SPEC.md), then [shared conventions](../conventions.md). Published equivalents live at https://markdownto.ai/specs/matrix.md and https://markdownto.ai/specs/conventions.md. The spec and fixtures govern conformance; this editorial guidance is non-normative and adapts to the user's brief.

## Author and repair

Confirm the purpose from the request, inspect any supplied references, and preserve supplied content and constraints. Start from a relevant valid fixture, not a remembered grammar. Write the envelope and meaningful `##` sections, then sparse direction. Avoid invented IDs. Run `mdto validate file.md` after edits. Repair diagnostics at their reported location using the spec's rationale; preserve unrelated source. Prefer the spec-owned verbs for state changes and preview their diff when useful. If the CLI is unavailable, perform a clearly labeled manual check against the spec and do not claim tool validation.

## Editorial judgment

Begin with the actual decision and realistic alternatives. Criteria should be distinct and understandable, with explicit score anchors. Separate evidence from judgments and never imply the weighted result is objective truth. All scores are benefits: explain any transformation from raw costs or risks. Ask how much each criterion matters, normalize through the specified formula, and inspect sensitivity by varying one weight. If small plausible weight changes reverse the ranking, explain the fragility. Do not manufacture missing values. Show ties honestly and retain the original options when results are close. Verify arithmetic against a hand calculation and check that downloads preserve the weights you adjusted.

## Review and delivery

Use `mdto render file.md` and the spec's build or review verbs. Inspect the actual resulting interface or artifact, including mobile/narrow views, keyboard controls and content extremes. Verify state-changing UI actions against the same CLI operations. Deliver the Markdown and usable output, explain any real limitation, and never equate a valid file with a successful artifact review. If artifact inspection is unavailable, say which checks remain undone.