From fdefd98aa3d22c6b1c8a6cde53614b1c90462912 Mon Sep 17 00:00:00 2001 From: Teknium Date: Thu, 16 Apr 2026 20:37:28 -0700 Subject: [PATCH] docs(skills): make descriptions self-contained, not cross-dependent MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Previous pass assumed both skills would always be loaded together, so each description pointed at the other ('use concept-diagrams instead'). That breaks when only one skill is active — the agent reads 'use the other skill' and there is no other skill. Now each skill's description and scope section is fully self-contained: - States what it's best suited for - Lists subjects where a more specialized skill (if available) would be a better fit, naming them only as 'consider X if available' - Explicitly offers itself as a general SVG diagram fallback when no more specialized skill exists An agent loading either skill alone gets unambiguous guidance; an agent with both loaded still gets useful routing via the 'consider X if available' hints and the related_skills metadata. --- .../creative/concept-diagrams/SKILL.md | 35 +++++++++---------- skills/creative/architecture-diagram/SKILL.md | 27 ++++++++------ 2 files changed, 32 insertions(+), 30 deletions(-) diff --git a/optional-skills/creative/concept-diagrams/SKILL.md b/optional-skills/creative/concept-diagrams/SKILL.md index d4e873e16..03497c0c2 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 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. +description: Generate flat, minimal light/dark-aware SVG diagrams as standalone HTML files, using a unified educational visual language with 9 semantic color ramps, sentence-case typography, and automatic dark mode. Best suited 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 system integrations (smart city, IoT), and exploded layer views. If a more specialized skill exists for the subject (dedicated software/cloud architecture, hand-drawn sketches, animated explainers, etc.), prefer that — otherwise this skill can also serve as a general-purpose SVG diagram fallback with a clean educational look. Ships with 15 example diagrams. version: 0.1.0 author: v1k22 (original PR), ported into hermes-agent license: MIT @@ -15,27 +15,24 @@ 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. -**When to use this skill vs `architecture-diagram`:** +## Scope -| 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 | +**Best suited for:** +- Physics setups, chemistry mechanisms, math curves, biology +- Physical objects (aircraft, turbines, smartphones, mechanical watches, cells) +- Anatomy, cross-sections, exploded layer views +- Floor plans, architectural conversions +- Narrative journeys (lifecycle of X, process of Y) +- Hub-spoke system integrations (smart city, IoT networks, electricity grids) +- Educational / textbook-style visuals in any domain +- Quantitative charts (grouped bars, energy profiles) -If in doubt: is the subject software/cloud infra? Use `architecture-diagram`. Anything else — physical, scientific, educational — this skill. +**Look elsewhere first for:** +- Dedicated software / cloud infrastructure architecture with a dark tech aesthetic (consider `architecture-diagram` if available) +- Hand-drawn whiteboard sketches (consider `excalidraw` if available) +- Animated explainers or video output (consider an animation 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) -- 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) +If a more specialized skill is available for the subject, prefer that. If none fits, this skill can serve as a general-purpose SVG diagram fallback — the output will carry the clean educational aesthetic described below, which is a reasonable default for almost any subject. ## Workflow diff --git a/skills/creative/architecture-diagram/SKILL.md b/skills/creative/architecture-diagram/SKILL.md index 581c34913..1e1749db8 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 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). +description: Generate dark-themed SVG diagrams of software systems and cloud infrastructure as standalone HTML files with inline SVG graphics. Semantic component colors (cyan=frontend, emerald=backend, violet=database, amber=cloud/AWS, rose=security, orange=message bus), JetBrains Mono font, grid background. Best suited for software architecture, cloud/VPC topology, microservice maps, service-mesh diagrams, database + API layer diagrams, security groups, message buses — anything that fits a tech-infra deck with a dark aesthetic. If a more specialized diagramming skill exists for the subject (scientific, educational, hand-drawn, animated, etc.), prefer that — otherwise this skill can also serve as a general-purpose SVG diagram fallback. 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 @@ -15,18 +15,23 @@ metadata: 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`:** +## Scope -| 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 | +**Best suited for:** +- Software system architecture (frontend / backend / database layers) +- Cloud infrastructure (VPC, regions, subnets, managed services) +- Microservice / service-mesh topology +- Database + API map, deployment diagrams +- Anything with a tech-infra subject that fits a dark, grid-backed aesthetic -If in doubt: is the subject software/cloud infra? Use this skill. Anything else — physical, scientific, educational — reach for `concept-diagrams`. +**Look elsewhere first for:** +- Physics, chemistry, math, biology, or other scientific subjects +- Physical objects (vehicles, hardware, anatomy, cross-sections) +- Floor plans, narrative journeys, educational / textbook-style visuals +- Hand-drawn whiteboard sketches (consider `excalidraw`) +- Animated explainers (consider an animation skill) + +If a more specialized skill is available for the subject, prefer that. If none fits, this skill can also serve as a general SVG diagram fallback — the output will just carry the dark tech aesthetic described below. Based on [Cocoon AI's architecture-diagram-generator](https://github.com/Cocoon-AI/architecture-diagram-generator) (MIT).