This skill should be used when the user asks to "create diagrams", "generate Mermaid", "visualize architecture", "diagram flows", "draw a sequence diagram", "create a C4 diagram", "add visual diagrams", or mentions diagramming, visualization, flowcharts, sequence diagrams, Mermaid syntax, architecture diagrams, or visual documentation. Use this skill to embed precise, syntactically valid Mermaid diagrams in any discovery deliverable.
From maonpx claudepluginhub javimontano/mao-discovery-frameworkThis skill is limited to using the following tools:
examples/README.mdexamples/sample-output.htmlexamples/sample-output.mdprompts/prompt.mdreferences/mermaid-patterns.mdProvides React and Next.js patterns for component composition, compound components, state management, data fetching, performance optimization, forms, routing, and accessible UIs.
Integrates Apple's FoundationModels for on-device LLM in iOS 26+ apps: text generation, @Generable structured output, tool calling, snapshot streaming.
Reviews Flutter/Dart code with library-agnostic checklist for widget best practices, state management patterns, Dart idioms, performance, accessibility, security, and clean architecture.
Generates syntactically valid, semantically precise Mermaid diagrams for discovery deliverables. Every diagram earns its place — no decorative visuals. Each diagram must compress complexity into clarity, replacing paragraphs of prose with a single visual that a reader grasps in seconds.
Un diagrama que no comprime complejidad en claridad no merece existir. Cada diagrama Mermaid debe reemplazar párrafos de prosa con una visual que el lector comprende en segundos. Decoración ≠ documentación — solo diagramas que ganan su lugar sobreviven.
| Argument | Required | Description |
|---|---|---|
$CONTEXT | Yes | Source material: deliverable content, code analysis, or structured data to visualize |
$DIAGRAM_TYPE | No | Specific type requested (auto-selected if omitted based on content) |
$AUDIENCE | No | Target reader: executive (simplified), technical (detailed), operational (actionable) |
Parameters:
{MODO}: piloto-auto (default) | desatendido | supervisado | paso-a-paso
{FORMATO}: markdown (default, fenced code blocks) | html (pre class="mermaid") | dual{VARIANTE}: ejecutiva (simplified, ≤10 nodes) | técnica (full detail, default)Analyze the content and select the optimal diagram type:
| Content Pattern | Diagram Type | Mermaid Syntax |
|---|---|---|
| System components + relationships | C4 Context/Container | C4Context / C4Container |
| Sequential process steps | Flowchart | flowchart TD/LR |
| Actor interactions over time | Sequence Diagram | sequenceDiagram |
| Entity relationships | Entity Relationship | erDiagram |
| State transitions | State Diagram | stateDiagram-v2 |
| Project timeline / phases | Gantt Chart | gantt |
| Hierarchical decomposition | Mindmap | mindmap |
| 2-axis positioning (e.g., risk vs impact) | Quadrant Chart | quadrantChart |
| Class/module structure | Class Diagram | classDiagram |
| Git/decision branching | Gitgraph | gitGraph |
| User journey steps | User Journey | journey |
| Data flow / pipeline | Flowchart with subgraphs | flowchart LR + subgraph |
Selection criteria: Choose the type that maximizes information density while minimizing cognitive load.
authService not A1). Wrap display labels in quotes if they contain spaces.TD (top-down) for hierarchies, LR (left-right) for flows/sequences.classDef for semantic coloring (e.g., classDef critical fill:#f96,stroke:#333). Max 4 style classes per diagram.Each discovery deliverable has recommended diagram types:
| Deliverable | Primary Diagram | Secondary Diagram |
|---|---|---|
| 01_Stakeholder_Map | Quadrant (influence × interest) | Mindmap (org structure) |
| 02_Brief_Tecnico | Mindmap (stack overview) | Quadrant (health semaphore) |
| 03_Analisis_AS-IS | C4 Context + Container | Class (module dependencies) |
| 04_Mapeo_Flujos | Sequence (E2E flows) | Flowchart (integration map) |
| 05_Escenarios | Flowchart (decision tree) | Quadrant (score positioning) |
| 06_Solution_Roadmap | Gantt (phase timeline) | Flowchart (pivot decision tree) |
| 07_Spec_Funcional | Flowchart (use case flows) | ER (data model) |
| 08_Pitch_Ejecutivo | Mindmap (value pillars) | Gantt (investment timeline) |
| 09_Handover | Flowchart (governance flow) | Gantt (90-day plan) |
Minimum: 1 diagram per deliverable. Recommended: 2. Maximum: 4 (avoid visual overload).
Every diagram passes through validation:
| Criterion | Check |
|---|---|
| Syntax | Renders without errors in Mermaid Live Editor |
| Semantics | Accurately represents the source data |
| Readability | Understandable in <10 seconds for target audience |
| Information density | Conveys info that would take ≥3 sentences in prose |
| Consistency | Uses same terminology as the surrounding document |
| Cross-reference | Node names match entity names used elsewhere in the deliverable |
In Markdown deliverables (default):
> **Figure N**: [1-line description for accessibility]
```mermaid
[diagram code]
```
*Source: [CÓDIGO] / [DOC] / [INFERENCIA]*
In HTML deliverables (on demand):
Embed Mermaid via <pre class="mermaid"> tag with Mermaid JS CDN include. Add alt attribute with text description.
| Decision | Enables | Constrains | When to Use |
|---|---|---|---|
| Max 20 nodes | Readability, quick comprehension | Cannot show full system in one view | Always — split complex diagrams |
| Max 4 style classes | Visual clarity | Limited visual differentiation | Always — more colors = more cognitive load |
| Descriptive IDs | Source readability, self-documenting | Longer Mermaid code | Always — readability > brevity |
| Text summary before diagram | Accessibility, fallback rendering | Minor overhead per diagram | Always — non-negotiable for accessibility |
| C4 extension usage | Rich architecture notation | Limited renderer support | When architecture visualization is primary |
Before delivering any diagram:
| Caso | Estrategia de Manejo |
|---|---|
| Requested diagram type is not supported by the target renderer (e.g., C4 extension in a basic Mermaid viewer) | Fall back to flowchart with subgraphs that emulate C4 structure; document the fallback with a note to the reader |
| Source data would require >40 nodes for a complete representation | Decompose into 2-3 sub-diagrams with explicit cross-reference labels (e.g., "see Diagram 2B for detail"); add an index diagram showing how sub-diagrams relate |
| Diagram contains node labels with special characters that break Mermaid syntax (quotes, brackets, pipes) | Escape characters per Mermaid spec; use descriptive IDs without special characters; place full labels in quoted strings |
| Two equally valid diagram types for the same content (e.g., flowchart vs sequence for an API call chain) | Prefer the type with fewer nodes; if equal, prefer the type that shows temporal ordering (sequence) over structural relationship (flowchart) |
| Decision | Alternativa Descartada | Justificacion |
|---|---|---|
| Enforce max 20 nodes per diagram as a hard rule | Allow unlimited nodes with a "best effort" readability guideline | Soft guidelines are ignored under time pressure; the hard cap forces conscious decomposition decisions that improve every diagram |
| Require accessibility text summary before every diagram | Rely on diagram self-explanation | Screen readers cannot parse Mermaid; non-rendering contexts (email, print) lose all information without text summaries; accessibility is non-negotiable |
| Use descriptive node IDs (authService, paymentDB) over short codes (A1, B2) | Short IDs for compact Mermaid source | Descriptive IDs make the raw Mermaid source self-documenting; when diagrams are reviewed in code, short IDs require cross-referencing a legend |
graph TD
subgraph Core["Mermaid Diagramming Engine"]
A["Type Selection"] --> B["Composition Rules"]
B --> C["Syntax Validation"]
C --> D["Quality Validation"]
end
subgraph Inputs["Inputs"]
E["Source Content"] --> A
F["Diagram Type Hint"] --> A
G["Audience Level"] --> B
end
subgraph Outputs["Outputs"]
D --> H["Mermaid Code Blocks"]
D --> I["Accessibility Text"]
end
subgraph Related["Related Skills"]
J["data-viz-storytelling"] -.-> A
K["output-engineering"] -.-> H
end
03_Analisis_ASIS_{cliente}_{WIP}.md)<pre class="mermaid"> with CDN v10; alt attribute with accessibility text; responsive container; print fallback CSS{fase}_{entregable}_{cliente}_{WIP}.docx{fase}_{entregable}_{cliente}_{WIP}.xlsx{fase}_{entregable}_{cliente}_{WIP}.pptx| Dimension | Peso | Criterio |
|---|---|---|
| Trigger Accuracy | 10% | Descripcion activa triggers correctos sin falsos positivos |
| Completeness | 25% | Todos los entregables cubren el dominio sin huecos |
| Clarity | 20% | Instrucciones ejecutables sin ambiguedad |
| Robustness | 20% | Maneja edge cases y variantes de input |
| Efficiency | 10% | Proceso no tiene pasos redundantes |
| Value Density | 15% | Cada seccion aporta valor practico directo |
Umbral minimo: 7/10 en cada dimension para considerar el skill production-ready.
| Format | Default | Description |
|---|---|---|
markdown | ✅ | Rich Markdown + Mermaid diagrams. Token-efficient. |
html | On demand | Branded HTML (Design System). Visual impact. |
dual | On demand | Both formats. |
Default output is Markdown with embedded Mermaid diagrams. HTML generation requires explicit {FORMATO}=html parameter.
Primary: Mermaid diagram code blocks ready to embed in Markdown or HTML deliverables. Each diagram includes accessibility text summary, source evidence tag, and figure numbering.
Supported diagram types: C4Context, C4Container, flowchart, sequenceDiagram, erDiagram, stateDiagram-v2, gantt, mindmap, quadrantChart, classDiagram, gitGraph, journey.
Autor: Javier Montaño | Última actualización: 12 de marzo de 2026