escritura-markdown-mermaid

Escritura en Markdown y Mermaid

Resumen

Esta habilidad te enseña — e impone un estándar para — la creación de documentación científica utilizando markdown con diagramas Mermaid incrustados como formato predeterminado y canónico.

La apuesta central: una relación expresada como un diagrama Mermaid dentro de un archivo .md es más valiosa que cualquier imagen. Es texto, por lo que diferencia limpiamente en git. No requiere un paso de compilación. Se renderiza de forma nativa en GitHub, GitLab, Notion, VS Code y cualquier visor de markdown. Utiliza menos tokens que una descripción en prosa de la misma relación. Y siempre se puede convertir a una imagen pulida más tarde, pero la versión de texto sigue siendo la fuente de verdad.

"Cuanto más tengas tus informes y archivos en .md en texto plano normal, que mermaid también lo es además de ser un simple 'lenguaje de script'. Esto solo ayuda con cualquier renderizado posterior y especialmente con imágenes generadas por IA (usando mermaid en lugar de solo texto extenso para describir relaciones < tokens). Además, mermaid puede renderizarse junto con markdown para un uso fácil en casi cualquier lugar por humanos o IA."

— Clayton Young (@borealBytes), K-Dense Discord, 2026-02-19

Cuándo usar esta habilidad

Usa esta habilidad cuando:

• Creando cualquier documento científico — informes, análisis, manuscritos, secciones de métodos
• Escribiendo cualquier documentación — READMEs, guías, registros de decisiones, documentación de proyectos
• Produciendo cualquier diagrama — flujos de trabajo, pipelines de datos, arquitecturas, cronogramas, relaciones
• Generando cualquier resultado que esté bajo control de versiones — si va a ir a git, debe ser markdown
• Trabajando con cualquier otra habilidad — esta habilidad define la capa de documentación que envuelve cada otro resultado
• Alguien te pide que "añadas un diagrama" o "visualices la relación" — Mermaid primero, siempre

NO empieces con matplotlib de Python, seaborn, o generación de imágenes por IA para diagramas estructurales o de relaciones. Esas son Fase 2 y Fase 3 — solo se usan cuando Mermaid no puede expresar lo necesario (por ejemplo, gráficos de dispersión con datos reales, imágenes fotorrealistas).

🎨 La filosofía del formato fuente

Por qué ganan los diagramas basados en texto

Qué importa	Mermaid en Markdown	Python / Imagen IA
Diferencia legible en git	✅	❌ blob binario
Editable sin regenerar	✅	❌
Eficiente en tokens vs. prosa	✅ más pequeño	❌ más grande
Se renderiza sin paso de compilación	✅	❌ necesita alojamiento
Analizable por IA sin visión	✅	❌
Funciona en GitHub / GitLab / Notion	✅	⚠️ si está alojado
Accesible (lectores de pantalla)	✅ accTitle/accDescr	⚠️ necesita texto alternativo
Convertible a imagen después	✅ en cualquier momento	— ya es imagen

El flujo de trabajo de tres fases

flowchart LR
    accTitle: Flujo de Trabajo de Documentación en Tres Fases
    accDescr: La Fase 1 de Mermaid en markdown siempre es obligatoria y es la fuente de verdad. Las Fases 2 y 3 son conversiones descendentes opcionales para resultados pulidos.

    p1["📄 Fase 1<br/>Mermaid en Markdown<br/>(SIEMPRE — fuente de verdad)"]
    p2["🐍 Fase 2<br/>Generado por Python<br/>(opcional — gráficos de datos)"]
    p3["🎨 Fase 3<br/>Visuales Generados por IA<br/>(opcional — pulido)"]
    out["📊 Entregable Final"]

    p1 --> out
    p1 -.->|"cuando sea necesario"| p2
    p1 -.->|"cuando sea necesario"| p3
    p2 --> out
    p3 --> out

    classDef required fill:#dbeafe,stroke:#2563eb,stroke-width:2px,color:#1e3a5f
    classDef optional fill:#fef9c3,stroke:#ca8a04,stroke-width:2px,color:#713f12
    classDef output fill:#dcfce7,stroke:#16a34a,stroke-width:2px,color:#14532d

    class p1 required
    class p2,p3 optional
    class out output

La Fase 1 es obligatoria. Incluso si procedes a la Fase 2 o 3, la fuente de Mermaid permanece confirmada.

Qué puede expresar Mermaid

Mermaid cubre 24 tipos de diagramas. Casi todas las relaciones científicas se ajustan a uno:

Caso de uso	Tipo de diagrama	Archivo
Flujo de trabajo experimental / lógica de decisión	Diagrama de flujo	references/diagrams/flowchart.md
Interacciones de servicios / llamadas API / mensajería	Secuencia	references/diagrams/sequence.md
Modelo de datos / esquema	Diagrama ER	references/diagrams/er.md
Máquina de estados / ciclo de vida	Estado	references/diagrams/state.md
Cronograma de proyecto / hoja de ruta	Gantt	references/diagrams/gantt.md
Proporciones / composición	Circular	references/diagrams/pie.md
Arquitectura del sistema (niveles de zoom)	C4	references/diagrams/c4.md
Jerarquía de conceptos / lluvia de ideas	Mapa mental	references/diagrams/mindmap.md
Eventos cronológicos / historia	Línea de tiempo	references/diagrams/timeline.md
Jerarquía de clases / relaciones de tipos	Clase	references/diagrams/class.md
Viaje del usuario / mapa de satisfacción	Viaje del usuario	references/diagrams/user_journey.md
Comparación de dos ejes / priorización	Cuadrante	references/diagrams/quadrant.md
Trazabilidad de requisitos	Requisito	references/diagrams/requirement.md
Magnitud de flujo / distribución de recursos	Sankey	references/diagrams/sankey.md
Tendencias numéricas / gráficos de barras + líneas	Gráfico XY	references/diagrams/xy_chart.md
Diseño de componentes / disposición espacial	Bloque	references/diagrams/block.md
Estado de elementos de trabajo / columnas de tareas	Kanban	references/diagrams/kanban.md
Infraestructura en la nube / topología de servicios	Arquitectura	references/diagrams/architecture.md
Comparación multidimensional / radar de habilidades	Radar	references/diagrams/radar.md
Proporciones jerárquicas / presupuesto	Treemap	references/diagrams/treemap.md
Protocolo binario / formato de datos	Paquete	references/diagrams/packet.md
Ramificación de Git / estrategia de fusión	Grafo Git	references/diagrams/git_graph.md
Secuencia estilo código (sintaxis de programación)	ZenUML	references/diagrams/zenuml.md
Patrones de composición de múltiples diagramas	Ejemplos complejos	references/diagrams/complex_examples.md

💡 Elige el tipo correcto, no el fácil. No uses diagramas de flujo por defecto para todo. Una línea de tiempo supera a un diagrama de flujo para eventos cronológicos. Una secuencia supera a un diagrama de flujo para interacciones de servicios. Escanea la tabla y encuentra la coincidencia.

---

🔧 Flujo de trabajo principal

Paso 1: Identifica el tipo de documento

Verifica si existe una plantilla antes de escribir desde cero:

Tipo de documento	Plantilla
Registro de solicitud de extracción	templates/pull_request.md
Incidencia / error / solicitud de función	templates/issue.md
Sprint / tablero de proyecto	templates/kanban.md
Decisión de arquitectura (ADR)	templates/decision_record.md
Presentación / informe	templates/presentation.md
Artículo de investigación / análisis	templates/research_paper.md
Documentación de proyecto	templates/project_documentation.md
Guía práctica / tutorial	templates/how_to_guide.md
Informe de estado	templates/status_report.md

Paso 2: Lee la guía de estilo

Antes de escribir cualquier archivo .md: lee references/markdown_style_guide.md.

Reglas clave a interiorizar:

• Un H1 por documento — el título. Nunca más.
• Emoji solo en encabezados H2 — un emoji por H2, ninguno en H3/H4
• Cita todo — cada afirmación externa recibe una nota al pie [^N] con la URL completa
• Negrita con moderación — máximo 2-3 términos en negrita por párrafo, nunca frases completas
• Regla horizontal después de cada </details> — obligatorio
• Tablas en lugar de prosa para comparaciones, configuraciones, datos estructurados
• Diagramas en lugar de muros de texto — si describe flujo, estructura o relaciones, añade Mermaid

Paso 3: Elige el tipo de diagrama y lee su guía

Antes de crear cualquier diagrama Mermaid: lee references/mermaid_style_guide.md.

Luego abre el archivo de tipo específico (por ejemplo, references/diagrams/flowchart.md) para el ejemplo, consejos y plantilla de copiar y pegar.

Reglas obligatorias para cada diagrama:

accTitle: Nombre Corto 3-8 Palabras
accDescr: Una o dos oraciones que explican qué muestra este diagrama.

• Sin directivas %%{init} — rompe el modo oscuro de GitHub
• Sin style en línea — usa solo classDef
• Un emoji por nodo como máximo — al inicio de la etiqueta
• IDs de nodo en snake_case — que coincidan con la etiqueta

Paso 4: Escribe el documento

Empieza desde la plantilla. Aplica la guía de estilo de markdown. Coloca los diagramas en línea con el texto relacionado, no en una sección separada de "Figuras".

Paso 5: Confirma como texto

El archivo .md con Mermaid incrustado es lo que se confirma. Si también generaste un PNG o imagen de IA, esos son complementarios — el markdown es la fuente.

---

⚠️ Errores comunes

Sintaxis del gráfico radar (radar-beta)

INCORRECTO:

radar
title Ejemplo
x-axis ["A", "B", "C"]
"Serie" : [1, 2, 3]

CORRECTO:

radar-beta
title Ejemplo
axis a["A"], b["B"], c["C"]
curve serie["Serie"]{1, 2, 3}
máx 3

• Usa radar-beta no radar (la palabra clave simple no existe)
• Usa axis para definir dimensiones, no x-axis
• Usa curve para definir series de datos, no etiquetas entre comillas con dos puntos
• Sin accTitle/accDescr — radar-beta no admite anotaciones de accesibilidad; siempre añade un párrafo en cursiva descriptivo arriba del diagrama

Confusión entre Gráfico XY y Radar

Diagrama	Palabra clave	Sintaxis de eje	Sintaxis de datos
Gráfico XY (barras/líneas)	xychart-beta	x-axis ["Etiqueta1", "Etiqueta2"]	bar [10, 20] o line [10, 20]
Radar (telaraña/red)	radar-beta	axis id["Etiqueta"]	curve id["Etiqueta"]{10, 20}

Olvidar accTitle/accDescr en tipos compatibles

Solo algunos tipos de diagrama admiten accTitle/accDescr. Para aquellos que no, coloca siempre un párrafo en cursiva descriptivo directamente arriba del bloque de código:

Gráfico radar que compara tres métodos en cinco dimensiones de rendimiento. Nota: Los gráficos radar no admiten accTitle/accDescr.

radar-beta
...

---

🔗 Integración con otras habilidades

Con scientific-schematics

scientific-schematics genera imágenes de calidad de publicación impulsadas por IA (PNG). Usa el diagrama Mermaid como el resumen para el esquema:

Flujo de trabajo:
1. Crea el concepto como Mermaid en .md (esta habilidad — Fase 1)
2. Describe el mismo concepto a scientific-schematics para un PNG pulido (Fase 3)
3. Confirma ambos — el .md como fuente, el PNG como figura complementaria

Con scientific-writing

Cuando scientific-writing produce un manuscrito, todos los diagramas y figuras estructurales deben usar los estándares de esta habilidad. La habilidad de escritura maneja la prosa y las citas; esta habilidad maneja la estructura visual.

Flujo de trabajo:
1. Usa scientific-writing para redactar el manuscrito
2. Para cada figura que muestre un flujo de trabajo, arquitectura o relación:
   - Reemplaza el marcador de posición con un diagrama Mermaid siguiendo la guía de esta habilidad
3. Usa scientific-schematics solo para figuras que realmente necesiten renderizado fotorrealista/complejo

Con literature-review

La revisión de literatura produce resúmenes con muchos datos de relaciones. Usa esta habilidad para:

• Crear mapas conceptuales (Mapa mental) del panorama de la literatura
• Mostrar cronogramas de publicación (Línea de tiempo o Gantt)
• Comparar metodologías (Cuadrante o Radar)
• Diagramar flujos de datos descritos en documentos (Secuencia o Diagrama de flujo)

Con cualquier habilidad que produzca documentos de salida

Antes de finalizar cualquier documento de cualquier habilidad, aplica la lista de verificación de esta habilidad:

• ¿El documento usa una plantilla? Si es así, ¿empecé con la correcta?
• ¿Todos los diagramas están en Mermaid con accTitle + accDescr?
• ¿Sin %%{init}, sin style en línea, solo classDef?
• ¿Todas las afirmaciones externas están citadas con [^N]?
• ¿Un H1, emoji solo en H2?
• ¿Reglas horizontales después de cada </details>?

---

📚 Índice de referencia

Guías de estilo

Guía	Ruta	Líneas	Qué cubre
Guía de estilo de Markdown	references/markdown_style_guide.md	~733	Encabezados, formato, citas, tablas, integración con Mermaid, plantillas, lista de verificación de calidad
Guía de estilo de Mermaid	references/mermaid_style_guide.md	~458	Accesibilidad, conjunto de emojis, clases de color, neutralidad de temas, selección de tipos, niveles de complejidad

Guías de tipo de diagrama (24 tipos)

Cada archivo contiene: ejemplo de calidad de producción, consejos específicos para ese tipo y una plantilla de copiar y pegar.

references/diagrams/ — architecture, block, c4, class, complex_examples, er, flowchart, gantt, git_graph, kanban, mindmap, packet, pie, quadrant, radar, requirement, sankey, sequence, state, timeline, treemap, user_journey, xy_chart, zenuml

Plantillas de documentos (9 tipos)

templates/ — decision_record, how_to_guide, issue, kanban, presentation, project_documentation, pull_request, research_paper, status_report

Ejemplos

assets/examples/example-research-report.md — un informe de investigación científica completo que demuestra la jerarquía adecuada de encabezados, múltiples tipos de diagramas (diagrama de flujo, secuencia, gantt), tablas, citas con notas al pie, secciones plegables y todas las reglas de la guía de estilo aplicadas.

---

📝 Atribución

Todas las guías de estilo, guías de tipo de diagrama y plantillas de documentos en esta habilidad son portadas del repositorio SuperiorByteWorks-LLC/agent-project bajo la Licencia Apache-2.0.

• Fuente: https://github.com/SuperiorByteWorks-LLC/agent-project
• Autor: Clayton Young / Superior Byte Works, LLC (@borealBytes)
• Licencia: Apache-2.0

Esta habilidad (como parte de scientific-agent-skills) se distribuye bajo la Licencia MIT. El contenido incluido bajo Apache-2.0 es compatible para uso descendente con atribución retenida, según se conserva en los encabezados de archivo a lo largo de esta habilidad.

---