pretty-azure-mermaid-skills

Pretty Azure Mermaid

Use this skill to produce publication-ready Microsoft Azure architecture diagrams as Mermaid source. This file is the lightweight activation and routing guide; load the referenced files only when the task needs that detail.

Invoke When

Use this skill when the user asks for any of:

• •A new Azure architecture diagram: context, runtime, deployment, network,

data-flow, identity, availability, or compliance.

• •An update to an existing Mermaid architecture diagram.
• •Help choosing the right Azure icon for a service.
• •Theming, branding, accessibility, or dark-mode treatment.
• •Validating that a diagram only references real bundled Azure icons.
• •Rendering a diagram to SVG/PNG for docs, README, slides, or review handoff.

Common trigger phrases: "draw an Azure architecture", "diagram this AKS deployment", "hub-spoke network", "Azure landing zone diagram", "RAG architecture on Azure", "convert this ASCII architecture to Mermaid", and "add monitoring to this diagram".

Deliverable Contract

• •Source of truth is .mmd Mermaid using the local Azure iconpack

(azure:<name> aliases from references/ICON_CATALOG.md).

• •Prefer flowchart icon nodes for starter diagrams, split views, runtime

flows, and any dense view that must render predictably.

• •Use architecture-beta only for small grouped service maps where automatic

layout remains readable.

• •For GitHub markdown, Mermaid Live, or any hosted surface that cannot load

dist/azure-icons-mermaid.json, render SVG/PNG assets and link those images.

• •For rendered deliverables, capture the target surface, artifact type, aspect

ratio or viewport, and whether SVG, PNG, or both are required.

• •Complex requests may require a split bundle: manifest + multiple .mmd

files, one concern per view.

Full runbook: references/AUTHORING_WORKFLOW.md.

Required Workflow

1. Triage before drafting. Read references/HITL_AND_SPLIT_VIEW.md and

count the HITL triggers. If 2 or more fire, ask 3-6 targeted questions and wait. Include target surface, artifact type, and render size/aspect when the output is not source-only. Use the host's structured question tool when available. If a hard split trigger fires, produce a split bundle unless the user explicitly chooses one canvas.

1. Choose the view and renderer. Read references/DIAGRAM_TYPES.md and

references/ARCHITECTURE_PATTERNS.md. Identify the diagram concern: runtime flow, network topology, identity, data lineage, deployment, observability, controls, or context.

1. Start template-first. Do not freehand from an empty flowchart LR when

a template covers at least half of the requested services or concern. Run npm run new -- --list, fork the closest template, and record the template name + fit score in a %% header comment.

1. Add services with official icons. Search aliases with

npm run icons:search -- <term> or use references/ICON_CATALOG.md. Prefer friendly aliases such as azure:aks, azure:apim, azure:cosmos-db, azure:sql-db, and azure:waf.

1. Compose groups and edges. Read references/COMPOSITION_RULES.md

before writing edges. Use real boundaries for groups, junctions for 3+ way fan-out, pos: "b" on flowchart icon nodes, and protocol/intent/auth labels on cross-boundary edges.

1. Theme and metadata. Copy a frontmatter theme from

references/THEMES.md. Never recolour Azure icons. Every publishable diagram needs title, description, diagramType, audience, updated, and source references in frontmatter.

1. Validate semantics, not just syntax. Run npm run check, then walk

references/ARCHITECTURE_REVIEW.md and references/QUALITY_BAR.md. If the host exposes Microsoft Learn docs tools, use them for non-obvious edges; otherwise ask the user to confirm architecture-sensitive assumptions.

1. Preview the render. Open assets/viewer.html or run the renderer and

inspect the actual SVG/PNG at the target size. Apply references/VISUAL_DESIGN.md; split, simplify, or rerender with a better viewport if the canvas is unreadable, oversized, or mostly whitespace.

Reference Router

Fast Commands

npm run new -- --list
npm run new -- --template rag-chatbot --out docs/diagrams/agent-mcp-rag.mmd

npm run icons:search -- "cosmos"
npm run icons:search -- --category networking
npm run icons:search -- --aliases

npm run check
npm run validate
npm run parse
npm run lint:edges

npm run render -- --input docs/orders.mmd --output docs/orders.svg
npm run render -- --input docs/orders.mmd --output docs/orders.png --format png --scale 8
npm run render -- --input docs/orders.mmd --output docs/orders.png --format png --width 1600 --height 1000 --scale 8
npm run render:all -- --input-dir docs --output-dir docs/rendered

Host Behavior

• •This skill does not bundle an MCP server. Microsoft Learn review is optional

and depends on the host tools available in GitHub Copilot, Claude Code, Cursor, Agent Framework, or another compatible assistant.

• •If structured HITL tools are unavailable, ask the same questions directly in

chat and wait for answers.

• •If script execution is unavailable, provide the command for the user or run

the closest local validation tool the host allows.

• •If a target render surface cannot load the local iconpack, pre-render assets

instead of expecting inline Mermaid to show Azure icons.

Non-Negotiables

• •Do not draft before the HITL gate passes.
• •Do not mix runtime, network, identity, ops, and ingestion in one dense canvas.
• •Do not invent services, SKUs, arrows, trust boundaries, or source references.
• •Do not use layout-only arrows or bidirectional <--> shortcuts.
• •Do not place a PaaS service inside a subnet when the architecture uses a

Private Endpoint; draw the Private Endpoint in the subnet instead.

• •Do not recolour, distort, or use Microsoft Azure icons outside Azure

architecture diagrams. See ICONS_NOTICE.md.

References

• •references/AUTHORING_WORKFLOW.md - expanded authoring workflow.
• •references/QUALITY_BAR.md - final quality checklist.
• •references/BEST_PRACTICES.md - Well-Architected design-diagram rules.
• •references/ARCHITECTURE_REVIEW.md - semantic arrow review.
• •references/VISUAL_DESIGN.md - render-time readability gate.
• •assets/templates/ - starter diagrams.
• •Mermaid flowchart docs: https://mermaid.js.org/syntax/flowchart.html
• •Mermaid architecture-beta docs: https://mermaid.js.org/syntax/architecture.html
• •Microsoft Well-Architected design diagrams: https://learn.microsoft.com/azure/well-architected/architect-role/design-diagrams
• •Microsoft Azure icon terms: https://learn.microsoft.com/azure/architecture/icons/