With solid context engineering, your AI agent calls the right tools and produces the right diagram on the first try

FlowZap's MCP Server already ensures your diagrams validate cleanly in tools like Claude Code, Cursor, and Windsurf. Now, with the new FlowZap Diagram Skill, your agent starts from a much smarter place: it knows the FlowZap DSL, when to call each tool, and how to structure diagrams on the first try.

The FlowZap Diagram Skill is a SKILL.md file that teaches your AI agent how to think about FlowZap diagrams before it writes a single line of .fz code. Understanding your code base, brainstorming development strategies with your favorite LLM, finding optimization strategies and bugs, will now feel smoother than ever.

Install it now:

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

Get it on GitHub.

What is context engineering (and why should you care)?

You've probably heard the term prompt engineering — crafting the right question to get a good answer from an LLM. Context engineering goes further. It's about designing the entire information environment the model operates in — not just what you ask, but what the model already knows when your request arrives.

In concrete FlowZap terms:

	Without the Skill	With the Skill
What the agent knows	Tool names and JSON schemas from the MCP server	Full DSL rules, 4 shapes, handle syntax, gotchas, templates, and a step-by-step workflow
What it does first	Guesses FlowZap syntax based on Mermaid/PlantUML patterns it saw in training	Follows explicit FlowZap Code rules injected into its context window
Typical failure	`label="Start"` on nodes (wrong), missing lane prefix, inventing shapes	Rare — the gotchas section catches common errors before they happen
Token cost	High (multiple validate → fix → re-validate loops)	Low (usually validates on first try)

An MCP server gives the agent hands (tools it can call). A SKILL.md gives it domain expertise (knowledge of when, why, and how to use those tools correctly). You need both.

Five developer pain points this solves

1. "It writes perfect FlowZap Code from the start."

LLMs can default to Mermaid syntax because it's prevalent in their training data. By explicitly stating the FlowZap DSL rules right up front, the skill ensures your agent writes native, accurate .fz code immediately.

2. "It nails the precise node and edge syntax."

FlowZap Code uses label:"Text" on nodes but [label="Text"] on edges. The skill includes a dedicated Gotchas section that explicitly trains the agent on these nuances, ensuring crisp, error-free connections every time.

3. "Cross-lane diagrams work flawlessly."

Complex, multi-actor workflows require precise lane prefixes (like sales.n5.handle(top)). The skill provides the agent with a complete two-lane template to reference, so cross-lane edges connect perfectly without prompting.

4. "It validates on the first pass, saving time and tokens."

Instead of a costly "validate → fix → re-validate" loop, the skill gives the agent a clear, step-by-step workflow to follow. By knowing the rules before it writes, first-pass validation success goes up dramatically.

5. "It knows exactly when to jump in."

You don't even have to mention "FlowZap" by name anymore. The skill includes explicit trigger conditions, so whether you ask for a "workflow", "flowchart", "process diagram", or "sequence diagram", the agent knows exactly which tool to reach for.

What's inside the SKILL.md

The file follows the open Agent Skills Specification — a lightweight standard adopted by Claude Code, Cursor, Windsurf, Codex, Warp, Zed, and 30+ other coding agents.

Here's what we packed into it:

YAML frontmatter — name, description, allowed-tools, metadata for discovery and indexing on skills.sh.
MCP setup — One-command install for every compatible platform.
7 MCP tools — A quick-reference table covering flowzap_validate, flowzap_create_playground, flowzap_get_syntax, flowzap_export_graph, flowzap_artifact_to_diagram, flowzap_diff, and flowzap_apply_change.
DSL quick reference — The 4 shapes (circle, rectangle, diamond, taskbox), all syntax rules, and the gotchas section.
4 templates — Single lane, two lanes with cross-lane edge, decision branch, and a full multi-lane authentication flow. Copy-pasteable starting points for any complexity.
Step-by-step workflow — So the agent doesn't just know the syntax — it knows the process to follow.
Public API fallback — For platforms that don't support MCP (like Replit or Lovable.dev), the skill documents the /api/validate and /api/playground/create endpoints.

How to install it

Option A: Via the skills CLI (recommended)

Works with Claude Code, Cursor, Windsurf, Codex, and 37+ agents:

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

Option B: Manual (any agent)

Copy the SKILL.md from GitHub.
Place it in your agent's skills directory:
- Claude Code: .claude/skills/flowzap-diagrams/SKILL.md
- Windsurf: .windsurf/skills/flowzap-diagrams/SKILL.md
- Cursor: .cursor/skills/flowzap-diagrams/SKILL.md
Restart your agent or reload the window.

Option C: Global install

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

This makes the skill available in every workspace, not just the current project.

Do I still need the MCP Server?

Yes. The skill and the FlowZap MCP server are complementary — not interchangeable.

	SKILL.md	MCP Server
What it provides	Domain knowledge, syntax rules, workflow instructions	Executable tools (validate, create playground, export, diff, patch)
Analogy	A senior engineer's cheat sheet	The API the engineer calls
Without it	Agent has tools but doesn't know how to use them well	Agent knows the rules but can't execute anything

The best setup is both: install the MCP server for tool access, install the skill for context. That's context engineering.

In short

FlowZap Diagram Skill: Give your AI agent the knowledge, not just the tools.

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

We'll iterate on the skill based on real-world failure patterns. If your agent still produces broken diagrams after installing the skill, open an issue — we want to know.

The FlowZap Diagram Skill Is Live — Here's Why It Matters