feat(deploy-on-aws): add architecture diagram generation skill#84
feat(deploy-on-aws): add architecture diagram generation skill#84MichaelWalker-git wants to merge 16 commits intoawslabs:mainfrom
Conversation
Add a diagram skill to the deploy-on-aws plugin that generates architecture diagrams using the Python diagrams DSL. This skill replaces the aws-diagram-mcp-server with a lighter-weight approach that runs diagram code directly via the agent's Bash tool. Includes: - Core SKILL.md with workflows, critical rules, and prerequisites - DSL syntax reference (Diagram, Cluster, Edge, all providers) - AWS service categories with 5 runnable examples - Non-AWS providers (K8s, on-prem, flowchart, custom) with 4 examples - Updated plugin.json and marketplace.json with diagram keywords
There was a problem hiding this comment.
Pull request overview
Adds a new diagram skill to the deploy-on-aws plugin to generate architecture diagrams via the Python diagrams DSL, and updates plugin/marketplace metadata and top-level docs to surface the new capability.
Changes:
- Introduces
plugins/deploy-on-aws/skills/diagram/SKILL.mdwith workflow, rules, and prerequisites for diagram generation. - Adds diagram DSL/provider reference docs with runnable examples (AWS and non-AWS).
- Updates plugin metadata (
plugin.json,marketplace.json) and rootREADME.mdto advertise the new skill and keywords/version bump.
Reviewed changes
Copilot reviewed 7 out of 7 changed files in this pull request and generated 6 comments.
Show a summary per file
| File | Description |
|---|---|
| plugins/deploy-on-aws/skills/diagram/SKILL.md | New skill definition + workflow/rules/prereqs for generating diagrams. |
| plugins/deploy-on-aws/skills/diagram/references/dsl-syntax.md | DSL syntax reference (constructors, edges, clusters, patterns). |
| plugins/deploy-on-aws/skills/diagram/references/aws-services.md | AWS import categories + AWS-focused runnable examples. |
| plugins/deploy-on-aws/skills/diagram/references/non-aws-providers.md | Non-AWS provider categories + K8s/on-prem/flowchart/custom icon examples. |
| plugins/deploy-on-aws/.claude-plugin/plugin.json | Adds diagram-related keywords and bumps plugin version to 1.2.0. |
| .claude-plugin/marketplace.json | Mirrors plugin metadata updates (description/keywords/tags/version). |
| README.md | Adds diagram trigger phrases to the deploy-on-aws skill table. |
plugins/deploy-on-aws/skills/diagram/references/aws-services.md
Outdated
Show resolved
Hide resolved
plugins/deploy-on-aws/skills/diagram/references/non-aws-providers.md
Outdated
Show resolved
Hide resolved
- Remove "sequence diagrams" claim (diagrams DSL doesn't produce UML
sequence diagrams, only flowchart-based process flows)
- Standardize on python3 instead of python in workflow commands
- Fix output verification to not assume PNG format
- Use ALB import instead of ELB("ALB") to avoid icon/label mismatch
- Replace urlretrieve with local icon file paths in custom node examples
to avoid external network dependencies and untrusted content
- Fix db_primary - [RDS()] list operator to use variable assignment
(- operator works between nodes, not node-to-list)
Normalize markdown table column widths to pass dprint check.
- Replace ELB("ALB") with ALB("ALB") in Clusters and Nested Clusters
examples (was missed in first fix round)
- Add .gitignore note for generated-diagrams/ output directory
Update the Diagram() constructor reference snippet to use generated-diagrams/ as the filename path, matching the skill's critical rules and other examples.
- Clarify PNG is default output format, not the only format - Fix invalid Edge() placeholder syntax with a real example - Remove unused Lambda import from basic structure example
plugins/deploy-on-aws/skills/diagram/references/non-aws-providers.md
Outdated
Show resolved
Hide resolved
- Wrap Diagram constructor in context manager so snippet is runnable - Fix mixed >> << operators in on-prem example to use consistent >> - Use python3 -m pip install for consistency with python3 workflow
plugins/deploy-on-aws/skills/diagram/references/aws-services.md
Outdated
Show resolved
Hide resolved
plugins/deploy-on-aws/skills/diagram/references/non-aws-providers.md
Outdated
Show resolved
Hide resolved
|
Diagram titles and node labels pass through to GraphViz. When outputting SVG, unsanitized user input with HTML/script tags could become an XSS vector if the SVG is later served on a web page. The skill provides no input sanitization guidance. |
- Remove Redshift from database category (only exists in analytics) - Clarify TB direction is a skill convention, not the library default - Move Namespace to k8s.group, add LimitRange/Limits to clusterconfig - Add SVG sanitization guidance to prevent XSS via unsanitized labels Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
plugins/deploy-on-aws/skills/diagram/references/aws-services.md
Outdated
Show resolved
Hide resolved
plugins/deploy-on-aws/skills/diagram/references/non-aws-providers.md
Outdated
Show resolved
Hide resolved
Code reviewFound 3 issues:
🤖 Generated with Claude Code - If this code review was useful, please react with 👍. Otherwise, react with 👎. |
…to examples Critical fixes (would cause ImportError): - Predefined -> PredefinedProcess (diagrams.programming.flowchart) - Fluentd -> Fluentbit (diagrams.onprem.logging) - DynamoDB -> Dynamodb (diagrams.aws.database) - EventBridge -> Eventbridge (diagrams.aws.integration) - CloudWatch -> Cloudwatch, CloudFormation -> Cloudformation (diagrams.aws.management) Important fixes: - Add direction="TB" to all examples missing it (skill convention) - Fix misleading flow direction comments in dsl-syntax.md - Fix AWS category count from 29 to 26 - Update README plugin description to mention diagram generation Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
…mments - Add import allowlist: ONLY diagrams.* modules, never os/subprocess/etc. - Add safe file path rule for Custom nodes (no absolute/traversal paths) - Pin diagrams version range (>=0.23,<1.0), suggest venv, add sudo warning - Expand error handling: syntax errors, runtime errors, empty output - Make Clusters and Nested Clusters snippets fully runnable with imports Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
|
|
||
| Generate architecture diagrams using the Python [diagrams](https://diagrams.mingrammer.com/) package. Write a Python script, run it, and produce an image (PNG by default). | ||
|
|
||
| Supports AWS (26 service categories), Kubernetes, on-premises, GCP, SaaS, and custom icons via the `diagrams` DSL. |
There was a problem hiding this comment.
The PR description says the diagram skill supports AWS "29 service categories", but the skill docs and references currently state/list 26 categories. Please reconcile the number either by updating the docs (if 29 is correct) or adjusting the PR description so they match to avoid confusion for users/maintainers.
| - Use `Cluster()` to group related resources (VPCs, subnets, namespaces) | ||
| - Use `Edge(label="HTTPS", color="darkgreen", style="dashed")` for labeled or styled connections | ||
| - **SVG sanitization**: When using `outformat="svg"`, sanitize all diagram titles, node labels, and edge labels — strip HTML tags and special characters (`<`, `>`, `&`, `"`, `'`) before passing them to the `diagrams` DSL. Unsanitized input rendered as SVG can become an XSS vector if served on a web page. | ||
| - **Import allowlist**: ONLY import from `diagrams.*` modules. NEVER import `os`, `sys`, `subprocess`, `shutil`, `socket`, `requests`, `urllib`, or any non-diagrams module. Before executing, review the generated script to confirm it contains ONLY diagrams DSL code. |
There was a problem hiding this comment.
The "Import allowlist" rule says to only import from diagrams.* modules, but all examples (and typical usage) require from diagrams import Diagram, Cluster, Edge. As written, this rule would incorrectly reject valid scripts. Consider rewording to allow imports from the diagrams package (both diagrams and diagrams.*) while still forbidding non-diagrams modules.
| - **Import allowlist**: ONLY import from `diagrams.*` modules. NEVER import `os`, `sys`, `subprocess`, `shutil`, `socket`, `requests`, `urllib`, or any non-diagrams module. Before executing, review the generated script to confirm it contains ONLY diagrams DSL code. | |
| - **Import allowlist**: ONLY import from the `diagrams` package (e.g., `import diagrams`, `from diagrams import Diagram, Cluster, Edge`, or `from diagrams.aws.compute import EC2`). NEVER import `os`, `sys`, `subprocess`, `shutil`, `socket`, `requests`, `urllib`, or any non-diagrams module. Before executing, review the generated script to confirm it contains ONLY diagrams DSL code. |
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Summary
diagramskill to thedeploy-on-awsplugin that generates architecture diagrams using the Python diagrams DSLaws-diagram-mcp-server(being deprecated in awslabs/mcp) with a lighter-weight skill that runs diagram code directly via the agent's Bash toolWhat's included
skills/diagram/SKILL.mdreferences/dsl-syntax.mdreferences/aws-services.mdreferences/non-aws-providers.mdAlso updates:
plugin.json— addsdiagram/architecturekeywords, bumps to v1.2.0marketplace.json— mirrors plugin.json updatesREADME.md— adds diagram trigger phrases to deploy-on-aws skill tablePrerequisites
The skill requires GraphViz and the Python
diagramspackage installed locally. SKILL.md documents install commands and error handling for missing dependencies.Context
This is part of the deprecation plan for
aws-diagram-mcp-server(awslabs/mcp#2597, #2598, #2599). The skill approach was chosen over keeping the MCP server because diagram generation is a write-then-run pattern that fits naturally into agent skills.Test plan
claude --plugin-dir ./plugins/deploy-on-awsmise run buildpassesmise run lint:manifestspassesmise run lint:cross-refspassesBy submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of the project license.