maias: Skill for Claude Code

maias-create

Turn an app description into a valid MAIAS document.

Ground rules

1. Read docs/spec/llms.txt first — it is the authoritative condensed spec (document shape, element taxonomy, hard rules, canonical form). Do not author from memory.
2. Never hand-verify — the toolchain is the referee: ./node_modules/.bin/maias validate <file> and maias fmt --write. (If the binary is missing: npm install && npm run build.)
3. Study one example in examples/ that resembles the requested app (todo_list for CRUD, social_network for feeds/tabs, ecommerce for catalogues/journeys, calculator for single-screen).

Process

1. Design before YAML. From the description, decide:

   • the 2–5 primary screens (tab bar) — what the user lives in;
   • the journeys (flows): each with an entry screen and an ordered screen list;
   • secondary screens: details (with :param paths), forms (usually presentation: modal), settings;
   • which screens are gated (auth: required) and which are shareable (deep_link: true + app.deep_links.scheme).

   End the design step by showing the user a structure preview in chat — tab bar, flows, and screens as an indented tree in the exact format maias tree prints (hand-drawn; no file exists yet). It is the contract you verify in step 5. Proceed after showing it unless the request was ambiguous — don't gate on confirmation. Format:

   Recipe Box — 9 screens, 3 flows
   Tab bar: Discover · My Recipes · Shopping
   
   Flow: discover — Browse and search recipes.
   ├─ discover        Discover       (list, tab)
   ├─ search          Search         (search)
   └─ recipe_detail   Recipe         (detail, deep_link)  back→discover
   

2. Write the document at the user-requested path (default <app_name>.maias.yaml in the project root). Every screen and flow gets a real description — intent travels with structure. Give data-bearing screens states (empty/loading/error) and data.reads/writes using a consistent app-wide key vocabulary. Links follow elements first (spec §4.2): anything with an on-screen affordance is an element with target; navigation.secondary only for links not laid out.

3. Validate and iterate: maias validate <file> until zero errors; then resolve warnings you introduced by accident (unreachable screens usually mean a missing link, not a missing warning-suppression). Deliberate warnings are fine — say so.

4. Canonicalise and re-verify: maias fmt <file> --write, then maias fmt <file> --check and a final maias validate (fmt rewrites content — reorders lists, refolds scalars — so verify after it, not before).

5. Summarise with the deterministic tree: run maias tree <file> and show its output — this is the toolchain's version of your step-1 preview; if they differ structurally, reconcile before finishing (the document is the truth, but an unintended difference means you drifted from the agreed design). Offer maias diagram <file> for a Mermaid flowchart of the screen graph — it renders in GitHub, Claude, and Obsidian with no install (--flow <name> scopes large apps).

6. Offer to open it in the MAIAS Browser (npm run web --workspace maias-browser, then pick the file from the menu).