/fireworks-tech-graph

name: fireworks-tech-graph
description: >-
  Create technical diagrams such as software architecture, data flow,
  flowcharts, sequence diagrams, C4 reviews, cloud deployments, event streams,
  observability investigations, agent/memory systems, UML, ER, network
  topology, timelines, and technical concept maps, then export SVG, PNG,
  focused semantic SVG-to-GIF motion, or offline interactive HTML. Treat direct
  requests such as "Generate a GIF", "生成 GIF", or "制作 GIF" as motion requests,
  and use this skill when the user asks to visualize a system or engineering
  concept. Do not use for photos, raster artwork, or quantitative data charts.

Fireworks Tech Graph

Generate geometry-checked SVG technical diagrams, high-resolution PNG, validated SVG-to-GIF semantic motion, and sanitized offline interactive HTML.

Runtime Compatibility

Use this repository unchanged in both Codex and Claude Code. It follows the Agent Skills layout: `SKILL.md` is the shared entry point, bundled resources use relative paths, and `agents/openai.yaml` adds optional Codex UI metadata without affecting Claude Code.

Before reading a reference or running a script, resolve the directory containing this `SKILL.md` as `SKILL_ROOT`. Do not assume the current working directory is the skill directory, and do not assume a variable set in one shell call persists into the next.

• In Claude Code, use `${CLAUDE_SKILL_DIR}`.
• In Codex, use the absolute skill directory shown in the loaded skill metadata.

Every command block below sets `SKILL_ROOT` itself. In Codex, replace `/absolute/path/from-codex-skill-metadata` with the absolute skill directory before running the command.

Helper Scripts (Recommended)

The unified `scripts/fireworks.py` CLI and compatibility helpers provide stable rendering, geometry validation, inspection, animation, and export:

1. `generate-diagram.sh` - Validate SVG + export PNG

SKILL_ROOT="${CLAUDE_SKILL_DIR:-/absolute/path/from-codex-skill-metadata}"
"$SKILL_ROOT/scripts/generate-diagram.sh" -t architecture -s 1 -o ./output/arch.svg

• Validates an existing SVG file
• Exports PNG after validation
• Example: `"$SKILL_ROOT/scripts/generate-diagram.sh" -t architecture -s 1 -o ./output/arch.svg`

2. `generate-from-template.py` - Create starter SVG from template

SKILL_ROOT="${CLAUDE_SKILL_DIR:-/absolute/path/from-codex-skill-metadata}"
mkdir -p ./output
python3 "$SKILL_ROOT/scripts/generate-from-template.py" architecture ./output/arch.svg '{"title":"My Diagram","nodes":[],"arrows":[]}'

• Loads a built-in SVG template
• Renders nodes, arrows, and legend entries from JSON input
• Escapes text content to keep output XML-valid

3. `validate-svg.sh` - Validate SVG syntax

SKILL_ROOT="${CLAUDE_SKILL_DIR:-/absolute/path/from-codex-skill-metadata}"
"$SKILL_ROOT/scripts/validate-svg.sh" <svg-file>

• Checks XML syntax
• Verifies tag balance
• Validates marker references
• Checks attribute completeness
• Validates path data

4. `test-all-styles.sh` - Batch test all styles

SKILL_ROOT="${CLAUDE_SKILL_DIR:-/absolute/path/from-codex-skill-metadata}"
"$SKILL_ROOT/scripts/test-all-styles.sh"

• Tests multiple diagram sizes
• Validates all generated SVGs
• Generates test report

**When to use scripts:**

• Use scripts when generating complex SVGs to avoid syntax errors
• Scripts provide automatic validation and error reporting
• Recommended for production diagrams

Workflow (Always Follow This Order)

1. **Classify** the diagram type (see Diagram Types below) 2. **Extract structure** — identify layers, nodes, edges, flows, and semantic groups from user description 3. **Plan layout** — load `$SKILL_ROOT/references/composition-quality-contract.md`, then apply the diagram-type layout rules 4. **Load style reference** — always load `$SKILL_ROOT/references/style-1-flat-icon.md` unless user specifies another; load the matching `$SKILL_ROOT/references/style-N-*.md` for exact color tokens and SVG patterns 5. **Select semantic contract** — Styles 9–12 default to `c4-review`, `cloud-fabric`, `event-transit`, and `ops-pulse`; use `scripts/fireworks.py validate` before layout so missing or contradictory engineering facts fail closed 6. **Map nodes to shapes** — use Shape Vocabulary below 7. **Check icon needs** — load `$SKILL_ROOT/references/icons.md` for known products 8. **Write SVG** with adaptive strategy (see SVG Generation Strategy below) 9. **Validate**: Run `"$SKILL_ROOT/scripts/validate-svg.sh" file.svg` to check XML, markers, geometry, composition budgets, and renderability 10. **Export PNG**: Use `cairosvg` (recommended). Load `$SKILL_ROOT/references/png-export.md` when choosing another renderer 11. **Animate on request** — `让这张图动起来` / `生成 GIF` / `制作 GIF` / `Animate this diagram` / `Generate a GIF` means the latest generated semantic SVG to one GIF with `auto`, 5.75s, 20fps, and 960px width when that SVG satisfies one of the 12 approved motion contracts. Exact source bytes are not pinned, but role/stage/order coverage, route directions, required colors, and geometry fail closed; do not claim arbitrary same-style topologies are supported. Load `$SKILL_ROOT/references/motion-effects.md`, run `fireworks.py animate`, and report SVG/GIF/report paths. GIF is the only motion media format, while the default command also emits `<output>.motion.json`. Styles 1–12 are enabled, and their contracts plus the shared `+2s-settled-flow` timing revision are user-approved; the default keeps frames 38–109 at full opacity and resets on frames 110–114. Every scene begins connector-free and advances its moving primitives toward each target. The 75-vs-115 compatibility gate counts binary-exact frames first, decoded-RGBA-exact frames second, and permits a guarded antialias equivalent only when AE ≤ 128, normalized RMSE ≤ 0.001, every difference component is at most 2px wide or high, and all differences remain on edge or node borders; DOM and signature geometry stay s