docs(skills): make descriptions self-contained, not cross-dependent

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.
This commit is contained in:
Teknium 2026-04-16 20:37:28 -07:00 committed by Teknium
parent 7d535969ff
commit fdefd98aa3
2 changed files with 32 additions and 30 deletions

View file

@ -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).