fireworks-tech-graph: an Agent Skill that turns a sentence into a checked SVG diagram

What fireworks-tech-graph actually replaces

Hand-drawing an architecture diagram is not the expensive part. The expensive part is the third revision, when a reviewer asks why two arrows cross, or why the event bus sits inside the VPC boundary, and you redraw the whole canvas. fireworks-tech-graph attacks that loop by making the diagram a generated artifact from a text description. The README frames the pitch directly: stop drawing diagrams by hand, describe your system in English or Chinese. The repository is a Python project under the MIT licence, distributed both as an npm package (@yizhiyanhua-ai/fireworks-tech-graph) and as an Agent Skill, with a CLI entry point at scripts/fireworks.py. The audience is narrower than the tagline suggests. This is for engineers who already work inside an agent host (Codex or Claude Code) and who treat diagrams as deliverables attached to reviews, runbooks or design docs. It is not a drawing application, and nothing in the README claims a GUI.

How the skill classifies a request and what it emits

The mechanism described in the README is a classification step followed by constrained generation. A prompt such as "Generate a Mem0 memory architecture diagram, dark style" is classified into a diagram type and a style, then rendered as SVG with swim lanes, cylinders and semantic arrows, exported as a 1920px PNG, and reported back as two filenames. The interesting part is the constraint set rather than the rendering. The showcase composition contract requires zero crossings, zero bridge jumps, at most two bends per edge, at most eight bends overall, and at least 40px between nodes. Those are checkable numbers, which is why the README calls the styles "generator-backed" and describes an executable composition contract for the four engineering-first styles. Twelve styles ship, eleven generator-backed plus one AI-authored style called Dark Luxury. The four engineering styles carry domain contracts rather than only a visual theme: C4 review, cloud deployment, event streams, and reliability investigation. All 14 UML diagram types are listed as supported. The skill is one SKILL.md that the README says works unchanged in both Codex and Claude Code, which matters if your team is split across the two.

Installing and generating a first diagram

The package is published on npm, so installation follows the usual route. The package declares a bin entry named fireworks-tech-graph that points at scripts/fireworks.py, and package.json sets engines.node to >=22.12.0, so check your Node version before installing. The repository also ships a test script and a check script; the check script runs tools/check_project_consistency.py and tools/distribution.py --check, which is useful if you intend to modify the skill rather than only use it.

npm install @yizhiyanhua-ai/fireworks-tech-graph
node --version

The repository exposes an examples command through package.json, which runs python3 scripts/fireworks.py examples. Running it is the fastest way to see the output shape without writing a prompt of your own, and it does not require an agent host.

npm run examples

For the agent path, the README shows the intended interaction as a plain sentence to the skill inside Codex or Claude Code, with the reply naming the produced files. The style number is part of the prompt, so the router can select both the visual theme and, for styles 9 through 12, the domain contract. The README gives a stable prompt recipe that assigns one scenario per style and instructs the model to preserve scenario-specific nodes, sections and reading direction.

Draw the scenario assigned to style N:
1 Mem0 Memory Architecture; 2 Tool Call Flow; 3 Microservices Architecture;
4 Agent Memory Types; 5 Multi-Agent Collaboration; 6 System Architecture;
7 API Integration Flow; 8 Agent Runtime Architecture; 9 C4 Checkout Review;
10 Active-Active Cloud Deployment; 11 Checkout Event Line; 12 Checkout Reliability Pulse.

The animation path is narrower than the diagram path

The README is explicit that the motion path is focused, not general. It accepts a generated semantic SVG and emits one compact, probed GIF. The animated previews use what the README calls a user-approved 5.75-second settled-flow timeline: routes draw in first, then the final topology keeps live data moving for two additional seconds. Each full-size GIF is 960px wide at 20fps and 115 frames, and the 3x4 overview is an optimized 1200px preview. Lossless 1920px PNGs remain in assets/samples/ as static regression baselines. Read that as a boundary. If you want arbitrary animation, transitions between two different diagrams, or video output, this is not the tool, and the README does not offer those. The motion is semantic in the sense that it follows the arrows already present in the SVG, which is why the input has to be a generated semantic SVG rather than any file.

Where the approach breaks down

The composition contract is the selling point and also the source of friction. A hard limit of at most eight bends overall across an entire diagram is generous for a C4 container view and tight for a dense dependency graph with thirty services. When your system exceeds what the contract allows, the generator has two options, both bad: drop nodes, or produce a diagram that fails the contract it advertises. Nothing in the README describes what happens at that boundary, and the README does not document rollback or a fallback rendering mode. The second limitation is environmental. This is an Agent Skill, so the natural-language path requires Codex or Claude Code. The CLI path exists, but the README's own examples are prompt-shaped, and the classification step is described as something the skill performs rather than something the CLI exposes as a documented flag. Third, the project is maintained but not fast-moving: the last push was on 2026-07-17, roughly two months before this writing, with v1.2.0 landing the same day. That is fine for a stable generator and a problem if you need a vendor to answer a support question this week. If your real need is a collaborative canvas where five people drag boxes around a shared screen, this is the wrong category of tool entirely.

How it differs from Mermaid and PlantUML

The honest comparison is with text-to-diagram tools you already have. Mermaid and PlantUML both take a text description and emit a diagram, and both are embedded in code review tools and documentation platforms. The difference is who does the layout reasoning. In Mermaid and PlantUML you write a graph description and the renderer applies its own layout algorithm; you get whatever crossings and bends the algorithm produces, and fixing them means restructuring your source text. fireworks-tech-graph inverts that: you write prose, an agent decides the arrangement, and the arrangement is then checked against numeric constraints before export. That buys you control over crossings and spacing that a deterministic layout engine does not offer, at the cost of non-determinism. The same prompt can plausibly produce different geometry on different runs, and the README's answer to that is the regression fixture set under fixtures/quality-baseline/, described as internal, plus the static PNG baselines in assets/samples/. If you need byte-identical output from identical input, a deterministic text format is the better fit. If you need a diagram that survives a design review without a redraw, the constraint approach is the more direct route.

Licence, maintenance and upgrade cost

The project is MIT licensed, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are preserved. That is a permissive baseline and it is the same licence Mermaid and PlantUML-family tooling typically use, so it should clear most corporate review without discussion. The npm package files list is worth reading before you vendor anything: it includes SKILL.md, agents/, docs/, references/, schemas/, scripts/, tests/, fixtures/, templates/ and assets/, and excludes __pycache__ and .pyc files. That means an install pulls the reference material and fixtures, not just the generator. The maintenance picture is a single maintainer with a documented commercial contact address and a sponsorship section, plus a page offering paid sprints and design-partner work. Treat upgrade cost as a function of how much you customize. If you only call the skill, a version bump is a package update. If you edit templates or schemas to match your house style, every release is a potential merge, and the repository does ship a consistency checker specifically because the pieces have to stay aligned. Pin the version you validate against.

What to check before you commit

Three things are verifiable from the repository without running anything. First, open SKILL.md and confirm the skill description matches the agent host you actually use; the README claims Codex and Claude Code parity, and SKILL.md is where that claim lives. Second, open one file under schemas/ for the diagram type closest to your work. The four engineering-first styles advertise executable contracts, and a schema is where an executable contract is written down. Third, look at the prompt recipe in the README and try to map your own system onto one of the twelve scenarios. If nothing maps, the style you need probably does not exist yet, and the router will fall back to a generic theme without the domain contract you were counting on. The animated samples are useful here as a calibration reference: they show what the settled-flow timeline looks like at 960px and 20fps, which is the format you would actually ship in a README.

Editorial conclusion

Adopt fireworks-tech-graph if your diagrams are review artifacts for C4, cloud deployment, event streaming or reliability work and you already run Claude Code or Codex, because the executable composition contract (zero crossings, at most two bends per edge, at least 40px node spacing) is the part that saves review time. Do not adopt it if you need a browser-based drag-and-drop editor, a hosted collaborative canvas, or a tool that works without an agent host. Before committing, read SKILL.md and one schema under schemas/ to confirm the contracts cover your diagram type, then run the examples command and inspect the emitted SVG for the style you intend to use.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes