Agent skill that generates beautiful, self-contained HTML pages for visualizing C# / .NET architecture, library internals, dependency graphs, namespace hierarchies, and project structure. Use this skill when asked to create visual HTML diagrams, architecture reports, diff reviews, NuGet dependency audits, or when complex .NET information needs to be presented as styled interactive HTML pages.
Generate self-contained HTML files for technical diagrams, visualizations, and data tables — optimized for C# applications, .NET libraries, and the broader .NET ecosystem. Always open the result in the browser. Never fall back to ASCII art when this skill is loaded.
Proactive table rendering. When you're about to present tabular data as an ASCII box-drawing table in the terminal (comparisons, audits, feature matrices, status reports, any structured rows/columns), generate an HTML page instead. The threshold: if the table has 4+ rows or 3+ columns, it belongs in the browser. Don't wait for the user to ask — render it as HTML automatically and tell them the file path. You can still include a brief text summary in the chat, but the table itself should be the HTML page.
This skill is optimized for visualizing C# and .NET codebases. When analyzing or diagramming .NET projects, apply this domain knowledge:
| Pattern | What to diagram | Approach |
|---|---|---|
| Clean Architecture / Onion | Concentric layers (Domain → Application → Infrastructure → Presentation) | CSS Grid cards with colored rings or nested borders |
| CQRS + MediatR | Command/Query separation, handler pipeline, behaviors | Mermaid flowchart with parallel branches |
| Repository + Unit of Work | DbContext, repositories, service layer | Mermaid class diagram or ER diagram |
| Middleware pipeline | ASP.NET Core request pipeline, middleware chain | Horizontal CSS pipeline (step boxes + arrows) |
| Dependency Injection | Service registration, lifetime scopes (Singleton/Scoped/Transient) | Data table with lifetime badges |
| Options pattern | IOptions<T>, configuration binding, validation | Data table mapping config sections to classes |
| Background services | IHostedService, BackgroundService, channels, queues | Mermaid sequence diagram or flowchart |
| Minimal APIs / Controllers | Route mapping, endpoint groups, filters | Data table or flowchart |
| Vertical Slice Architecture | Feature folders, each slice self-contained (handler + model + validator) | Mermaid flowchart showing request → slice → response |
| API Versioning | URL/header/query-string versioned endpoints | Data table: version → endpoints → deprecation status |
| Health checks | /health, /ready, dependency checks | Data table with check name, status badge, dependency |
| Rate limiting | ASP.NET Core rate limiting middleware, policies | Mermaid flowchart or data table with policy definitions |
Project dependency graph. Visualize .csproj → .csproj references and NuGet package dependencies. Use Mermaid graph TD with subgraph blocks for solution folders. Color-code: project references in one accent, NuGet packages in another, test projects dimmed.
Namespace hierarchy. Show the namespace tree of an assembly. Use Mermaid mindmap rooted at the assembly name, branching into top-level namespaces and their children. Leaf nodes can show class counts.
Class/interface relationships. Inheritance chains, interface implementations, decorator stacks. Use Mermaid classDiagram for simple cases. For complex hierarchies with many members, use CSS Grid cards grouped by namespace with interface badges.
Entity Framework model. DbContext, entity classes, relationships (1:1, 1:N, N:N), owned types, value objects. Use Mermaid erDiagram with navigation properties as relationship labels.
NuGet dependency audit. Package name, installed version, latest version, vulnerability status. Use the data table template with status badges (✓ up-to-date, ⚠ outdated, ✗ vulnerable).
ASP.NET middleware pipeline. Ordered chain of middleware components from request entry to response exit. Use the CSS horizontal pipeline pattern with step boxes. Color-code by concern: auth (purple), logging (blue), error handling (red), business logic (green).
Configuration binding map. Show which appsettings.json sections bind to which IOptions<T> classes and where they're registered. Use a two-column data table: JSON path → C# type.
Request lifecycle. Full HTTP request flow from Kestrel to response. Use Mermaid sequenceDiagram with participants: Client, Kestrel, Middleware, Router, Auth, Handler, Database. Show the happy path and one error path. Color-code middleware participants by concern.
Endpoint route table. All registered endpoints with HTTP method, path, handler reference, auth policy, and rate-limiting policy. Use the data table template with HTTP method badges (colored: GET=green, POST=accent, PUT=orange, DELETE=red). Group by controller/feature area.
Middleware pipeline. Ordered chain from UseExceptionHandler() to MapControllers(). Use the CSS horizontal pipeline pattern. Each step shows: order position, extension method name (e.g., UseAuthentication()), and the concern category. Critical ordering constraints (auth before authz, CORS before routing) should be called out with callout boxes.
DI service registration map. Which services are registered with which lifetime (Singleton/Scoped/Transient) and their implementation type. Use a data table with lifetime badges color-coded: Singleton=domain-1, Scoped=domain-2, Transient=domain-3.
Configuration binding map. Which appsettings.json sections bind to which IOptions<T> / IOptionsSnapshot<T> / IOptionsMonitor<T> classes. Use a two-column data table: JSON path → C# type, with a third column for environment variable overrides (ASPNETCORE_*, custom env vars).
Health check dashboard. Health check name, status (Healthy/Degraded/Unhealthy), dependencies checked, timeout. Use the data table template with status badges.
data-language="csharp" for code samples unless the code is explicitly another language (JSON, XML, YAML, SQL)..cs, .csproj, .sln, .props, .targets, appsettings.json, Program.cs, Startup.cs.IRepository<Order> not IRepository<T> when the concrete usage is known. In Monaco code samples, keep the generic form.+ public, - private, # protected, ~ internal as prefix markers on member lists.<code> tags styled with the accent color. Link to nuget.org when useful..csproj files with VS Code links pointing to the project file, not the directory.table sections, show HTTP methods as colored inline badges: GET (green), POST (accent), PUT (orange), DELETE (red).Program.cs. Incorrect ordering (e.g., auth after routing) is a critical visualization error.appsettings.json paths in <code> with colon separators (e.g., Logging:LogLevel:Default). Show environment variable overrides with double-underscore format (e.g., Logging__LogLevel__Default).Before generating any visualization, research the .NET APIs and patterns involved using the Microsoft Learn MCP tools. This ensures diagrams are accurate, use correct type names, and reflect current best practices.
When to research:
How to research (MCP tools):
microsoft_docs_search — Start here. Search for the .NET API, pattern, or concept. Returns up to 10 relevant content chunks with article titles and URLs. Use specific queries: "IHttpClientFactory dependency injection" beats "http client".
microsoft_code_sample_search — Search for official code examples. Pass language: "csharp" to filter results. Use when you need realistic usage patterns for Monaco Editor code samples in your diagrams.
microsoft_docs_fetch — Follow up on high-value pages found by search. Fetches the complete page as markdown. Use when search results are truncated or when you need full step-by-step procedures, configuration tables, or API reference details.
Research workflow:
Search MS Learn for the topic
→ Identify 1-2 authoritative pages
→ Fetch full content of the best page
→ Extract: correct type names, namespaces, patterns, configuration keys
→ Use these in your diagram nodes, code samples, and descriptions
What to extract for diagrams:
Microsoft.Extensions.DependencyInjection.IServiceCollection not a guess)"Logging:LogLevel:Default")Do NOT skip research and generate diagrams from memory alone. A beautiful diagram with wrong type names or outdated patterns is worse than an ugly accurate one.
Before writing HTML, commit to a direction. Don't default to "dark theme with blue accents" every time.
Who is looking? A developer understanding a system? A PM seeing the big picture? A team reviewing a proposal? This shapes information density and visual complexity.
What type of diagram? Architecture, flowchart, sequence, data flow, schema/ER, state machine, mind map, data table, timeline, or dashboard. Each has distinct layout needs and rendering approaches (see Diagram Types below).
Service or library? If the codebase is a service (has HTTP endpoints, middleware pipeline, Program.cs with WebApplication.CreateBuilder or Host.CreateBuilder), use the service-report flow. If it's a library (exposes a public API surface, is consumed as a NuGet package, has no host builder), use the library-report flow. Mixed projects (e.g., a library that also ships a host) — pick the dominant concern or generate both reports.
Visual is always default. Even essays, blog posts, and articles get visual treatment — extract structure into cards, diagrams, grids, tables.
Prose patterns (lead paragraphs, pull quotes, callout boxes) are accent elements within visual pages, not a separate mode. Use them to highlight key points or provide breathing room, but the page structure remains visual.
For prose accents, use callout and markdown section types. For everything else, use the standard template workflow with aesthetic directions below.
What aesthetic? Pick one and commit. The constrained aesthetics (Blueprint, Editorial, Paper/ink) are safer — they have specific requirements that prevent generic output. The flexible ones (IDE-inspired) require more discipline.
Constrained aesthetics (prefer these):
#faf7f5 background, terracotta/sage accents, informal feel)Flexible aesthetics (use with caution):
Explicitly forbidden:
Vary the choice each time. If the last diagram was dark and technical, make the next one light and editorial. The swap test: if you replaced your styling with a generic dark theme and nobody would notice the difference, you haven't designed anything.
Use the template. All diagrams are generated using the HTML template at ./assets/template.html. Your job is to produce a JSON data object — the template handles all CSS, JS, rendering, and interactivity.
Read the section types reference at ./references/section-types.md before composing your JSON. It documents every supported section type with its schema, examples, and composition guidelines.
How to generate:
./assets/template.html to the output location (e.g., diagrams/my-report.html)const DATA = {...}; line with your JSON payloadChoosing a palette: Set "palette" in the JSON to one of the 6 named palettes. See ./references/palette-registry.md for visual reference.
| Palette | Vibe | Use for |
|---|---|---|
| cool-slate | Technical, blue-gray | Architecture reports, system overviews |
| warm-terracotta | Earthy, editorial | Library walkthroughs, documentation |
| forest | Natural, green | Environment/infrastructure diagrams |
| ocean | Calm, teal | API reports, service documentation |
| dusk | Dramatic, purple | Feature specs, design proposals |
| sand | Desert minimalism | Configuration guides, data tables |
Choosing section types: Read ./references/section-types.md for the full catalog. Common patterns:
| Diagram need | Section types to use |
|---|---|
| Architecture overview | hero → callout → mermaid → card × N → file-inventory |
| Data flow / pipeline | hero → pipeline → mermaid → card × N |
| Type inventory | hero → kpi-row → table → file-inventory |
| Feature comparison | hero → table → callout |
| Service report | hero → mermaid (request flow) → table (endpoints) → pipeline (middleware) → file-inventory |
For slide deck presentations (when --slides flag is present or /generate-slides is invoked): the template system does not apply to slides — read ./assets/slide-deck.html and ./references/slide-patterns.md instead. (Note: the template also supports a lightweight ?slides query-string mode that presents sections as slides — see ./references/section-types.md for details.)
Navigation is automatic — the template generates a sidebar TOC from any section with a heading field. On narrow screens it collapses to a horizontal bar.
Choosing a rendering approach — all rendered via JSON section types:
| Diagram type | Section type | Why |
|---|---|---|
| Architecture (text-heavy) | hero + card + grid | Rich card content (descriptions, code, tool lists) |
| Architecture (topology-focused) | mermaid | Visible connections need automatic edge routing |
| Flowchart / pipeline | mermaid or pipeline | pipeline for simple linear flows, mermaid for branching |
| Sequence diagram | mermaid | Lifelines, messages, activation boxes |
| Data flow | mermaid with edge labels | Connections and data descriptions |
| ER / schema diagram | mermaid | Relationship lines between entities |
| State machine | mermaid | State transitions with labeled edges |
| Data table | table | Semantic markup, accessibility, copy-paste |
| KPI / metrics | kpi-row | Quick-glance numeric summary |
| File listings | file-inventory | Collapsible file lists with VS Code links |
Mermaid theming: Always use theme: 'base' with custom themeVariables so colors match your page palette. Use layout: 'elk' for complex graphs (requires the @mermaid-js/layout-elk package — see ./references/libraries.md for the CDN import). Override Mermaid's SVG classes with CSS for pixel-perfect control. See ./references/libraries.md for full theming guide.
Mermaid zoom controls: The template automatically adds zoom controls (+/−/reset/focus buttons), Ctrl/Cmd+scroll zoom, and a .mermaid-inner wrapper to every mermaid section. The focus button (⛶) opens a fullscreen overlay that auto-fits the SVG to maximum viewport size — essential for complex .NET dependency graphs and architecture diagrams. No manual setup needed.
Mermaid CSS class collision constraint: Never define .node as a page-level CSS class. Mermaid.js uses .node internally on SVG <g> elements with transform: translate(x, y) for positioning. Page-level .node styles (hover transforms, box-shadows) leak into diagrams and break layout. Use the namespaced .ve-card class for card components instead. The only safe way to style Mermaid's .node is scoped under .mermaid (e.g., .mermaid .node rect).
AI-generated illustrations (optional). If image generation tools are available (e.g., via MCP servers or built-in capabilities), optionally generate illustrations and embed as base64 data URIs in markdown section content.
When to use: Hero banners that establish the page's visual tone. Conceptual illustrations for abstract systems that Mermaid can't express (physical infrastructure, user journeys, mental models). Educational diagrams that benefit from artistic or photorealistic rendering. Decorative accents that reinforce the aesthetic.
When to skip: Anything Mermaid or CSS handles well. Generic decoration that doesn't convey meaning. Data-heavy pages where images would distract. Always degrade gracefully — if image generation isn't available, skip images without erroring. The page should stand on its own with CSS and typography alone.
Prompt craft: Match the image to the page's palette and aesthetic direction. Specify the style (3D render, technical illustration, watercolor, isometric, flat vector, etc.) and mention dominant colors from your CSS variables. Use landscape aspect ratios for hero banners, square for inline illustrations. Keep prompts specific — "isometric illustration of a message queue with cyan nodes on dark navy background" beats "a diagram of a queue."
The template handles all styling automatically via the named palette. Focus on:
domain-1 through domain-5 to specific concerns in your legend, then use matching domain fields on card sectionshero for the primary overview, card for detailed type descriptions, callout for important notes, collapsible for supplementary content**bold**, `code`, [links](url), and lists naturally in content fieldsTo generate the final HTML file:
Copy-Item .agents/skills/visual-explainer/assets/template.html diagrams/output-name.htmlconst DATA = {...}; line is the only thing that changes between diagramsOutput location: Write to ./diagrams/. Use a descriptive filename: modem-architecture.html, pipeline-flow.html.
Open in browser:
open ./diagrams/filename.htmlxdg-open ./diagrams/filename.htmlstart ./diagrams/filename.htmlTell the user the file path so they can re-open or share it.
All diagram types below are rendered via the template's JSON section types. See ./references/section-types.md for full schemas.
Two approaches depending on what matters more:
Text-heavy overviews (card content matters more than connections): Use card sections with inner grids. Cards support rich descriptions, code references, file links, badges, and nested items. Combine with hero for overview and pipeline for process flows.
Topology-focused diagrams (connections matter more than card content): Use mermaid sections. A graph TD or graph LR with custom themeVariables produces proper diagrams with automatic edge routing. Use when the point is showing how components connect.
Use mermaid sections for complex flows with branches and decision points. Use pipeline sections for simple linear step sequences (build pipelines, middleware chains, deployment stages).
Use mermaid sections. Mermaid supports sequenceDiagram, erDiagram, stateDiagram-v2, mindmap, and flowchart syntaxes — all rendered with automatic layout.
stateDiagram-v2 label caveat: Transition labels have a strict parser — colons, parentheses, <br/>, HTML entities, and most special characters cause silent parse failures ("Syntax error in text"). If your labels need any of these (e.g., cancel(), curate: true, multi-line labels), use flowchart LR instead with rounded nodes and quoted edge labels (|"label text"|). Flowcharts handle all special characters and support <br/> for line breaks. Reserve stateDiagram-v2 for simple single-word or plain-text labels.
Use table sections. The template renders semantic <table> elements with sticky headers, alternating row backgrounds, hover highlights, and responsive overflow handling.
Use proactively. Any time you'd render an ASCII box-drawing table in the terminal, generate an HTML table instead. This includes: NuGet dependency audits, API endpoint inventories, DI service registration tables, configuration binding maps, test result summaries, feature comparisons — any structured rows and columns.
Use pipeline sections for linear timelines. For branching timelines, use mermaid with a graph TD or gitGraph.
Use kpi-row for hero metrics, card sections with inner grids for detail cards. For charts (bar, line, pie), use Chart.js via CDN (see ./references/libraries.md).
Generate magazine-quality slide deck presentations as self-contained HTML files. Use only when explicitly requested — /generate-slides, --slides flag on an existing prompt, or natural language like "as a slide deck." Never auto-select slide format.
Before generating, read ./assets/slide-deck.html (reference template demonstrating all 10 slide types) and ./references/slide-patterns.md (engine CSS, layouts, transitions, presets).
| Type | Use for | Layout | |------|---------|--------| | Title | Opening slide | Centered display te
<!-- Content truncated for initial SEO render. Open the source file tab for the full file. -->Search for places (restaurants, cafes, etc.) via Google Places API proxy on localhost.
Interact with GitHub using the `gh` CLI. Use `gh issue`, `gh pr`, `gh run`, and `gh api` for issues, PRs, CI runs, and advanced queries.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Start voice calls via the OpenClaw voice-call plugin.
Notion API for creating and managing pages, databases, and blocks.
Gemini CLI for one-shot Q&A, summaries, and generation.
Category:developer