| name | azure-diagrams |
| description | Generates professional Azure architecture diagrams and data-visualization charts (WAF pillar scores, cost distribution, cost projection). Produces Python `diagrams` + matplotlib artifacts (`.py` + `.png`) for Step 2 WAF charts, Step 3 design visuals, and Step 7 as-built documentation. |
| compatibility | Requires graphviz system package and Python diagrams library; works with Claude Code, GitHub Copilot, VS Code, and any Agent Skills compatible tool. |
| license | MIT |
| metadata | {"author":"cmb211087","version":"5.0","repository":"https://github.com/mingrammer/diagrams"} |
Azure Architecture Diagrams Skill
Generate professional Azure architecture diagrams and data-visualization charts using
Python's diagrams library and matplotlib. Load reference files on demand for patterns.
Reference Files (Load on Demand)
| File | When to Load |
|---|
references/output-standards.md | Professional template, connection syntax, clusters, troubleshooting |
references/azure-components.md | Complete list of 700+ Azure components |
references/common-patterns.md | Ready-to-use architecture patterns (3-tier, microservices, etc.) |
references/waf-cost-charts.md | WAF pillar bar, cost donut & projection chart implementations |
references/iac-to-diagram.md | Generate diagrams from Bicep/Terraform/ARM |
references/preventing-overlaps.md | Layout troubleshooting guide |
references/business-process-flows.md | Workflow and swimlane diagrams |
references/entity-relationship-diagrams.md | Database ERD patterns |
references/timeline-gantt-diagrams.md | Project timeline diagrams |
references/ui-wireframe-diagrams.md | UI mockup patterns |
references/sequence-auth-flows.md | Authentication flow patterns |
references/quick-reference.md | Copy-paste code snippets |
references/integration-services.md | Integration service patterns |
references/migration-patterns.md | Migration diagram patterns |
Output Format
| Format | File Extension | Tool | Use Case |
|---|
| Python PNG | .py + .png | diagrams library | Programmatic, version-controlled, CI |
| SVG | .svg | diagrams library | Web documentation (optional) |
Execution Method
Always save diagram source to file first, then execute it:
python3 agent-output/{project}/03-des-diagram.py
- ✅ Generate and save
.py source in agent-output/{project}/
- ✅ Execute saved script to produce
.png
- ✅ Keep source version-controlled for deterministic regeneration
Architecture Diagram Contract (Mandatory)
Generate non-Mermaid diagrams using Python diagrams only.
Required outputs
03-des-diagram.py + .png (Step 3)04-dependency-diagram.py + .png (Step 4)04-runtime-diagram.py + .png (Step 4)07-ab-diagram.py + .png (Step 7, when requested)
Required naming conventions
- Cluster vars:
clu_<scope>_<slug> where scope ∈ sub|rg|net|tier|zone|ext
- Node vars:
n_<domain>_<service>_<role> where domain ∈ edge|web|app|data|id|sec|ops|int
- Edge vars (if reused):
e_<source>_to_<target>_<flow>
- Flow taxonomy only:
auth|request|response|read|write|event|replicate|secret|telemetry|admin
Required layout/style defaults
direction="LR" unless explicitly justified- deterministic spacing via
graph_attr (nodesep, ranksep, splines)
- short labels (2–4 words), max 3 edge styles
Read references/output-standards.md for the full professional template and settings.
Quality gate (score /10)
- Readable at 100% zoom
- No major label overlap
- Minimal line crossing
- Clear tier grouping
- Correct Azure icons
- Security boundary visible
- Data flow direction clear
- Identity/auth flow visible
- Telemetry path visible
- Naming conventions followed
If score < 9/10, regenerate once with simplification.
Prerequisites
pip install diagrams matplotlib pillow
apt-get install -y graphviz
Workflow Integration
| Workflow Step | File Pattern | Description |
|---|
| Step 2 | 02-waf-scores.py/.png | WAF pillar score bar chart |
| Step 3 (Design) | 03-des-diagram.py/.png | Proposed architecture visualization |
| Step 3 (Design) | 03-des-cost-distribution.py/.png | Monthly cost distribution donut chart |
| Step 3 (Design) | 03-des-cost-projection.py/.png | 6-month cost projection bar + trend chart |
| Step 7 (As-Built) | 07-ab-diagram.py/.png | Deployed architecture documentation |
| Step 7 (As-Built) | 07-ab-cost-distribution.py/.png | As-built cost distribution donut chart |
| Step 7 (As-Built) | 07-ab-cost-projection.py/.png | As-built 6-month cost projection chart |
| Step 7 (As-Built) | 07-ab-cost-comparison.py/.png | Design estimate vs as-built grouped bars |
| Step 7 (As-Built) | 07-ab-compliance-gaps.py/.png | Compliance gaps by severity horizontal bar |
Artifact Suffix Convention
-des: Design diagrams (Step 3 artifacts) — proposed/conceptual-ab: As-built diagrams (Step 7 artifacts) — deployed/actual
Data Visualization Charts
Styled matplotlib charts for WAF scores and cost estimates. See references/waf-cost-charts.md
for full Python implementations.
When to generate
| Trigger | Chart(s) to generate |
|---|
| After WAF scoring | 02-waf-scores.png — horizontal bar, one colour per pillar |
| After cost design | 03-des-cost-distribution.png + 03-des-cost-projection.png |
| After as-built | 07-ab-cost-distribution.png + 07-ab-cost-projection.png + 07-ab-cost-comparison.png |
| After compliance | 07-ab-compliance-gaps.png — gap counts by severity |
Design tokens (use consistently)
| Token | Value | Usage |
|---|
| Background | #F8F9FA | Figure + axes fill |
| Azure blue | #0078D4 | Primary bars |
| Minimum line | #DC3545 | Red dashed WAF reference |
| Target line | #28A745 | Green dashed WAF reference |
| Trend line | #FF8C00 | Orange dashed projection |
| DPI | 150 | Crisp PNG output |
WAF pillar colours
| Pillar | Hex colour |
|---|
| 🔒 Security | #C00000 |
| 🔄 Reliability | #107C10 |
| ⚡ Performance Efficiency | #FF8C00 |
| 💰 Cost Optimization | #FFB900 |
| 🔧 Operational Excellence | #8764B8 |
Generation Workflow
- Gather Context — Read Bicep templates, deployment summary, or architecture assessment
- Identify Resources — List all Azure resources to visualize
- Determine Hierarchy — Map Subscription → RG → VNet → Subnet structure
- Generate Python Code — Read
references/output-standards.md for template
- Execute Script — Run Python to generate PNG
- Verify Output — Confirm PNG file was created successfully
Guardrails
DO
- ✅ Create diagram files in
agent-output/{project}/
- ✅ Use step-prefixed filenames (
03-des-* or 07-ab-*)
- ✅ Use valid
diagrams.azure.* imports only
- ✅ Include docstring with prerequisites and generation command
- ✅ ALWAYS execute the Python script to generate the PNG file
- ✅ Use
references/waf-cost-charts.md patterns for WAF / cost charts
- ✅ Apply the design tokens table to every chart
DO NOT
- ❌ Use invalid or made-up diagram node types
- ❌ Create diagrams that don't match the actual architecture
- ❌ Skip the PNG generation step
- ❌ Output to legacy
docs/diagrams/ folder (use agent-output/ instead)
- ❌ Use Mermaid
xychart-beta for WAF or cost charts (always use matplotlib PNGs)
What This Skill Does NOT Do
- Generate Bicep or Terraform code (use
bicep-code agent)
- Create workload documentation (use
azure-artifacts skill)
- Deploy resources (use
deploy agent)
- Create ADRs (use
azure-adr skill)
- Perform WAF assessments (use
architect agent)
