Ctrl K

Quick Ref / Command

Engineer Kit

/ak:diagram

Unified editorial diagrams

A deterministic diagram surface for Mermaid, 24 editorial template types, raw HTML, PNG/SVG stills, and MP4/GIF animated connector flows.

Route by Artifact

Pick Input Tier

Account for Limitation

Compose Editorial Frame

Rule 01

Pick by target artifact, not by the word diagram.

Rule 02

Editorial diagrams should carry meaning through geometry, palette, and animation.

Rule 03

Deterministic rendering matters: pinned Mermaid, browser, fonts, and frozen animations.

Rule 04

Raw HTML is the honest path when template slots are not declared yet.

Execution Map

Core lanes from input to output, aligned with the command's real execution path.

Start

Input, scope, route

1 Route by Artifact Choose ak:diagram for editorial PNG/SVG or short MP4/GIF; route editable canvases to ak:excalidraw, large graph exploration to ak:graphify, and plain Mermaid rendering to ak:mermaid if installed.
2 Pick Input Tier Use Tier 1 Mermaid, Tier 2 JSON plus --type when template slots exist, or Tier 3 raw HTML for fully composed pages.

Work

Agent / skill execution

3 Account for Limitation For current Tier 2 templates, start from vendored HTML and hand-customize because upstream examples do not yet expose replacement slots.
4 Compose Editorial Frame Use strict ink-on-paper palette, one accent, meaningful geometry, and mobile-safe self-contained HTML.

Verify

Gate, review, validation

5 Apply Animation For flows, attach connector effects such as marching-ants, comet, wave, morse, glow, silhouette, pulse, or dashed-flow.
6 Render Deterministically Run render.py for HTML/PNG/SVG or record.py for MP4/GIF with pinned Mermaid, Chromium, fonts, and animation freezing.

Report, handoff, artifact

7 Verify Goldens For intended visual changes, compare against snapshot hashes under the pinned Chromium/font profile before updating goldens.
8 Deliver Attribution Return generated artifacts and preserve Mermaid/template/effect attribution through the shared third-party notices ledger.

Syntax, arguments, subcommands

How to invoke the skill: syntax, positional arguments, shared options, then each subcommand with its own syntax and outcome.

Syntax

/ak:diagram [request]

Arguments

[request] Required

Diagram request

Natural-language source, target artifact, diagram type or visual goal, output destination, and permission boundaries for browser rendering, video capture, or dependency installation.

/ak:diagram Render checkout-flow.mmd as an editorial PNG and SVG in ./artifacts

Modes / Routes

Mermaid source

Tier 1

Research:: Read Mermaid input guidance
Review:: Check syntax and framing
Validate:: HTML/PNG/SVG emitted

JSON spec + type

Tier 2

Research:: Read per-type schema
Review:: Check template slot limitation
Validate:: Template render output

Raw HTML

Tier 3

Research:: Inspect composed page
Review:: Check mobile and animation
Validate:: Rendered artifact output

Special Operations

Tier 2 caveat

JSON specs are wired, but current vendored templates are finished exemplars without declared replacement slots.

Reduced motion

Connector effects freeze automatically under prefers-reduced-motion for accessible animated output.

Sample Prompt

Concrete invocations for each flag, subcommand, mode, or route available in the live workflow.

Mermaid to editorial PNG/SVG Recommended

/ak:diagram Render checkout-flow.mmd as an editorial PNG and SVG in ./artifacts with a dark frame, no dependency installation, and any unverified output called out.

Use when:: The desired artifact is a polished static diagram from Mermaid source, not a plain Mermaid render or editable canvas.
Expected:: Uses the Tier 1 Mermaid path with vendored Mermaid, wraps the source in the editorial frame, emits self-contained HTML plus PNG and extractable SVG when present, and reports dependency or renderer limits.

Animated connector video

/ak:diagram Create a six-second MP4 connector-flow animation from diagram.html for the checkout handoff; make a GIF only if I ask for it separately.

Use when:: A short video better explains movement or handoff than a still image.
Expected:: Treats video as a separate recording step over prepared HTML, uses the bundled connector effects where appropriate, emits MP4 by default, and notes ffmpeg plus frame-capture requirements.

Hand-customized template

/ak:diagram Render my hand-edited loop.html as a mobile-safe editorial HTML and PNG; do not rely on JSON slot replacement.

Use when:: You need one of the editorial template looks today, but the current vendored templates do not expose useful JSON replacement slots.
Expected:: Uses the Tier 3 raw-HTML path, preserves the composed page content, renders the self-contained HTML and PNG, and avoids promising structured JSON fields will populate the template.

Dependency readiness probe

/ak:diagram Check whether this environment can render PNG/SVG and record MP4 for ./diagrams without installing anything.

Use when:: Before rendering, you need to know whether Playwright, Chromium, vendored Mermaid, and ffmpeg are available without changing the environment.
Expected:: Runs the non-installing dependency probe, separates browser-rendered static output from video requirements, and reports missing tools as approval-needed setup rather than silently installing them.

Handled Scope

Mermaid v11 wrapping and SVG extraction
Twenty-four editorial diagram base types with light, dark, and full variants
Self-contained HTML, PNG screenshots, SVG extraction, and video recording
Zero-dependency connector effects and reduced-motion handling
Snapshot hashes, pinned renderer profiles, and vendored template source records

Artifacts Produced

Diagram Artifacts

Pattern

<basename>.html + <basename>.png + optional .svg/.mp4/.gif

Self-contained HTML, deterministic 2× PNG, extracted SVG when present, and reproducible MP4/GIF recordings for animated flows.