feat(deploy-on-aws): add architecture diagram generation skill by MichaelWalker-git · Pull Request #84 · awslabs/agent-plugins

MichaelWalker-git · 2026-03-07T00:16:52Z

Summary

Adds a diagram skill to the deploy-on-aws plugin that generates architecture diagrams using the Python diagrams DSL
Replaces the aws-diagram-mcp-server (being deprecated in awslabs/mcp) with a lighter-weight skill that runs diagram code directly via the agent's Bash tool
Supports AWS (29 service categories), Kubernetes, on-premises, SaaS, flowcharts, and custom icons

What's included

File	Lines	Purpose
`skills/diagram/SKILL.md`	80	Core skill: workflows, critical rules, prerequisites, error handling
`references/dsl-syntax.md`	110	DSL syntax: Diagram/Cluster/Edge constructors, connections, provider import paths
`references/aws-services.md`	111	AWS service categories, common icons, 5 runnable examples
`references/non-aws-providers.md`	122	K8s, on-prem, flowchart providers, 4 runnable examples

Also updates:

plugin.json — adds diagram/architecture keywords, bumps to v1.2.0
marketplace.json — mirrors plugin.json updates
README.md — adds diagram trigger phrases to deploy-on-aws skill table

Prerequisites

The skill requires GraphViz and the Python diagrams package 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

Install plugin: claude --plugin-dir ./plugins/deploy-on-aws
Verify diagram skill auto-triggers on "draw an architecture diagram"
Generate AWS diagram from aws-services.md examples
Generate K8s diagram from non-aws-providers.md examples
Generate flowchart from non-aws-providers.md examples
Verify mise run build passes
Verify mise run lint:manifests passes
Verify mise run lint:cross-refs passes

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

Copilot

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.md with 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 root README.md to 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.

Copilot · 2026-03-07T00:21:17Z

plugins/deploy-on-aws/skills/diagram/SKILL.md

+
+- **Any diagram** -> ALWAYS load [references/dsl-syntax.md](references/dsl-syntax.md) first for DSL syntax, constructor options, connections, clusters, and edge styles
+- **AWS architecture**, **cloud infrastructure**, or **AWS services** -> load [references/aws-services.md](references/aws-services.md) for AWS import paths, common icons, and 5 AWS examples
+- **Kubernetes**, **on-premises**, **SaaS**, **flowcharts**, **sequence diagrams**, **custom icons**, or **non-AWS diagrams** -> load [references/non-aws-providers.md](references/non-aws-providers.md) for K8s, on-prem, flowchart, and custom icon examples


The skill claims support for "sequence diagrams", but the Python diagrams DSL (GraphViz-based) doesn't produce UML sequence diagrams. Please remove this trigger/category or clarify what diagram types are actually supported.

Suggested change

- **Kubernetes**, **on-premises**, **SaaS**, **flowcharts**, **sequence diagrams**, **custom icons**, or **non-AWS diagrams** -> load [references/non-aws-providers.md](references/non-aws-providers.md) for K8s, on-prem, flowchart, and custom icon examples

- **Kubernetes**, **on-premises**, **SaaS**, **flowcharts**, **custom icons**, or **non-AWS diagrams** -> load [references/non-aws-providers.md](references/non-aws-providers.md) for K8s, on-prem, flowchart, and custom icon examples

Copilot · 2026-03-07T00:21:18Z

plugins/deploy-on-aws/skills/diagram/SKILL.md

+3. Write a Python script using the `diagrams` DSL
+4. Run: `mkdir -p generated-diagrams && python diagram.py`
+5. Verify the PNG was created in `generated-diagrams/`


The workflow uses python diagram.py but the prerequisites/verification use python3. Using python can invoke Python 2 or a different environment. Also, step 5 says to verify a PNG even though outformat can be overridden (e.g., SVG). Consider standardizing on python3 and verifying the generated file based on the chosen outformat.

Copilot · 2026-03-07T00:21:18Z

plugins/deploy-on-aws/skills/diagram/references/aws-services.md

+        svc_group = [ECS("web1"), ECS("web2"), ECS("web3")]
+    with Cluster("DB Cluster"):
+        db_primary = RDS("userdb")
+        db_primary - [RDS("userdb ro")]


This example uses db_primary - [RDS("userdb ro")]. The - operator in the diagrams DSL is typically used between nodes, not a list, so this is likely to fail at runtime. Use a single replica node (or assign the replica to a variable) instead of wrapping it in a list.

Suggested change

db_primary - [RDS("userdb ro")]

db_replica = RDS("userdb ro")

db_primary - db_replica

Copilot · 2026-03-07T00:21:18Z

plugins/deploy-on-aws/skills/diagram/references/dsl-syntax.md

+from diagrams.aws.network import ELB
+
+with Diagram("Title", show=False, filename="generated-diagrams/name"):
+    with Cluster("VPC"):
+        lb = ELB("ALB")


In the basic structure example, ELB("ALB") mixes the ELB icon with an "ALB" label. If the intent is an Application Load Balancer, use the ALB node/icon; otherwise rename the label to avoid confusion.

Suggested change

from diagrams.aws.network import ELB

with Diagram("Title", show=False, filename="generated-diagrams/name"):

with Cluster("VPC"):

lb = ELB("ALB")

from diagrams.aws.network import ALB

with Diagram("Title", show=False, filename="generated-diagrams/name"):

with Cluster("VPC"):

lb = ALB("ALB")

Copilot · 2026-03-07T00:21:19Z

plugins/deploy-on-aws/skills/diagram/references/dsl-syntax.md

+from urllib.request import urlretrieve
+
+icon_path, _ = urlretrieve("https://example.com/icon.png", "icon.png")


The custom node example downloads an icon at runtime via urlretrieve, which adds an external network dependency and can pull untrusted content. Prefer referencing a local icon file path (or document a separate, manual download step with integrity verification) so diagram generation is deterministic and safer.

Suggested change

from urllib.request import urlretrieve

icon_path, _ = urlretrieve("https://example.com/icon.png", "icon.png")

# Use a local icon file. Download or place the icon in your project beforehand.

icon_path = "icons/my-service.png"

Copilot · 2026-03-07T00:21:19Z

plugins/deploy-on-aws/skills/diagram/references/non-aws-providers.md

+from urllib.request import urlretrieve
+
+rabbitmq_url = "https://jpadilla.github.io/rabbitmqapp/assets/img/icon.png"
+rabbitmq_icon, _ = urlretrieve(rabbitmq_url, "rabbitmq.png")


This example downloads a custom icon from the public internet (urlretrieve). That makes the example non-deterministic/offline-unfriendly and can pull untrusted content when users run it. Consider switching to a local icon file path (or document a separate, manual download step with integrity verification).

Suggested change

from urllib.request import urlretrieve

rabbitmq_url = "https://jpadilla.github.io/rabbitmqapp/assets/img/icon.png"

rabbitmq_icon, _ = urlretrieve(rabbitmq_url, "rabbitmq.png")

# Use a local RabbitMQ icon file. Download an appropriate PNG (for example,

# from the official RabbitMQ resources) and save it as "rabbitmq.png" in

# the working directory before running this example.

rabbitmq_icon = "rabbitmq.png"

MichaelWalker-git requested review from a team, Copilot, krokoko, scottschreckengaust and theagenticguy March 7, 2026 00:16

MichaelWalker-git requested review from a team as code owners March 7, 2026 00:16

Copilot started reviewing on behalf of MichaelWalker-git March 7, 2026 00:17 View session

Copilot AI reviewed Mar 7, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(deploy-on-aws): add architecture diagram generation skill#84

feat(deploy-on-aws): add architecture diagram generation skill#84
MichaelWalker-git wants to merge 1 commit intoawslabs:mainfrom
MichaelWalker-git:feat/diagram-skill

MichaelWalker-git commented Mar 7, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Mar 7, 2026

Uh oh!

Copilot AI Mar 7, 2026

Uh oh!

Copilot AI Mar 7, 2026

Uh oh!

Copilot AI Mar 7, 2026

Uh oh!

Copilot AI Mar 7, 2026

Uh oh!

Copilot AI Mar 7, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	- Kubernetes, on-premises, SaaS, flowcharts, sequence diagrams, custom icons, or non-AWS diagrams -> load [references/non-aws-providers.md](references/non-aws-providers.md) for K8s, on-prem, flowchart, and custom icon examples
	- Kubernetes, on-premises, SaaS, flowcharts, custom icons, or non-AWS diagrams -> load [references/non-aws-providers.md](references/non-aws-providers.md) for K8s, on-prem, flowchart, and custom icon examples

	db_primary - [RDS("userdb ro")]
	db_replica = RDS("userdb ro")
	db_primary - db_replica

		from urllib.request import urlretrieve

		icon_path, _ = urlretrieve("https://example.com/icon.png", "icon.png")

-from urllib.request import urlretrieve
-rabbitmq_url = "https://jpadilla.github.io/rabbitmqapp/assets/img/icon.png"
-rabbitmq_icon, _ = urlretrieve(rabbitmq_url, "rabbitmq.png")
+# Use a local RabbitMQ icon file. Download an appropriate PNG (for example,
+# from the official RabbitMQ resources) and save it as "rabbitmq.png" in
+# the working directory before running this example.
+rabbitmq_icon = "rabbitmq.png"

Conversation

MichaelWalker-git commented Mar 7, 2026

Summary

What's included

Prerequisites

Context

Test plan

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Mar 7, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 7, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 7, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 7, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 7, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 7, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants