Skip to content
Back to search

architecture-diagram-skill

SkillGitHubIncomplete

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/konraddzbik--architecture-diagram-skill/badge.svg)](/listings/konraddzbik--architecture-diagram-skill)

HTML

<a href="/listings/konraddzbik--architecture-diagram-skill"><img src="/api/listings/konraddzbik--architecture-diagram-skill/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Claude Code — Plugin Marketplace (recommended)

/plugin marketplace add konraddzbik/architecture-diagram-skill
/plugin install architecture-diagram

That's it. The skill activates automatically whenever you ask for an architecture diagram, system flow, RAG pipeline, etc.

Claude Code — manual clone

The skill lives in `skills/architecture-diagram/` inside this repo, so clone to a temp dir and copy that subfolder into place (Claude Code discovers `SKILL.md` exactly one level under `skills/` — cloning the whole repo would nest it too deep).

Personal install (available in all your projects):

git clone https://github.com/konraddzbik/architecture-diagram-skill /tmp/arch-skill
cp -r /tmp/arch-skill/skills/architecture-diagram ~/.claude/skills/architecture-diagram

Project install (committed to a repo, shared with your team):

git clone https://github.com/konraddzbik/architecture-diagram-skill /tmp/arch-skill
cp -r /tmp/arch-skill/skills/architecture-diagram .claude/skills/architecture-diagram

Gemini CLI (recommended: one command)

gemini skills install https://github.com/konraddzbik/architecture-diagram-skill

This installs to `~/.gemini/skills/` (user-level, all projects). To install for just the current project:

gemini skills install https://github.com/konraddzbik/architecture-diagram-skill --scope workspace

Verify it loaded:

gemini skills list

If you're already in a session, reload without restarting:

/skills reload

Manual install (Gemini CLI)

Personal install — available in all your projects:

git clone https://github.com/konraddzbik/architecture-diagram-skill /tmp/arch-skill
cp -r /tmp/arch-skill/skills/architecture-diagram ~/.gemini/skills/architecture-diagram

Project install — committed to a repo, shared with your team:

git clone https://github.com/konraddzbik/architecture-diagram-skill /tmp/arch-skill
cp -r /tmp/arch-skill/skills/architecture-diagram .gemini/skills/architecture-diagram

Or use the cross-tool `.agents/skills/` path (works in Gemini CLI, OpenCode, and other compatible tools):

git clone https://github.com/konraddzbik/architecture-diagram-skill /tmp/arch-skill
cp -r /tmp/arch-skill/skills/architecture-diagram .agents/skills/architecture-diagram

GitHub Copilot CLI

Requires [GitHub CLI](https://cli.github.com/) ≥ 2.90.0:

gh skill install konraddzbik/architecture-diagram-skill architecture-diagram

The skill is installed to `.github/skills/` in your current project by default. To install it globally for all projects:

gh skill install konraddzbik/architecture-diagram-skill architecture-diagram --scope user

If you're already in a `copilot` session, reload without restarting:

/skills reload

Manual install (Copilot CLI)

Personal install — available in all your projects:

git clone https://github.com/konraddzbik/architecture-diagram-skill /tmp/arch-skill
cp -r /tmp/arch-skill/skills/architecture-diagram ~/.copilot/skills/architecture-diagram

Project install — committed to a repo, shared with your team:

git clone https://github.com/konraddzbik/architecture-diagram-skill /tmp/arch-skill
cp -r /tmp/arch-skill/skills/architecture-diagram .github/skills/architecture-diagram

OpenCode

Project install — committed to a repo, shared with your team:

git clone https://github.com/konraddzbik/architecture-diagram-skill /tmp/arch-skill
cp -r /tmp/arch-skill/skills/architecture-diagram .opencode/skills/architecture-diagram

Personal install — available in all your projects:

git clone https://github.com/konraddzbik/architecture-diagram-skill /tmp/arch-skill
cp -r /tmp/arch-skill/skills/architecture-diagram ~/.config/opencode/skills/architecture-diagram

Or use the Claude-compatible path (OpenCode reads `.claude/skills/` too):

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 14 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "name": "architecture-diagram-skill",
  3. "owner": {
  4. "name": "Konrad Dzbik",
  5. "url": "https://github.com/konraddzbik"
  6. },
  7. "plugins": [
  8. {
  9. "name": "architecture-diagram",
  10. "source": "./",
  11. "description": "Interactive, click-through architecture diagrams — single HTML file with animated flows, mode toggles, dark/light theme, and a side panel with payload details."
  12. }
  13. ]
  14. }
README.md · README · 351 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <p align="center">
  2. <img src="banner.svg" alt="Interactive Architecture Diagrams – animated nodes with flowing data packets" width="800" />
  3. </p>
  4. <h1 align="center">Interactive Architecture Diagrams</h1>
  5. <p align="center">
  6. <a href="https://www.mintlify.com/blog/skill-md"><b>Agent Skill</b></a> for Claude Code · Gemini CLI · GitHub Copilot CLI · OpenCode · Cursor<br/>
  7. Build click-through, animated system architecture diagrams as a single HTML file.<br/>
  8. No build step. No dependencies. One file you can email, host, or open locally.
  9. </p>
  10. <p align="center">
  11. <a href="#install"><b>Install</b></a> ·
  12. <a href="#try-it"><b>Try It</b></a> ·
  13. <a href="#example-prompts"><b>Examples</b></a> ·
  14. <a href="skills/architecture-diagram/SKILL.md"><b>Skill Spec</b></a>
  15. </p>
  16. > Build click-through, animated system architecture diagrams as a single HTML file. Drop it into a workshop, design review, or onboarding doc and let people **watch the data flow** instead of reading static boxes-and-arrows.
  17. This is an [Agent Skill](https://www.mintlify.com/blog/skill-md) — a folder of instructions any compatible AI coding agent loads on demand. When you ask for an architecture diagram, this skill takes over and produces a self-contained `architecture.html` plus a companion `architecture.md` description. Works with Claude Code, Gemini CLI, GitHub Copilot CLI, OpenCode, Cursor, and any tool supporting the SKILL.md standard.
  18. ---
  19. ## What you get
  20. Each generated diagram includes:
  21. - **Named flows** — pick a scenario tab (`RAG Query`, `Login`, `Ingest`, …) and watch it play out step by step
  22. - **Animated data packets** glowing along quadratic-curve wires between services
  23. - **Side panel** showing the current step's payload, description, and metadata chips (latency, auth headers, ports)
  24. - **Mode toggles** — switch between `offline/online`, `dev/prod`, `v1/v2` (any keys; colors follow button order) to swap node labels, ports, and payloads in place
  25. - **Drag-and-drop nodes** — reposition any tile by dragging (or Shift+Arrows on a focused node); snaps to grid, wires redraw live, moved nodes saved to localStorage
  26. - **Player controls** — play/pause/step, keyboard shortcuts, visual progress bar, screen-reader announcements
  27. - **Dark/light theme toggle** — follows your OS preference, switch with one click or press `T` (saved in localStorage)
  28. - **Fullscreen mode** — press `F` to expand the canvas for presentations with the controls, flow tabs and step panel still at hand (below ~1140px wide the panel gives way to a one-line step summary); `Escape` to exit
  29. - **Self-linting** — the page warns in the console about unknown node ids, flows without tabs, and leftover placeholders; `references/screenshot.js` prints the same list and exits non-zero on JavaScript errors (`1`) or lint warnings (`2`)
  30. No build step. No dependencies. One HTML file you can email, host, or open locally.
  31. Battle-tested on a public RAG workshop (Eskadra Bielik) and several internal design reviews.
  32. ---
  33. ## When to use this skill
  34. | Situation | Use this? |
  35. |---|---|
  36. | "Show me how the auth flow works" (interactive, for a workshop) | **Yes** |
  37. | "Design the RAG pipeline before we build it" (planning a new service) | **Yes** |
  38. | "Build an architecture mockup we can iterate on with the team" | **Yes** |
  39. | "Visualize our microservices and how they communicate" | **Yes** |
  40. | "Map out the CI/CD pipeline for onboarding docs" | **Yes** |
  41. | "Show the data flow through our ETL pipeline" | **Yes** |
  42. | "Draw a sequence diagram for this PR" (static, lives in markdown) | No — a Mermaid sequence diagram inline is simpler |
  43. | "I just need a static boxes-and-arrows topology" (no flows/steps) | No — a Mermaid flowchart is enough |
  44. The differentiator is **interactivity + sequenced data flow**. If the value is "click through it and watch what happens," this skill applies.
  45. ### Use cases
  46. - **System architecture** — map services, databases, queues, and external APIs; watch requests flow between them step by step
  47. - **Data pipelines & ETL** — show how data moves from ingestion through transformation to storage, with payload previews at each stage
  48. - **Agentic / RAG flows** — visualize LLM chains, tool calls, retrieval-augmented generation, and multi-agent orchestration
  49. - **Microservices communication** — trace requests through API gateways, service mesh, event buses, and worker queues
  50. - **CI/CD pipelines** — walk through build, test, deploy, and rollback stages with environment toggles (staging/prod)
  51. - **Auth & security flows** — OAuth2, SAML, mTLS handshakes, token refresh cycles with the full redirect dance
  52. - **Onboarding diagrams** — give new team members a clickable walkthrough of "how does X actually work here"
  53. - **Design reviews** — present a proposed architecture before building it; iterate on the diagram with stakeholders
  54. - **Workshop materials** — let attendees click through a system at their own pace instead of watching static slides
  55. ---
  56. ## Install
  57. ### Claude Code — Plugin Marketplace (recommended)
  58. ```bash
  59. /plugin marketplace add konraddzbik/architecture-diagram-skill
  60. /plugin install architecture-diagram
  61. ```
  62. That's it. The skill activates automatically whenever you ask for an architecture diagram, system flow, RAG pipeline, etc.
  63. ### Claude Code — manual clone
  64. The skill lives in `skills/architecture-diagram/` inside this repo, so clone to a temp
  65. dir and copy that subfolder into place (Claude Code discovers `SKILL.md` exactly one
  66. level under `skills/` — cloning the whole repo would nest it too deep).
  67. Personal install (available in all your projects):
  68. ```bash
  69. git clone https://github.com/konraddzbik/architecture-diagram-skill /tmp/arch-skill
  70. cp -r /tmp/arch-skill/skills/architecture-diagram ~/.claude/skills/architecture-diagram
  71. ```
  72. Project install (committed to a repo, shared with your team):
  73. ```bash
  74. git clone https://github.com/konraddzbik/architecture-diagram-skill /tmp/arch-skill
  75. cp -r /tmp/arch-skill/skills/architecture-diagram .claude/skills/architecture-diagram
  76. ```
  77. ### Gemini CLI (recommended: one command)
  78. ```bash
  79. gemini skills install https://github.com/konraddzbik/architecture-diagram-skill
  80. ```
  81. This installs to `~/.gemini/skills/` (user-level, all projects). To install for just the current project:
  82. ```bash
  83. gemini skills install https://github.com/konraddzbik/architecture-diagram-skill --scope workspace
  84. ```
  85. Verify it loaded:
  86. ```bash
  87. gemini skills list
  88. ```
  89. If you're already in a session, reload without restarting:
  90. ```
  91. /skills reload
  92. ```
  93. #### Manual install (Gemini CLI)
  94. Personal install — available in all your projects:
  95. ```bash
  96. git clone https://github.com/konraddzbik/architecture-diagram-skill /tmp/arch-skill
  97. cp -r /tmp/arch-skill/skills/architecture-diagram ~/.gemini/skills/architecture-diagram
  98. ```
  99. Project install — committed to a repo, shared with your team:
  100. ```bash
  101. git clone https://github.com/konraddzbik/architecture-diagram-skill /tmp/arch-skill
  102. cp -r /tmp/arch-skill/skills/architecture-diagram .gemini/skills/architecture-diagram
  103. ```
  104. Or use the cross-tool `.agents/skills/` path (works in Gemini CLI, OpenCode, and other compatible tools):
  105. ```bash
  106. git clone https://github.com/konraddzbik/architecture-diagram-skill /tmp/arch-skill
  107. cp -r /tmp/arch-skill/skills/architecture-diagram .agents/skills/architecture-diagram
  108. ```
  109. ### GitHub Copilot CLI
  110. Requires [GitHub CLI](https://cli.github.com/) ≥ 2.90.0:
  111. ```bash
  112. gh skill install konraddzbik/architecture-diagram-skill architecture-diagram
  113. ```
  114. The skill is installed to `.github/skills/` in your current project by default. To install it globally for all projects:
  115. ```bash
  116. gh skill install konraddzbik/architecture-diagram-skill architecture-diagram --scope user
  117. ```
  118. If you're already in a `copilot` session, reload without restarting:
  119. ```
  120. /skills reload
  121. ```
  122. #### Manual install (Copilot CLI)
  123. Personal install — available in all your projects:
  124. ```bash
  125. git clone https://github.com/konraddzbik/architecture-diagram-skill /tmp/arch-skill
  126. cp -r /tmp/arch-skill/skills/architecture-diagram ~/.copilot/skills/architecture-diagram
  127. ```
  128. Project install — committed to a repo, shared with your team:
  129. ```bash
  130. git clone https://github.com/konraddzbik/architecture-diagram-skill /tmp/arch-skill
  131. cp -r /tmp/arch-skill/skills/architecture-diagram .github/skills/architecture-diagram
  132. ```
  133. ### OpenCode
  134. Project install — committed to a repo, shared with your team:
  135. ```bash
  136. git clone https://github.com/konraddzbik/architecture-diagram-skill /tmp/arch-skill
  137. cp -r /tmp/arch-skill/skills/architecture-diagram .opencode/skills/architecture-diagram
  138. ```
  139. Personal install — available in all your projects:
  140. ```bash
  141. git clone https://github.com/konraddzbik/architecture-diagram-skill /tmp/arch-skill
  142. cp -r /tmp/arch-skill/skills/architecture-diagram ~/.config/opencode/skills/architecture-diagram
  143. ```
  144. Or use the Claude-compatible path (OpenCode reads `.claude/skills/` too):
  145. ```bash
  146. git clone https://github.com/konraddzbik/architecture-diagram-skill /tmp/arch-skill
  147. cp -r /tmp/arch-skill/skills/architecture-diagram ~/.claude/skills/architecture-diagram
  148. ```
  149. The skill activates automatically when you ask for an architecture diagram, system flow, RAG pipeline, etc.
  150. ### Claude.ai (web / desktop / mobile)
  151. 1. Build a ZIP with the skill folder at its root (`SKILL.md` must sit directly inside `architecture-diagram/`, so GitHub's **Download ZIP** of the whole repo won't work):
  152. ```bash
  153. git clone https://github.com/konraddzbik/architecture-diagram-skill /tmp/arch-skill
  154. cd /tmp/arch-skill/skills && zip -r ~/architecture-diagram.zip architecture-diagram
  155. ```
  156. 2. In Claude, go to **Settings → Capabilities → Skills → Upload skill**
  157. 3. Upload `architecture-diagram.zip`
  158. 4. Toggle the skill **on** in your skills list
  159. ---
  160. ## Try it
  161. Once installed, just describe what you want. If you don't know where to start, just type:
  162. > Prepare an architecture view of this repository.
  163. Claude will generate an `architecture.html` and `architecture.md` in your working directory. Open the HTML in a browser to see the interactive diagram — or ask Claude to show the results right in the terminal.
  164. The skill triggers on phrases like *architecture diagram*, *system flow*, *RAG flow*, *agentic flow*, *service map*, or the Polish equivalents (*diagram architektury*, *klikany diagram*).
  165. ### Example prompts
  166. **OAuth2 login flow**
  167. > Build an interactive architecture diagram for an OAuth2 login flow with PKCE. Show the redirect dance between client, authorization server, and resource API step by step. Include a dev/prod mode toggle.
  168. **RAG pipeline design**
  169. > I'm designing a RAG pipeline with embedding retrieval, a reranker, and an LLM. Show me a click-through diagram I can use in a design review. Toggle between offline (Docker, local Qdrant) and online (Cloud Run, BigQuery) modes.
  170. **Event-driven microservices**
  171. > Visualize an event-driven order system: API gateway → Kafka → three consumers (inventory, billing, notifications). Toggle between synchronous (REST fallback) and asynchronous (Kafka) modes.
  172. **CI/CD pipeline**
  173. > Show our CI/CD pipeline: GitHub push → GitHub Actions → build → test → deploy to staging → approval gate → deploy to prod. Toggle between staging and production environments.
  174. **Data ingestion pipeline**
  175. > Visualize a data pipeline: webhook events → SQS → Lambda → transform → write to Postgres + push to Elasticsearch. Show the happy path and the dead-letter-queue retry flow.
  176. **Multi-agent system**
  177. > Draw an agentic AI system: user query → orchestrator agent → tool-calling agent (search, calculator, code exec) → synthesis agent → response. Show how context flows between agents.
  178. **Microservices with service mesh**
  179. > Map our microservices: mobile app → API gateway → user service, product service, order service. Each talks to its own DB. Show the checkout flow and the search flow with an Istio service mesh.
  180. If you upload an existing `SOLUTION.md`, OpenAPI spec, or README first, the skill will extract services, ports, and operations from it before asking clarifying questions — so the more architecture context you give it, the less it asks.
  181. ---
  182. ## What's inside
  183. ```
  184. architecture-diagram-skill/
  185. ├── .claude-plugin/
  186. │ ├── marketplace.json # Plugin marketplace manifest
  187. │ └── plugin.json # Plugin metadata
  188. ├── .github/workflows/ci.yml # Runs scripts/check.js and the headless UI tests on every push / PR
  189. ├── scripts/
  190. │ └── check.js # Dependency-free integrity checks (versions, examples, template)
  191. ├── tests/
  192. │ └── ui.test.js # Headless-Chrome UI regression tests (puppeteer-core, see tests/README.md)
  193. ├── evals/ # Behavioral evals for `claude plugin eval` (see evals/README.md)
  194. ├── skills/
  195. │ └── architecture-diagram/
  196. │ ├── SKILL.md # Instructions Claude reads when activated
  197. │ ├── assets/
  198. │ │ ├── template.html # The drop-in diagram template (CSS + JS + SVG)
  199. │ │ └── css-tokens.css # Standalone color/typography tokens for restyling
  200. │ ├── examples/
  201. │ │ ├── rag-eskadra-bielik.json # Real RAG system, 5 flows, offline/online modes
  202. │ │ ├── auth-oauth2.json # OAuth2 + session flow, dev/prod modes
  203. │ │ ├── event-driven.json # Kafka fan-out, v1 vs v2 migration modes
  204. │ │ ├── cicd-pipeline.json # GitHub Actions deploy, staging/prod modes
  205. │ │ └── agentic-tool-calling.json # Multi-agent AI with tool calls
  206. │ └── references/
  207. │ ├── flow-design-patterns.md # Layout heuristics, naming, sequencing
  208. │ ├── component-library.md # Copy-paste node snippets
  209. │ ├── validation.md # How to check a generated diagram (static check, screenshots, console)
  210. │ └── screenshot.js # Optional puppeteer-based layout spot-check (prints lint warnings)
  211. ├── CHANGELOG.md
  212. ├── README.md
  213. ├── LICENSE
  214. └── .gitignore
  215. ```
  216. The HTML template is the heart of the skill — Claude copies it and edits a handful of clearly marked regions (title/header, mode-toggle labels, flow tabs, the `.node` divs, and the `flows` object in JS; the template's top `EDIT THESE THINGS` comment is the authoritative list). Everything else (player, side panel, animations, wire renderer) just works.
  217. ---
  218. ## Demo
  219. Template content:
  220. <img width="1585" height="958" alt="image" src="https://github.com/user-attachments/assets/0677c5b3-8eff-4d79-acef-2a67a757e8a7" />
  221. Dark theme:
  222. <img width="1585" height="958" alt="image" src="https://github.com/user-attachments/assets/4798bfff-89ac-4436-9c11-8a28aa086525" />
  223. ---
  224. ## Customizing
  225. - **Light or dark theme:** every diagram ships with a built-in toggle (moon/sun icon, or press `T`). The preference is saved in localStorage. To make light the default, ask Claude to add `class="light"` to the `<body>` tag.
  226. - **Rearrange nodes:** drag any node (mouse/pen) or focus it and press Shift+Arrows. Positions snap to a 48px lattice; the nodes you moved are saved to localStorage (keyed per diagram), the rest follow the file. Press `R` to reset to original positions. On touch screens nodes are tap-to-jump so the page keeps scrolling.
  227. - **Fullscreen presentations:** press `F` to expand the canvas full-screen; the mode toggle, flow tabs and the step panel stay on screen (on screens narrower than ~1140px the panel is hidden and a one-line step summary takes its place). Press `Escape` to exit.
  228. - **Keyboard shortcuts off:** click "shortcuts on" under the flow tabs to disable the single-key shortcuts (remembered per browser).
  229. - **Restyle to your brand:** point Claude at `assets/css-tokens.css` and ask it to swap the palette. The tokens are standalone — splice them into the template and you're done.
  230. - **Node roles:** seven color-coded roles are built in — `user`, `orch` (API / Service), `compute`, `embed`, `vector`, `seed` and `ext` (External: Stripe, Twilio, SaaS, hosted IdPs). Roles are color groups; the legend labels say what each color means in your diagram. An eighth role needs a `--c-<role>` variable in both the dark `:root` and `body.light` blocks, a `.node[data-role="<role>"]` rule, an arrowhead (`ahMap` entry + `<marker>`) and a legend item — rarely worth it, since more colors make the legend hard to read.
  231. - **Different output language:** the skill works in English and Polish. Ask in your preferred language and the labels, descriptions, and companion markdown will match.
  232. ---
  233. ## Known limits
  234. - The diagram is a **single HTML file** — no live data, no real backend. It's a didactic tool, not a monitoring dashboard.
  235. - Designed for **≤ 12 nodes per diagram**. Beyond that, wire crossings get hard to avoid even with careful layout.
  236. - The skill produces **two artifacts** by default (`.html` and `.md`). If you only want the HTML, say so explicitly.
  237. - **Works offline.** The only network call is to Google Fonts, loaded non-blocking with a system-font fallback — the diagram renders and is fully interactive with no connection. Delete the three font `<link>` tags at the top of the file for a 100% self-contained, air-gapped artifact.
  238. - **Locked down by default.** A Content Security Policy in the file allows only its own inline code and Google Fonts; step descriptions are sanitized to inline formatting. If you hand-edit in an external image or script, extend the CSP `<meta>` first.
  239. ---
  240. ## Contributing
  241. Found a bug, a layout pattern that doesn't work, or have an example system you'd like added? PRs welcome — especially new entries in `examples/` showing real-world topologies.
  242. When proposing changes to `SKILL.md` itself, please test that the description still triggers on the original phrases (`architecture diagram`, `RAG flow`, etc.) and doesn't over-trigger on static-diagram requests.
  243. ---
  244. ## License
  245. MIT — see [LICENSE](./LICENSE).
  246. ---
  247. ## Credits
  248. Built by [@konraddzbik](https://github.com/konraddzbik). Inspired by the design constraints of running real workshops where attendees need to *see* a system, not just read about it.
  249. If you publish a diagram built with this skill, a link back is appreciated but not required.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.