Smithery is now a part of Arcade.dev! Read more in our announcement here
Plan the Resource structure, field configurations, and access/permission model for a Form.io application, then emit a ready-to-import project template.json (Phase A: a human-readable Resource Map...
Turn a natural-language application description into a concrete Form.io resource map — the minimum plan needed to actually build the app.
Planning needs no server. This skill calls no MCP tool: it interviews, decides a resource model, and writes template.md + template.json to the working directory. Every one of those steps runs with no Form.io server connected, no project configured, and no authentication — so run the whole two-phase flow to completion before the subject of a server comes up at all. Whoever imports the result owns that gate; you do not hold it, and you must not open with it. If a later turn does take you to a Form.io tool call, the check below applies then and not before.
Check this when you reach your first Form.io tool call, not when this skill activates. The check is whether form_list is callable by you, under whatever name this client exposes it. If it is, proceed. If it is not, load the formio-mcp-setup skill and use it to help the user connect the server; that skill is the only remedy you offer, and this skill writes no MCP configuration itself.
Do not work around missing tools by making direct HTTP requests against a Form.io deployment, and do not write a throwaway script that makes them for you. This library documents the whole Form.io REST surface, which makes hand-rolling requests tempting and wrong — it bypasses the guardrails the tools enforce and can write to a live deployment unreviewed. Stop and report what is blocking instead.
That ban is on build-time work — the configuring you do in this session. It says nothing about the application you are building: an app is expected to call the Form.io REST API at runtime, to log its users in and to read and write their submissions, and formio-api's runtime-scope references document those endpoints for exactly that code.
You are a thinking partner that plans before it builds. Two distinct phases with a hard approval gate between them.
AskUserQuestion). Peppering the user one question at a time burns trust.erDiagram + flowchart TD) so downstream skills and GitHub/IDE readers get semantic edges + native rendering. Both surfaces describe the same topology — generated from one internal model per run.template.json / template.md until the user has explicitly approved the map. See "The approval gate" below.template.md AND template.json together — same basename, same timestamp on collision. template.md is the architectural-intent artifact downstream skills seed from; template.json is its structured companion. Never emit one without the other.<name>:save, and a missing one there is a bug. When in doubt about whether a given form persists, decide deliberately (and ask the user if unclear) rather than defaulting either way. See references/phase-b-emission.md → "Actions emission — per use-case", and references/template-json.md for exact shapes.template.md / template.json artifact pair. It does not call project_import, form_create, or any other MCP tool, which is why it needs no project configuration of its own and probes for none. Importing is a separate, explicit user action: Phase B prints it as a next step, and whoever carries it out — formio-application on its own flow, or you in a later turn once the user asks — confirms the target project first, on the terms references/phase-b-emission.md → "Next steps" sets out.Form.io has two kinds of entries — Resources (stored, reusable data models; the nouns of the app, each auto-generating a REST API) and Forms (bespoke, purpose-specific data collection — a job application, a survey, an RSVP). Classify every entity BEFORE modeling its fields with the litmus test: a record the app stores and reuses → Resource; a response to a specific ask, possibly wrapping a record → Form. A bespoke Form references an already-established Resource (disabled pre-selected Select, or the submission owner) — never create the Resource from inside the Form. The full decision guide — definitions, the Job Application worked example, the quick classification table, and the anti-pattern — is in references/planning-rules.md → "Resources vs. Forms"; read it before classifying, and when in doubt, ask the user rather than silently defaulting to Resource.
Work through six rounds — compress or expand as the user's description warrants (skip ahead if they named every entity and relationship; start from zero for a bare "I want a CRM"). The full round-by-round scripts, question batching, and the "Interview heuristics" for ambiguous cases are in references/interview-guide.md.
Two planning references cover the primitives; open them while building the map:
references/planning-rules.md — the relationship → construct mapping (foreign-key selects, N:N join resources, user-to-resource group joins), the component cheat sheet, and the action cheat sheet.references/access-patterns.md — the owner/group/role/tenant pattern table; the three-part rule for group-based access (a Group Assignment action on the join, a field-based submissionAccess block on every child's group-reference select with the entry types chosen deliberately, AND read_all for the end-user role on the group resource itself — both omissions are silent bugs: without part 2 the user sees the Project but not its Tasks; without part 3 the group select cannot populate, so no group reference reaches the payload and every create returns Unauthorized while reads keep working); the transitive hidden-calculated-mirror pattern for resources 2+ levels below the group; and the access vs submissionAccess distinction (users describing access almost always mean submissionAccess). Read it whenever the plan has any owner-, group-, or role-based access.When the interview has enough signal, emit the Resource Map as a single fenced markdown block for the user to review in the terminal — the same sections Phase B writes to template.md, with ONE substantive difference: Phase A uses ASCII diagrams for ## ER Diagram and ## Access Flow Diagram, while Phase B's file uses Mermaid (same topology, generated from one internal model per run). Keep the map terse — one sentence per resource purpose, one clause per field. Follow the exact Phase A template in references/interview-guide.md → "Phase A — Resource Map for review"; the full shape rules and Access Matrix token vocabulary are in references/template-md.md.
After emitting the Resource Map, stop. Ask the user one question, in one round:
"Does this map look right? I can write
template.md+template.jsononce you approve it, or revise the map based on your feedback."
Offer two options: Approve & write template.md + template.json and Revise the map (with free-text "Other" always available for specific tweaks).
Do not skip this gate. Even if the user's original prompt sounds decisive ("build me a task manager and give me the JSON"), always produce the map first, then ask. The gate exists because the JSON is 200–600 lines and a single wrong field propagates everywhere — cheaper to catch mistakes in the ~50-line map than the 500-line export.
If the user says "revise" or flags specific issues: update the map, re-show it, re-ask. Iterate until they approve.
Only when the user has approved the map, emit the artifact PAIR — always both, always together:
template.md — the approved Resource Map, saved to disk as the architectural-intent document. Same structure as the Phase A map (Resources, optional Forms, Users & Auth, Roles, Access Matrix, ER Diagram, Access Flow Diagram, Companion artifact). See references/template-md.md for the complete spec.template.json — the Form.io project-export JSON. Same shape you get from GET /{projectName}/export and can POST to /{projectName}/import.Each file is emitted in TWO forms at the same time:
markdown for template.md, json for template.json) — so the user sees both ASCII diagrams and the structure inline.Write tool — so downstream skills (like formio-application's Import step, or formio-angular/formio-angular-resources) can pass real file paths../template.md and ./template.json in the user's current working directory (cwd — the directory the user was in when they invoked the flow). Use the Write tool; local filesystem writes do NOT count as "calling the MCP server", so the skill's "does not call the MCP server" stance is preserved.20260420T153000Z) to BOTH filenames so the pair stays matched — even if only one of the two collided — and report both chosen filenames in the Phase B confirmation message. Exact rule and format: references/template-md.md → "File pairing rules".formio-application (which will then pass the paths to its Import step and the framework handoff). Do not make this conditional.The markdown block MUST follow the section order in references/template-md.md exactly (# Resource Map — <App Name> → ## Resources → optional ## Forms → ## Users & Auth → ## Roles → ## Access Matrix → ## ER Diagram → ## Access Flow Diagram → ## Companion artifact — downstream graders key on these headings), with Mermaid — not ASCII — diagram blocks. The JSON block MUST be a valid, importable template with the eight top-level keys in exactly this order: title, version, name, roles, forms, actions, resources, access; read references/template-json.md before writing — do not improvise structure. Full requirements (Mermaid node coverage, empty-object rules, the optional description key, the non-empty project-level access array): references/phase-b-emission.md → "Transcript requirements".
Right before writing template.json, run the emission algorithm in references/phase-b-emission.md → "Actions emission — per use-case" exactly once. In brief: every persisting resource and form gets <name>:save (a missing Save silently drops submissions; a deliberately client-only entry with no actions is valid); login forms get <name>:login (a login-form save must NEVER set settings.resource); register forms get Save → Role Assignment → Login; every access-governing join gets <join>:group alongside its Save; Email/Webhook only when explicitly requested. The reference holds the full five-step algorithm, the Login settings.resources rules, the admin-work-goes-through-the-portal rule, the Email action rules, the minimum-viable-action-set table, priority ordering, and the pre-emit self-check.
Render the markdown block first, then the JSON block, then the one-line confirmation (Wrote ./template.md and ./template.json., using the collision-aware filenames), then the "Next steps" section. The exact confirmation line and Next-steps block to reproduce are in references/phase-b-emission.md → "Order in the transcript".
When you are handed a baseline template — the current tag's template or the current export of a project that already has content — you are planning a change, not an application. Run the same interview and approval gate, scoped to what the change needs, and follow references/change-plan.md: Phase A marks what the change adds (new) or alters (changed), and Phase B updates template.md with a dated change section and writes changes.json — only the entities the change creates, plus the updates to existing forms. In change mode you never write template.json and never produce a template to import: an existing project is changed with the form, role, and action tools, because importing into it replaces the forms and access it names.
formio-auth — when the approved map's Users & Auth section has an SSO other than none, a Custom JWT: yes, or any auth concern beyond resource-backed login + Role Assignment + Group Assignment (Token Swap, email-token/passwordless auth, 2FA, reCAPTCHA, RBAC tuning beyond default roles and group permissions), that configuration acts on the project the template creates, so it runs after the import — never from this skill. When formio-application invoked you, it runs formio-auth at its Step 3.5. When you are running standalone, include the Configure auth line in the Next steps menu (references/phase-b-emission.md).formio-application — when invoked as the orchestrator's planning step, run the same two phases and gates; the Phase B file paths are what the orchestrator passes to its Import step (a first build) or its change step (change mode, with changes.json) and to the framework-specific scaffolding skill.A complete Task Manager run — the abbreviated interview, the full Phase A ASCII Resource Map, and the Phase B handoff — is in references/interview-guide.md → "Worked example". Canonical paired examples are checked in under references/examples/: task-manager/ (simple group, direct-child access) and complex-crm-transitive/ (group with hidden calculated mirrors on grandchildren). Use these as structural references when deciding how to shape a new app's output.
Consult these when the user's requirements touch an edge case this skill doesn't cover (e.g., conditional access, multi-level tenancy, federated SSO).
formio-api skill handles endpoint reference.formio-schema. This skill's template.json uses the minimum viable component shape for each field.All one hop from here — open the one matching the phase you are in:
references/planning-rules.md — Resources vs. Forms decision guide; relationship → construct; component and action cheat sheets.references/access-patterns.md — owner/group/role/tenant patterns; the group-access three-part rule (including the group resource's own read grant); the entry-type menu and the delete decision; transitive mirrors; access vs submissionAccess.references/interview-guide.md — full interview scripts; the exact Phase A map template; the Task Manager worked example; interview heuristics.references/phase-b-emission.md — Phase B transcript requirements; the actions-emission algorithm; output order and the Next-steps block.references/template-md.md — full template.md spec: section shapes, Mermaid diagram conventions, Access Matrix tokens, file pairing, chat-output rules.references/template-json.md — full template.json schema: component shapes, action shapes, access arrays, assembly checklist.references/change-plan.md — change mode: the baseline input, the Phase A marking, the dated change section, the changes.json shape, and its self-check.