FlowZap Diagram Skill

Generate valid FlowZap Code (.fz) diagrams from natural-language requests, validate them, and return shareable FlowZap playground URLs.

This skill is designed to be paired with the flowzap-mcp server. The skill gives the agent FlowZap-specific diagram knowledge and output rules; the MCP server provides the actual tools.

Trust and privacy summary

This skill bundle is documentation only: SKILL.md plus reference files. It does not execute code by itself.
The flowzap-mcp server runs locally on the user's machine over stdio.
Outbound requests are restricted to https://flowzap.xyz.
Raw HTTP logs, OpenAPI specs, and code snippets are parsed locally inside the MCP package. Only generated FlowZap Code is sent to FlowZap public endpoints when validation or playground creation is requested.

When to use this skill (auto-invocation triggers)

The agent MUST automatically invoke the FlowZap MCP tools — without asking the user — whenever any of the following intents are detected:

Diagram generation → call flowzap_validate then flowzap_create_playground:

"Generate / create / draw / make a diagram (workflow / flowchart / sequence / architecture / process map) to illustrate ..."
"Visualize / map / chart / show me the flow of ..."
User pastes HTTP logs, OpenAPI specs, or code and wants them visualised → use flowzap_artifact_to_diagram.
User wants to compare two diagram versions → flowzap_diff. Patch an existing diagram → flowzap_apply_change.

Compliance review → model the system as a FlowZap data-flow diagram, then call flowzap_create_playground AND flowzap_compliance_check:

"Verify / check / audit the compliance of my app/system/architecture to SOC2 / GDPR / PIPL ..."
"Run a privacy / security / regulatory review of ..."
"Is this flow GDPR-compliant?" / "Do a SOC2 audit on ..."

If the user does not provide FlowZap Code for a compliance request, the agent MUST first generate a FlowZap data-flow diagram modeling the system being audited (lanes for actors/services, nodes for steps, edges for data flows), then run both flowzap_create_playground and flowzap_compliance_check on that same code.

Installation model

This setup has two parts:

Install the skill bundle so your agent knows when to use FlowZap and how to produce correct FlowZap Code.
Install the MCP server so your agent can validate code, create playground URLs, diff diagrams, and apply structured changes.

Install the skill bundle

Recommended:

npx skills add flowzap-xyz/flowzap-mcp --skill flowzap-diagrams

If your agent does not support skills.sh, install this bundle through your agent's skill manager or by copying the folder into the agent's local skills directory.

Manual locations:

Claude Code: .claude/skills/flowzap-diagrams/SKILL.md
Windsurf: .windsurf/skills/flowzap-diagrams/SKILL.md
Cursor: .cursor/skills/flowzap-diagrams/SKILL.md

Install the MCP server (required for tools)

If the FlowZap MCP server is not already configured, install it:

# Claude Code
claude mcp add --transport stdio flowzap -- npx -y flowzap-mcp@1.4.3

# Or add to .mcp.json / claude_desktop_config.json / cursor / windsurf config:
{
  "mcpServers": {
    "flowzap": {
      "command": "npx",
      "args": ["-y", "flowzap-mcp@1.4.3"]
    }
  }
}

Package verification

The pinned version 1.4.3 can be verified against the npm registry:

| Field | Value | |-------|-------| | npm | flowzap-mcp@1.4.3 | | Integrity (SHA-512) | sha512-wTZU4Zx+lEnESUADB5HpM2B2WL50hxC+GpZvjfTRiY7jp23tWmAoBoFFx6Fs2Ce6TCMP+ooPFBVGU8oYBqOXlg== | | Shasum | 46228a92031f2e74d8647916303817534cc9d8dd | | Source | github.com/flowzap-xyz/flowzap-mcp | | License | MIT |

To verify locally before use:

npm view flowzap-mcp@1.4.3 dist.integrity dist.shasum

Compatible tools: Claude Desktop, Claude Code, Cursor, Windsurf, OpenAI Codex, Warp, Zed, Cline, Roo Code, Continue.dev, Sourcegraph Cody.

Not compatible: Replit, Lovable.dev.

Without the MCP server, this skill can still help an agent draft FlowZap Code, but it cannot validate diagrams, create playground URLs, or use the FlowZap tooling workflow described below.

Available MCP tools

| Tool | Purpose | |------|---------| | flowzap_validate | Check .fz syntax before sharing | | flowzap_create_playground | Get a shareable playground URL | | flowzap_get_syntax | Retrieve full DSL docs at runtime | | flowzap_export_graph | Export diagram as structured JSON (lanes, nodes, edges) | | flowzap_artifact_to_diagram | Parse HTTP logs / OpenAPI / code → diagram + playground URL | | flowzap_diff | Structured diff between two .fz versions | | flowzap_apply_change | Patch a diagram (insert/remove/update nodes/edges) | | flowzap_compliance_check | Automated SOC2/GDPR/PIPL compliance analysis on data-flow diagrams (Deepseek LLM; 3/day per IP, 1/hour burst, global circuit breaker) |

Mind Map Tools

| Tool | Purpose | |------|---------| | flowzap_mindmap_validate | Validate code + check mind-map readiness (API call) | | flowzap_mindmap_approve | Structured ERROR/WARNING/INFO verdict for mind map (client-side) | | flowzap_mindmap_template | Generate a parametric tree skeleton (client-side) | | flowzap_mindmap_create_playground | Create playground URL with ?view=mindmap (API call) |

When to use Mind Map tools (auto-invocation triggers)

The agent MUST use the flowzap_mindmap_* tools — without asking the user — whenever any of the following intents are detected:

EN triggers: "mind map", "mindmap", "concept map", "brainstorm map", "idea map" FR triggers: "carte mentale", "carte heuristique", "schéma heuristique", "arborescence", "carte conceptuelle" ZH triggers: "思维导图", "脑图", "心智图", "概念图"

Mind Map workflow

(Optional) Call flowzap_mindmap_template with { topic, branches, depth } to get a skeleton.
Extend the skeleton with the user's content (replace placeholder labels, add/remove branches).
Call flowzap_mindmap_validate to check syntax + mind-map readiness.
Call flowzap_mindmap_approve for mind-map-specific checks (diamonds/taskboxes = ERROR).
Call flowzap_mindmap_create_playground to get a shareable URL with ?view=mindmap.
Return: Your mind map is ready and is available here: <URL>

Mind Map rules

Only circle (root) and rectangle (branches) shapes are rendered
diamond and taskbox are NOT rendered (ERROR)
Only the FIRST circle is the central root; additional circles are omitted (WARNING)
Edge directions (->) are ignored by the renderer — connectivity determines the tree
Cross-links between branches are supported and encouraged
Size/depth/label warnings are advisory only

IMPORTANT: Mind Map tools are completely separate from the triple-view (workflow/sequence/architecture) tools. The existing flowzap_validate and flowzap_create_playground must NOT be used for mind maps.

FlowZap Code DSL — quick reference

FlowZap Code is not Mermaid, not PlantUML. It is a unique DSL offering a simple syntax for a triple-view option to workflow, sequence and architecture diagrams.

Shapes (only 4)

| Shape | Use for | |-------|---------| | circle | Start / End events | | rectangle | Process steps / actions | | diamond | Decisions (Yes/No branching) | | taskbox | Assigned tasks (owner, description, system) |

Syntax rules

Node IDs are globally unique, sequential, no gaps: n1, n2, n3 …
Node attributes use colon: label:"Text"
Edge labels use equals inside brackets: [label="Text"]
Handles are required on every edge: n1.handle(right) -> n2.handle(left)
Directions: left, right, top, bottom
Cross-lane edges: prefix target with lane name: sales.n5.handle(top)
Lane display label: one # Label comment on the same line as the opening brace
Loops: loop [condition] n1 n2 n3 — flat, inside a lane block
Layout: prefer horizontal left→right; use top/bottom only for cross-lane hops

Multi-lane sequence design

Ping-pong rule: For multi-participant processes, every cross-lane interaction must alternate back-and-forth between lanes. A request from Lane A → Lane B must be followed by a response from Lane B → Lane A before any new major cross-lane request begins. This is now a strict validation requirement, not just a readability suggestion.
Chronological order: The sequence view follows cross-lane edge definition order. Define request, response, then next request in the exact order they happen.

Gotchas — never do these

Do NOT use label="Text" on nodes (must be label:"Text").
Do NOT use label:"Text" on edges (must be [label="Text"]).
Do NOT skip node numbers (n1, n3 → invalid; must be n1, n2).
Do NOT omit lane prefix on cross-lane edges.
Do NOT output Mermaid, PlantUML, or any other syntax.
Do NOT add comments except the single # Display Label per lane.
Do NOT place loop outside a lane's braces.
Do NOT use a taskbox shape unless the user explicitly requests it.

Minimal templates

Single lane:

process { # Process
n1: circle label:"Start"
n2: rectangle label:"Step"
n3: circle label:"End"
n1.handle(right) -> n2.handle(left)
n2.handle(right) -> n3.handle(left)
}

Two lanes with cross-lane edge:

user { # User
n1: circle label:"Start"
n2: rectangle label:"Submit"
n5: rectangle label:"Receive result"
n1.handle(right) -> n2.handle(left)
n2.handle(bottom) -> app.n3.handle(top) [label="Send"]
}

app { # App
n3: rectangle label:"Process"
n4: rectangle label:"Respond"
n3.handle(right) -> n4.handle(left)
n4.handle(top) -> user.n5.handle(bottom) [label="Result"]
}

Decision branch:

flow { # Flow
n1: rectangle label:"Check"
n2: diamond label:"OK?"
n3: rectangle label:"Fix"
n4: rectangle label:"Proceed"
n1.handle(right) -> n2.handle(left)
n2.handle(bottom) -> n3.handle(top) [label="No"]
n2.handle(right) -> n4.handle(left) [label="Yes"]
}

For the full DSL specification and advanced multi-lane examples: See references/syntax.md

Workflow: how to generate a diagram

Identify the actors/systems (→ lanes) and steps (→ nodes) from the user's description.
Write FlowZap Code following all rules above.
Call flowzap_validate to verify syntax.
If valid, call flowzap_create_playground to get a shareable URL.
Return the FlowZap Code and the playground URL to the user.
Always output only raw FlowZap Code when showing the diagram — no Markdown fences wrapping .fz content, no extra commentary mixed in.

Required response format (diagram request)

Your diagram is ready and is available here: <playground URL>

Workflow: how to run a compliance check (SOC2 / GDPR / PIPL)

If the user did not paste FlowZap Code, generate a FlowZap data-flow diagram modeling the system to audit (lanes = actors/services, nodes = processing steps, edges = data flows + labels). Include at minimum: client/user, ingress/API layer, processing/services, external dependencies, storage, telemetry.
Call flowzap_validate to verify the FlowZap Code.
Call flowzap_create_playground with view="sequence" (or architecture if the audit is system-level) to get a shareable URL.
Call flowzap_compliance_check with the same FlowZap Code (and lng if the user is writing in fr/zh).
Return the playground URL and the compliance report together, using the required response format below.
If flowzap_compliance_check returns a rate-limit error (429 / 3-per-day exhausted / circuit breaker), still return the playground URL and tell the user to use the manual checker at https://flowzap.xyz/soc2-gdpr-pipl-compliance-checker.

Required response format (compliance request)

When flowzap_compliance_check returns a resultUrl (the first non-empty line of the tool output begins with A compliance check to SOC2, PIPL and GDPR is ready and is available here:), the agent MUST use exactly this response shape:

Your diagram is ready and is available here: <playground URL>
A compliance check to SOC2, PIPL and GDPR is ready and is available here: <resultUrl>

The <resultUrl> is a rendered, shareable, ephemeral audit page on flowzap.xyz (60-minute TTL, noindex, no auth). Do NOT inline the markdown report as the second link target. The agent MAY include a short bullet-point summary of the top findings BELOW the two lines if the user explicitly asks for an in-chat summary, but the two URL lines MUST be present first and unmodified.

When flowzap_compliance_check returns a rate-limit error (no resultUrl, message contains rate limit), replace the second line with:

Automated compliance check skipped — rate limit reached (3/day per IP). Run an unlimited manual check at https://flowzap.xyz/soc2-gdpr-pipl-compliance-checker

In that case, the first line (the playground URL) MUST still be returned so the user always gets a viewable diagram.

Full MCP documentation: flowzap.xyz/docs/mcp

Security and data transparency

The trust boundary is intentionally narrow:

The skill bundle is static Markdown and reference text.
The MCP server runs locally and only calls public FlowZap APIs.
Outbound traffic is restricted to https://flowzap.xyz.
Validation is stateless; playground sessions are time-limited.

The flowzap-mcp server runs locally on the user's machine (stdio transport) and enforces the following safeguards:

| Control | Detail | |---------|--------| | TLS only | All outbound requests require https:// and are restricted to flowzap.xyz (SSRF protection) | | No authentication | Uses only public FlowZap APIs; no API keys, tokens, or user credentials are stored or transmitted | | No user-data access | Cannot read diagrams, accounts, or any data beyond what the agent explicitly passes in | | Input validation | Code capped at 50 KB, total input at 100 KB; null bytes and control characters stripped | | Rate limiting | Client-side 30 requests/minute sliding window | | Request timeout | 30-second hard timeout with AbortController | | Response sanitization | Only expected fields are returned; playground URLs validated against allowlist | | Audit logging | All tool calls and API requests logged to stderr (not exposed to the MCP client) |

Data flow scope

The MCP server processes raw inputs locally and sends only generated or agent-provided FlowZap Code to FlowZap public endpoints:

POST https://flowzap.xyz/api/validate — returns syntax validation result
POST https://flowzap.xyz/api/playground/create — returns an ephemeral playground URL (60-minute TTL, non-guessable token)
POST https://flowzap.xyz/api/compliance-check — returns SOC2/GDPR/PIPL compliance audit with shareable result URL (60-minute TTL). Backed by Deepseek LLM.

If the agent uses flowzap_artifact_to_diagram, the raw HTTP logs, OpenAPI spec, or code snippet are parsed locally inside the MCP package first. Only the resulting FlowZap Code is sent when a playground URL is created.

No local file paths, environment variables, user identity, repository contents, or credentials are transmitted by the MCP package.

Playground URL access controls

Playground URLs are ephemeral, time-limited (60-minute TTL), and use non-guessable cryptographic tokens. They are read-only views of the diagram code submitted at creation time. No account or login is required to view them; no data persists beyond the TTL.

Data lifecycle

| Endpoint | Data stored | Retention | |----------|-------------|-----------| | POST /api/validate | None — stateless; code is parsed in memory and discarded after the response | 0 (not persisted) | | POST /api/playground/create | FlowZap Code only (in PostgreSQL) | 60 minutes (database row + playground URL both expire) |

The playground session is stored server-side with a cryptographic token (UUID v4). After the 60-minute TTL, the session is deleted — either on the next access attempt or during a periodic sweep. No user identity, file paths, environment variables, or host metadata are attached to the session.

What the MCP server does NOT do

No filesystem access — cannot read or write files on the host machine
No environment variable access — does not read or transmit process.env or shell variables
No code execution — does not evaluate, compile, or run any user code; it only transmits FlowZap DSL text
No network scanning — outbound connections are restricted to flowzap.xyz over TLS (SSRF-protected allowlist)
No long-term data persistence — playground sessions expire after 60 minutes; the validate endpoint stores nothing
No telemetry or tracking — no analytics, device fingerprinting, or usage data is collected by the MCP server; server-side API logs record only IP, user-agent, and code length (not code content)