QORM Skills

A QORM Skill is a battle-tested workflow description for AI agents — each skill encodes the exact steps, allowed tools, input files, and output format needed to complete a specific QORM task reliably. Skills are shipped in integrations/skill/ and loaded by the agent at session start.

Available Skills

Skill	What it does
`scene-authoring`	Author a new QORM scene: choose the right layout container, pick widgets from the catalog, wire state bindings with `{{state.x}}` syntax, declare actions for interactivity, and validate the result with `qorm_check_layout`. Covers the full authoring loop: scaffold → wire → verify.
`layout-debugging`	Diagnose and fix layout issues: measure rendered positions with `qorm_measure`, compare against expected bounds, identify overflow/clipping/z-index problems, and apply targeted patches. Uses the verification pipeline to confirm fixes.
`agent-patch`	Design and apply structural patches to a live app: use `qorm_query` to find target nodes, `qorm_preview_patch` to preview changes safely, `qorm_diff` to review the structural impact, and `qorm_apply_patch` to commit — with the preview token binding every apply to a prior review.
`platform-porting`	Adapt a QORM app for a new platform: audit capabilities with `qorm_capabilities`, add platform-specific style overrides (safe-area insets, native font stacks, platform-correct spacing), and stamp the capability manifest so the runtime gates what the platform actually provides.
`motion-design`	Add declarative animations and transitions: entrance effects via the `animation` prop (fade, slide, bounce, shake, pulse, spin), interaction transitions via `transition: "0.2s"` on pressed/hover scale + background + opacity, animated widgets (spinner, switch, animatedOpacity), and theme-level motion tokens.
`host-capability-check`	Audit which hardware/native capabilities are available on the current host: camera, biometrics, GPS, accelerometer, clipboard, Bluetooth, battery, brightness control, and more — cross-referenced against the platform support matrix so the agent knows what will actually work.
`mobile-adaptation`	Adapt a desktop-first QORM app for mobile: responsive breakpoints (`sm`/`md`/`lg`), touch-friendly hit targets, bottom navigation patterns, safe-area handling, and viewport-aware `when` branches that swap layouts at device widths.

Skill Structure

Each skill is a markdown file with this structure:

Goal              — the specific outcome (one sentence)
Applicable scope  — when to use (trigger phrases, app state, file patterns)
Input files       — which app files to read
Recommended tools — which MCP tools to use and in what order
Steps             — the numbered workflow
Prohibited actions — what to NEVER do
Output format     — how to report results
Permission requirements — which qorm_* tools are needed

scene-authoring

Purpose: let the agent create or modify scene JSON.

Rules:

Use the canonical widget names from the widget catalog.
Prefer column/row for layout, scroll for scrollable content, box for

card/surface containers.

Wire state with {{ state.x }} bindings; use if/visible/show for

conditional nodes.

onPress names an action in actions/; onChange fires on input/select

changes.

Prefer QSS stylesheets (styles/*.qss) for shared styles; use inline style

for one-off overrides.

Validate with qorm_check_layout after every edit.
Check the widget catalog for available props per widget type.

layout-debugging

Purpose: analyze and fix layout anomalies on the live app.

Steps:

qorm_measure — get every node's rendered x,y,w,h and computed styles.
Identify overflow: any node where x-overflow is true or the node extends

past its parent's bounds.

Identify clipping: nodes inside a scroll whose box sits outside the

viewport.

Check z-index: overlay widgets (drawer, menu, modal) must paint above siblings.
qorm_preview_patch → qorm_diff → qorm_apply_patch with fixes.
Re-measure to confirm.

Common causes: missing scroll wrapper, width/height too small for content, absolute-positioned nodes overlapping, gap/padding collapsing.

AI Usage Guidance

Best practices for agents working with QORM

Read before write. Always run qorm_inspect at session start to understand

the app's state schema, scenes, actions, and design tokens. Run qorm_measure to see the current rendered layout.

Preview before apply. Never call qorm_apply_patch without first calling

qorm_preview_patch with the same ops — the preview token binds every commit to a prior review. Use qorm_diff to see what changed structurally.

Use the widget catalog. The widget catalog is

auto-generated from the runtime — it is always correct. Prefer canonical widget names; aliases work but may confuse future agents.

Verify after every edit. Run qorm_check_layout with assertions that

match what the human asked for (visible, within bounds, correct type, no overflow). A passing verification is the only proof the edit worked.

Keep the DevTool open. The human observation window (/logwindow or

/console) lets the human see what the agent is doing in real time. Never close it during development.

Use QSS for shared styles. Instead of repeating style blocks on every

node, write a styles/app.qss with type/class/id rules. Theme variables (var(--accent), var(--label)) follow OS light/dark automatically.

Use qscript for complex logic. When steps in an action JSON get too

long, write an actions/<id>.qs file — let/if/for in/while/fn are easier to read and maintain than nested step arrays.

Respect the canvas engine. On -tags desktop, the app renders in a

native window with a software renderer. All interaction features work: keyboard navigation, scroll momentum, text editing, animated transitions, disabled dimming. The same JSON runs identically on the HTML path — test both.

Don't guess capabilities. Run qorm_capabilities to see what the host

actually provides. A capability that exists on iOS may not exist on desktop.

Self-heal from errors. If qorm_validate reports issues, fix them before

proceeding. If qorm_preview_patch returns validTokens and suggestedFix, use them.