From 7d535969ff5ae041766b1dd5ce414f07326ee4cc Mon Sep 17 00:00:00 2001 From: Teknium Date: Thu, 16 Apr 2026 20:30:53 -0700 Subject: [PATCH] docs(skills): make architecture-diagram vs concept-diagrams routing explicit Both skills generate SVG system diagrams, but for very different subjects and aesthetics. The old descriptions didn't make the split clear, so an agent loading either one couldn't confidently pick. Changes: - Rewrote both frontmatter descriptions to state the scope up front plus an explicit 'for X, use the other skill instead' pointer. - Added a symmetric 'When to use this skill vs ' decision table to the top of each SKILL.md body, so the guidance is visible whether the agent is reading frontmatter or full content. - Added architecture-diagram <-> concept-diagrams to each other's related_skills metadata. Rule of thumb baked into both skills: software/cloud infra -> architecture-diagram physical / scientific / educational -> concept-diagrams --- .../creative/concept-diagrams/SKILL.md | 21 ++++++++++++++----- skills/creative/architecture-diagram/SKILL.md | 17 +++++++++++++-- 2 files changed, 31 insertions(+), 7 deletions(-) diff --git a/optional-skills/creative/concept-diagrams/SKILL.md b/optional-skills/creative/concept-diagrams/SKILL.md index 19b262853..d4e873e16 100644 --- a/optional-skills/creative/concept-diagrams/SKILL.md +++ b/optional-skills/creative/concept-diagrams/SKILL.md @@ -1,6 +1,6 @@ --- name: concept-diagrams -description: Generate flat, minimal SVG diagrams for explaining concepts visually — physics, chemistry, math, engineering, systems, data flows, physical objects, and anatomy. Light/dark-mode aware, self-contained HTML output, and a consistent educational visual language (inspired by clod-style diagrams). Use when the user asks to illustrate a concept, mechanism, structure, or process — physical or abstract — and wants a clean, textbook-ready visual. For strict software/infra architecture, prefer the `architecture-diagram` skill instead. +description: Generate flat, minimal light/dark-aware SVG diagrams for educational and non-software visuals — physics setups, chemistry mechanisms, math curves, physical objects (aircraft, turbines, smartphones, mechanical watches), anatomy, floor plans, cross-sections, narrative journeys (lifecycle of X, process of Y), hub-spoke integrations (smart city, IoT), and exploded layer views. Uses 9 semantic color ramps with automatic light/dark mode and sentence-case typography. Single self-contained HTML file. Use this when the goal is explaining a concept, mechanism, or physical structure to a reader — textbook-style visuals for any domain outside software infrastructure. For software system architecture specifically (frontend/backend/database/cloud services, microservice topology, deployment diagrams), use the `architecture-diagram` skill instead — it has a darker palette and component-type color semantics tuned for software stacks. version: 0.1.0 author: v1k22 (original PR), ported into hermes-agent license: MIT @@ -15,17 +15,28 @@ metadata: Generate production-quality SVG diagrams with a unified flat, minimal design system. Output is a single self-contained HTML file that renders identically in any modern browser, with automatic light/dark mode. -Use this skill when the user asks to explain or illustrate: +**When to use this skill vs `architecture-diagram`:** + +| Use `concept-diagrams` for | Use `architecture-diagram` for | +|----------------------------|--------------------------------| +| Physics, chemistry, math, biology | Software system architecture | +| Physical objects (aircraft, turbines, watches, phones) | Cloud infrastructure (VPC, regions, services) | +| Anatomy, cross-sections, exploded views | Microservice / service mesh topology | +| Floor plans, narrative journeys, lifecycles | Database + API layer diagrams | +| Educational / textbook-style visuals | Security groups, message buses | +| Flat, light/dark-adaptive aesthetic | Dark-themed tech/infra aesthetic | + +If in doubt: is the subject software/cloud infra? Use `architecture-diagram`. Anything else — physical, scientific, educational — this skill. + +Subjects this skill handles well: - physical objects (aircraft, turbines, watches, smartphones, cells) - scientific mechanisms (reactions, physics setups, electrical circuits) - processes and flows (ETL, CI/CD, workflows, narrative journeys) -- system topologies (microservices, IoT hub-spoke, grids) +- general system topologies when a textbook/educational style is preferred (smart city hub-spoke, grids) - floor plans, exploded views, cross-sections - quantitative charts (grouped bars, energy profiles) -For a dark-themed, Cocoon-style software architecture diagram (frontend/backend/DB/cloud/security), prefer the `architecture-diagram` skill. - ## Workflow 1. Decide on the diagram type (see Diagram Types below). diff --git a/skills/creative/architecture-diagram/SKILL.md b/skills/creative/architecture-diagram/SKILL.md index aa95b76ea..581c34913 100644 --- a/skills/creative/architecture-diagram/SKILL.md +++ b/skills/creative/architecture-diagram/SKILL.md @@ -1,6 +1,6 @@ --- name: architecture-diagram -description: Generate professional dark-themed system architecture diagrams as standalone HTML/SVG files. Self-contained output with no external dependencies. Based on Cocoon AI's architecture-diagram-generator (MIT). +description: Generate professional dark-themed SVG diagrams of software systems and cloud infrastructure — frontend, backend, database, cloud services, security groups, message buses, regions. Semantic color categories map component types to colors (cyan=frontend, emerald=backend, violet=database, amber=AWS/cloud, rose=security, orange=message bus). Single self-contained HTML file with JetBrains Mono font and grid background. Use this for software architecture, infrastructure topology, service maps, deployment diagrams, and anything that would fit in a cloud-provider architecture deck. For educational or non-software visuals (physics, chemistry, math, physical objects like aircraft/turbines, anatomy, floor plans, narrative journeys), use the `concept-diagrams` skill instead. Based on Cocoon AI's architecture-diagram-generator (MIT). version: 1.0.0 author: Cocoon AI (hello@cocoon-ai.com), ported by Hermes Agent license: MIT @@ -8,13 +8,26 @@ dependencies: [] metadata: hermes: tags: [architecture, diagrams, SVG, HTML, visualization, infrastructure, cloud] - related_skills: [excalidraw] + related_skills: [concept-diagrams, excalidraw] --- # Architecture Diagram Skill Generate professional, dark-themed technical architecture diagrams as standalone HTML files with inline SVG graphics. No external tools, no API keys, no rendering libraries — just write the HTML file and open it in a browser. +**When to use this skill vs `concept-diagrams`:** + +| Use `architecture-diagram` for | Use `concept-diagrams` for | +|--------------------------------|----------------------------| +| Software system architecture | Physics, chemistry, math, biology | +| Cloud infrastructure (VPC, regions, services) | Physical objects (aircraft, turbines, watches, phones) | +| Microservice / service mesh topology | Anatomy, cross-sections, exploded views | +| Database + API layer diagrams | Floor plans, narrative journeys, lifecycles | +| Security groups, message buses | Educational / textbook-style visuals | +| Dark-themed tech/infra aesthetic | Flat, light/dark-adaptive aesthetic | + +If in doubt: is the subject software/cloud infra? Use this skill. Anything else — physical, scientific, educational — reach for `concept-diagrams`. + Based on [Cocoon AI's architecture-diagram-generator](https://github.com/Cocoon-AI/architecture-diagram-generator) (MIT). ## Workflow