From a55809e675b719be66795d93ba0d7981dc7294de Mon Sep 17 00:00:00 2001 From: Adam Rubinstein Date: Wed, 12 Aug 2026 16:59:47 -0700 Subject: [PATCH] show-me: add topology view and color-encoding guidance MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add two view-selection guidelines to the skill: - A topology view for systems whose real shape is not a list — nested containment, parallel siblings, a shared layer everything draws on. A linear stack or tree implies a top-to-bottom order that often is not real; the topology draws the actual structure, in text, a Mermaid subgraph, or a focused HTML file. - A general rule that color should encode category (layer, module, owner, state) consistently across every view on the page. Mermaid is called out because it defaults to gray while the tree, diff, and HTML views carry color for free; a classDef snippet shows the fix. Co-Authored-By: Claude --- plugins/show-me/skills/show-me/SKILL.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/plugins/show-me/skills/show-me/SKILL.md b/plugins/show-me/skills/show-me/SKILL.md index 15b5601..8dcc74d 100644 --- a/plugins/show-me/skills/show-me/SKILL.md +++ b/plugins/show-me/skills/show-me/SKILL.md @@ -43,6 +43,16 @@ src/ └── transport/ # sends API requests ``` +- Show a system whose real shape is not a list — parts nested inside other parts, siblings that run in parallel, a shared layer everything draws on — as a topology, not a linear stack or tree. A stack implies a top-to-bottom order that often is not real; draw the actual containment, parallelism, and shared foundations instead. Sketch it in text, render it with a Mermaid `subgraph`, or — when filled regions and nested boxes carry the point — a focused HTML file (below): + +```text +platform + control-plane ── wraps ──┐ + seam ───────────────────┤ one contract + brain: [ provider A │ provider B ] ← parallel, not stacked + services ── shared foundation every layer draws on +``` + - Show component interaction, control flow, or data flow with Mermaid: ```mermaid @@ -120,6 +130,13 @@ function expandSkill(command: string): string { Bash(open path/to/show-me-{description}.html) ``` +- Use color to carry meaning, not decoration. When a view has categories — layers, modules, owners, states — give each its own hue and keep it consistent across every view on the page, so the same thing is the same color everywhere. Flat black-on-white reads as unfinished. Tree, diff, and HTML views pick up color for free; Mermaid defaults to gray, so color its nodes with `classDef` + `class` (and `style` for a `subgraph`) to match: + +``` +classDef svc fill:#6a4f8f,stroke:#513b6d,color:#fff; +class LogGw,ModelGw,ToolGw svc; +``` + - Place each visual next to the short text it supports. Keep only the calls, files, props, states, and boundaries needed to answer the user's current question. You may use one of these, you may use several, it is unlikely you will use all of them. Use your judgement and don't overwhelm the user.