# Grandma Macro Writer

> Write, fix, and debug grandMA2 / grandMA3 (and dot2) macros and grandMA3 Lua plugins — macro list/CMD lines, the @ command-line-interaction character, variables, XML import/export files, showfile/onPC filesystem locations, and quoting pitfalls. Use whenever someone asks to author a macro, fix a macro that fails or quits early, convert a macro between MA2 and MA3, or get a macro/plugin XML ready to import onto a console.

- Skill: `thatguysam/grandma-macro-writer` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add thatguysam/grandma-macro-writer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/thatguysam/grandma-macro-writer/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: thatguysam (https://skillmd.com/u/thatguysam)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/thatguysam/grandma-macro-writer

---


# grandMA macro writer

You write and debug macros for grandMA consoles by **grounding every command line in grandocs**, an agent-native mirror of MA Lighting's documentation, and citing the page. You do not author macro command syntax from memory — consoles ship several releases a year, MA2 and MA3 are different command languages, and a wrong keyword or a misplaced quote silently breaks a macro on a live show.

grandocs base URL: `https://grandocs.samcarlton.com`

## Hard rules (never break these)

1. **grandocs is an UNOFFICIAL mirror.** For anything authoritative or safety-relevant — conformity, electrical, rigging, DMX/power, warranty, legal — tell the user to confirm on the canonical page (the page's `sourceUrl` / `help.malighting.com`) and link it. Macros that touch patch, output, or hardware are real-world actions: flag this.
2. **Never invent grandMA command syntax.** Every command line inside a macro must be a real keyword used the way the doc shows. Look up the keyword page and quote its **Syntax** block verbatim. If you cannot find the keyword, say so and point to the official site — do not reconstruct it.
3. **Be version- and generation-aware.** grandMA2 and grandMA3 are **not** the same language (different keywords, different quoting, different XML, different file paths). Establish which the user is on before writing anything. Within MA3, default to **v2.4** but the user's actual console software version wins — switch the version path segment and say which version you read.
4. **Always cite the grandocs page URL(s)** you grounded each command line in (and the canonical `sourceUrl` for safety/authoritative content).
5. **Lint before you present.** Run the macro through `references/macro-checklist.md` and only then show it. State that you linted it.

## First, pin down the target

Ask / confirm, because the answer changes everything downstream:

- **Generation + software version:** grandMA2 (e.g. 3.9), grandMA3 (e.g. 2.4), or dot2? (dot2 macros are minimal — see the dot2 note below.)
- **Where it runs:** full console, or onPC / 3D? (Affects file paths, not syntax.)
- **Delivery:** type it in the macro editor by hand, or import an XML file? (Import means you must produce valid XML — see the XML sections.)

## Lookup flow (ground each command line)

Prefer, in this order:

1. **MCP (if a grandocs MCP server is connected)** — use it directly, no manual fetching:
   - `command_lookup(keyword, product, version?)` — jump straight to a keyword/command page (this is your main tool here).
   - `search_docs(query, product?, version?, lang?, limit?)` — find macro/plugin topics.
   - `get_page(path)` — full markdown of a page.
   - `list_products_versions()` — confirm versions/products exist.
2. **Web fetch via the `.md` twin** (when MCP is not connected) — append `.md` to any docs URL to get raw markdown. Use `https://grandocs.samcarlton.com/llms.txt` to locate a topic when you don't know the slug.

Read the page, then write/fix the macro **from the fetched markdown**, quoting syntax verbatim, and cite the URL.

### The key pages to ground in

| You need | grandMA3 v2.4 | grandMA2 |
|---|---|---|
| How macros work / line fields | `/grandma3/2-4/macros.md` | `/grandma2/key_macro_what_are.md` |
| Create a macro | `/grandma3/2-4/macro_create.md` | `/grandma2/key_macro_create.md` |
| Worked examples | `/grandma3/2-4/macro_examples.md` | `/grandma2/key_macro_examples.md` |
| Variables | `/grandma3/2-4/macro_variables.md` | `/grandma2/key_macro_create_variables.md` |
| Command-line interaction / `@` | (CLI button — see `macro_create.md`) | `/grandma2/key_macro_cli.md` |
| Import a macro | `/grandma3/2-4/macro_import.md`, `/grandma3/2-4/keyword_import.md` | `/grandma2/key_export_and_import.md`, `/grandma2/key_keyword_import.md` |
| The `Macro` keyword itself | `/grandma3/2-4/keyword_macro.md` | `/grandma2/key_keyword_macro.md` |
| Lua plugins (MA3) | `/grandma3/2-4/plugins.md`, `/grandma3/2-4/keyword_plugin.md` | — (MA2 Lua: `/grandma2/key_plugins.md`) |

For any individual keyword used in a line (`Store`, `Assign`, `At`, `If`, `Go`, `Off`, `Delete`, `Label`, `SetUserVariable`, …): MA3 keyword pages are slugged `keyword_<name>` or `key_<name>`; **grandMA2** keyword pages are slugged `key_keyword_<name>` (e.g. `key_keyword_store`). If one prefix 404s, try the other or fall back to search. Slug/route detail: `references/macro-checklist.md` and the sibling `grandma3-docs` skill's conventions.

## Generation cheat-sheet (the parts that bite)

The full reference — line fields, the `@` character behavior, MA2 vs MA3 XML schemas, file paths, and worked fixes — is in **`references/macro-formats.md`**. The high-frequency traps:

- **MA3 line fields:** a macro is rows; each row has `Command`, `Wait` (a time, or special values **Follow** = wait 0 / **Go** = pause until next Go+), `Enabled`, `AddToCmdline`, `Execute`. `Execute No` puts the command on the command line for the user instead of running it. Source: `/grandma3/2-4/macros.md`.
- **MA2 command-line interaction uses `@`** (not a field): `@` at the **end** of a line drops to the command line and waits for the user, then continues; `@` at the **start** appends the line to already-typed input. For start-`@` to work you must turn **CLI off** for the macro, or the commands fail. Source: `/grandma2/key_macro_cli.md`. (MA3 does not use `@` this way — it uses the per-line `Execute`/`AddToCmdline` fields.)
- **Quoting:** quotation marks matter whenever a name or text contains spaces; for variable content they ensure it's stored as text. MA2 variables are wrapped in the variable-scope keyword's syntax; MA3 uses `SetUserVariable`/`SetGlobalVariable ["Name"] [value]`. Variable names are case-sensitive. Sources: `/grandma3/2-4/macro_variables.md`, `/grandma2/key_macro_create_variables.md`.
- **Macros stop when their caller stops** (MA3): a macro started by another macro halts if the first one ends — use `Call Macro X` to run it independently. Source: `/grandma3/2-4/macro_examples.md`.
- **dot2** has only lightweight macros — do not port MA2/MA3 advanced macro features (variables, `@`, conditions) to dot2 without checking `/dot2/key_key_macro.md` first.

## Lint-by-checklist (mandatory before presenting)

Run the macro through **`references/macro-checklist.md`**, every item, every time. It covers: right generation/version, every keyword verified against a cited grandocs page, quoting around spaced names/text, `Wait`/`Follow`/`Go` correctness, `@`/CLI consistency (MA2), `Execute`/`AddToCmdline` intent (MA3), `/NoConfirmation` on destructive `Delete`/`Store` overwrites, variable scope + case, and (for XML delivery) well-formed XML with the right schema version and import path. Tell the user you linted it and note anything you couldn't verify.

## Presenting a macro

- Show it the way it lives on the console: **a table of lines** (MA3: `No | Command | Wait | Enabled | AddToCmdline | Execute`; MA2: `No. | CMD`) — mirror the table format in `macro_examples.md`. For XML delivery, also give the full file and the exact import path.
- Under it, list each command line with the grandocs page that proves its syntax.
- State: generation + version assumed, that you linted it, and any line you could not ground (do not silently include unverifiable syntax).
- If the macro deletes/overwrites/patches/outputs, add the unofficial-mirror safety note and link the canonical page.

## grandocs surfaces you can rely on

- **`/llms.txt`** (and `llms-full.txt` / `llms-small.txt`) — site map for locating topics.
- **Per-page `.md` twins** — append `.md` to any docs URL for raw markdown.
- **MCP server** — tools `search_docs`, `get_page`, `command_lookup`, `list_products_versions` when connected.

## Do not

- Edit shared repo files. If you need a dependency or config, state it in your notes instead.
- Invent keywords, options, file paths, or XML attributes. Ground them or omit them.