Generate evidence-backed diagrams with ak:tech-graph

Use ak:tech-graph to create publish-grade technical diagrams as editable SVG and high-resolution PNG files. The Skill turns an approved system description into nodes, relationships, semantic arrows, and a layout, validates the SVG, renders it locally, and reports both artifacts.

Choose ak:tech-graph for durable visual artifacts

Use ak:tech-graph when

• You need an architecture, data-flow, sequence, process, UML, ER, network, or agent-memory diagram for publication.
• A static SVG and PNG pair is more useful than an inline diagram definition.
• Arrow meaning, grouping, labels, and visual style must be reviewable.
• You want to render a structured JSON fixture through a bundled template.

Choose another workflow when

• You need a quick inline diagram inside documentation. Use the project's Mermaid workflow instead.
• You need raw source packaged for analysis. Use ak:repomix.
• You need repository facts before drawing. Use ak:scout and treat source, configuration, tests, and current docs as the diagram's evidence.
• You need an image that is not a technical graph. Use the appropriate image or preview workflow.

Prepare the evidence and renderer

Before you start:

• Complete Onboarding, and confirm Engineer Kit is installed for the runtime and scope you use.
• Provide the audience, diagram type, components, boundaries, relationships, direction of flow, labels, desired style, and output destination.
• For an existing system, identify the primary sources that prove each node and edge: code, manifests, schemas, deployment configuration, tests, or official architecture documentation. Mark assumptions instead of drawing them as fact.
• Verify rsvg-convert is available. It comes from librsvg and is required for PNG export.
• Confirm the destination can hold both SVG and PNG files and that publication or upload remains outside the run unless separately approved.

Run the Skill

/ak:tech-graph "Create a data-flow diagram from the current authentication docs and deployment config. Show browser, gateway, auth service, session store, and audit sink; label every payload and assumption; style 1; write ./artifacts/auth-flow.svg and PNG."

/ak:tech-graph "Create a data-flow diagram from the current authentication docs and deployment config. Show browser, gateway, auth service, session store, and audit sink; label every payload and assumption; style 1; write ./artifacts/auth-flow.svg and PNG."

$ak:tech-graph "Create a data-flow diagram from the current authentication docs and deployment config. Show browser, gateway, auth service, session store, and audit sink; label every payload and assumption; style 1; write ./artifacts/auth-flow.svg and PNG."

The Skill accepts a diagram type or system description. It has no published mode flag. Style 1, Flat Icon, is the default; styles 2–7 select Dark Terminal, Blueprint, Notion Clean, Glassmorphism, Claude Official, or OpenAI Official.

Choose a generation path

Without a custom path, the source-defined deliverables are ./[derived-name].svg and ./[derived-name].png. PNG export defaults to 1920 pixels wide. The template generator supports architecture, flowchart, data-flow, sequence, comparison, timeline, mind-map, agent, memory, use-case, class, state-machine, ER, and network-topology structures.

Understand what happens during a run

1. The Skill establishes factual scope. It separates source-backed components and flows from requested abstractions and unresolved assumptions.
2. It classifies the diagram. The type determines layers, lifelines, cardinalities, states, actors, or other layout semantics.
3. It selects a style. The matching style reference supplies colors, typography, shapes, spacing, and arrow conventions.
4. It plans the graph. Nodes, edges, groups, ports, legends, labels, and routing corridors are laid out before file generation.
5. It writes and validates SVG. Validation checks XML, tag balance, quoting, marker references, simple arrow collisions, closing tags, and renderer compatibility when tools are available.
6. It exports and reviews PNG. rsvg-convert creates the raster artifact; an image-capable runtime inspects overlap, clipped text, crossings, and legend placement, then revises and rerenders when needed.
7. It reports evidence and files. The result names both paths, validation, source basis, assumptions, and any visual-review limitation.

Keep diagrams accurate and safe

• SVG and PNG are persistent files. Confirm before overwriting an existing artifact or writing outside the project boundary.
• Source-defined generation and rendering are local and require no provider, credential, network call, or paid service. Installing librsvg, reading remote sources, or publishing the outputs are separate effects that need approval.
• Do not embed secrets, private hostnames, customer data, internal URLs, or credentials in labels, metadata, file names, or screenshots.
• Avoid external font imports; they can break local rendering and add network dependencies. Keep fonts and SVG resources self-contained.
• Skipping validation or visual review lowers evidence quality. If image reading is unavailable, report that visual correctness was not inspected.

Verify the result

A complete result includes the source-backed graph specification, exact SVG and PNG paths, diagram type and style, render width, validator result, a visual review statement, and unresolved assumptions. Check that every label fits, arrows connect to component edges, crossings are unambiguous, legends explain multiple flow types, and the output remains readable at its intended size.

The bundled regression suite renders one fixture for each style, validates the SVGs, and exports PNGs when rsvg-convert exists. It demonstrates generator and style coverage, not factual accuracy of a new diagram.

Troubleshoot or continue

Know the current limits

• The Skill does not automatically discover an architecture or dependency graph; it needs a supplied description or approved project inspection.
• Shell validation catches a bounded set of structural and routing problems; it does not replace visual inspection or accessibility review.
• Runtime depends on graph complexity and revision cycles. Simple template renders are local and quick; dense publication diagrams can require several inspect-and-rerender passes.
• Stable and beta package identical ak:tech-graph generators, fixtures, styles, and validation workflow.