WhoSolo developer about to publish a repo who needs an architecture picture and does not want to open Figma or fight Mermaid
The problemREADME diagrams either look like default Mermaid output or take an hour in a drawing app.
The outcomeOne self-contained HTML file with an architecture diagram (frontend, backend, database, cache) you can open by double-clicking and export as PNG or SVG.
Steps
Run: npx skills add cathrynlavery/diagram-design
Ask your agent in plain words, for example: Make me an architecture diagram of my app: frontend, backend, database, Redis cache.
Open the generated .html file in your browser and check the labels and arrows.
Ask the agent to export a PNG or SVG and add it to your README.
Prompt for your agent
Using the diagram-design skill, draw an architecture diagram of <my project: components and how they connect> as a single HTML and SVG file. Then export it as SVG so I can embed it in the README, and tell me which diagram type you picked and why.
Caveat. The skill works from your description, so any component you forget to mention will be missing from the diagram. Check it against your real code before publishing.
Ask for a flow or sequence diagram of a proposed change and approve the design first.
Intermediate
30 minutes
Claude Code
Codex
Cursor
Seen in the wild
Evidence (similar to what people reported): Reddit
WhoDeveloper about to hand a multi-step feature to a coding agent who wants to catch design mistakes early
The problemAgents start coding from a vague plan and the wrong design only shows up after many files change.
The outcomeA sequence or flow diagram of the planned change that you read, correct and approve before any code is written.
Steps
Install the skill with: npx skills add cathrynlavery/diagram-design
Describe the feature, for example: Give me a sequence of a bearer call with token refresh on 401.
Read the diagram and fix any wrong step by telling the agent what to change.
Once the diagram matches your intent, ask the agent to implement it.
Prompt for your agent
Before writing code for <feature>, use the diagram-design skill to draw the planned flow as one HTML diagram. Wait for my approval of the diagram, and flag any step where you made an assumption.
Caveat. The diagram only helps if you actually read it before the agent continues. Tell the agent explicitly to stop and wait for approval.
Diagram which tools your AI agent can call, where data moves and where a human must approve.
Intermediate
30 minutes
Any agent
Seen in the wild
Evidence (similar to what people reported): Reddit
WhoTeam lead documenting how an internal AI agent is wired before a security or ops review
The problemReviewers ask where data goes and who approves actions, and nobody has a single picture to point at.
The outcomeA diagram showing the agent, its tools, data flows and approval points that can be attached to a review document.
Steps
Install the skill with: npx skills add cathrynlavery/diagram-design
List your agent's tools, data sources and approval steps in a short prompt.
Ask for a diagram that shows data flows and where a human approves actions.
Walk the reviewers through the HTML file and correct anything they spot.
Prompt for your agent
Using diagram-design, draw our agent setup for <agent name>: the tools it can call, where data flows, and where a person must approve. Mark any boundary where data leaves our systems so I can double-check it.
Caveat. The diagram shows what you tell it, not what the agent actually does at runtime. Do not use it as proof of a security boundary without verifying the real config.
Have your agent read a codebase and draw its parts and connections so you can orient before editing.
Beginner
15 minutes
From the README
Claude Code
Codex
Cursor
WhoDeveloper joining a project or reviewing a pull request who needs a quick mental map of an unfamiliar repo
The problemReading folders and files one by one makes it hard to see how the pieces connect.
The outcomeA component and data-flow diagram of the repo that you can review with teammates before approving or writing code.
Steps
Install the skill with: npx skills add cathrynlavery/diagram-design
Point your agent at the repo and ask it to map the main components and how they talk to each other.
Open the HTML file and compare each box and arrow with the actual code paths.
Ask for corrections where the diagram is wrong, then keep the final version in the project docs.
Prompt for your agent
Use the diagram-design skill to map the components and connections in <repo path or URL> as one HTML and SVG diagram. List any connection you were unsure about so I can verify it against the code.
Caveat. The diagram reflects what the agent inferred from the code it read, so it can miss runtime wiring or hidden dependencies. Treat it as a first draft to verify.
Use the diagram skill alongside HyperFrames to turn a repo README into a short explainer video.
Advanced
1 hour
Claude Code
Seen in the wild
Evidence (similar to what people reported): X, Oct 2026
WhoMaintainer or creator who wants a quick explainer video for a GitHub project without editing footage
The problemExplaining how a repo works takes a written walkthrough most visitors never read.
The outcomeA short explainer video for a repo where the architecture scenes come from diagrams drawn by the skill.
Steps
Install the video tooling the way the field post describes: claude plugin marketplace add heygen-com/hyperframes
Run: claude plugin install hyperframes@hyperframes
Run: npx skills add cathrynlavery/diagram-design
Ask Claude Code to read the repo README, plan the scenes and draw the diagrams, then render the video.
Prompt for your agent
Make a 45-second explainer video for this GitHub repo: <repo URL>. Read the README, state in one sentence what it does, use diagram-design for the architecture scenes, and tell me which scenes you were least sure about.
Caveat. The video side depends on a separate project (HyperFrames) with its own requirements. The prompt shape comes from a community post, not this README, so expect to adjust it.
Give the skill your site URL once and every later diagram uses your palette and fonts.
Beginner
15 minutes
From the README
Any agent
WhoFounder or marketer who needs diagrams for decks, docs and blog posts that look like their own brand
The problemGeneric diagrams clash with a branded site or deck and need manual recoloring each time.
The outcomeA saved brand profile so each new diagram comes out in your palette and typography without extra prompting.
Steps
Install the skill with: npx skills add cathrynlavery/diagram-design
Ask your agent: Onboard diagram-design to https://yoursite.com
Let it pull your palette and fonts, then request a first diagram and compare it with your site.
Ask for tweaks to the style if a color or font is off, then keep using the same profile.
Prompt for your agent
Onboard diagram-design to <my website URL>, then draw a <diagram type> of <topic> in that brand. Tell me which colors and fonts you picked up so I can confirm they match.
Caveat. The skill sends your site URL over the network during onboarding, and the README points to PRIVACY.md for exactly what leaves your machine. Read it before onboarding a private or staging site.
Import an existing Mermaid, draw.io or Excalidraw file and get it back as a polished editorial diagram.
Intermediate
30 minutes
From the README
Claude Code
Codex
Cursor
WhoDocs maintainer with a folder of ugly Mermaid or draw.io diagrams in their README and wiki
The problemExisting diagrams use default theme styling that looks dated and inconsistent across pages.
The outcomeThe same diagrams redrawn in one consistent editorial style, exported as PNG or SVG for the docs.
Steps
Install the skill with: npx skills add cathrynlavery/diagram-design
Hand your agent the Mermaid, draw.io or Excalidraw source and ask it to redraw it with the skill.
Open the new HTML file and check that every node and edge from the original survived.
Export to PNG or SVG and replace the old image in your docs.
Prompt for your agent
Use the diagram-design skill to import <path to mermaid, drawio or excalidraw file> and redraw it as a clean HTML and SVG diagram. Confirm that the node and edge counts match the original and export an SVG.
Caveat. Import is described in the README, but complex layouts may be re-arranged by the skill, so compare the result against the original instead of assuming it is identical.
Turn on optional motion so a process diagram reveals its steps one after another.
Intermediate
30 minutes
From the README
Any agent
WhoTechnical writer or educator presenting a process (request flow, pipeline) where order matters
The problemA static diagram shows all steps at once, which makes sequences harder to follow in a talk or doc.
The outcomeAn HTML diagram with optional motion that walks a viewer through the steps in order, with a static version still available.
Steps
Install the skill with: npx skills add cathrynlavery/diagram-design
Ask your agent to draw an ordered process and request optional motion for it.
Open the HTML file in a browser and check that the steps appear in the intended order.
Keep the static version as the default for places where motion is not wanted.
Prompt for your agent
Use diagram-design to draw <process name> as an ordered diagram with the optional motion enabled. Confirm the step order is right and keep a static version alongside it.
Caveat. The README says static HTML is the default and motion is optional for ordered explanations only, so it will not suit every diagram type.
Who it is forDevelopers and non-designers who already work inside an AI coding agent and want presentable diagrams without opening a drawing app or settling for default Mermaid output.
DEDUPED