diff --git a/scientific-skills/markdown-mermaid-writing/SKILL.md b/scientific-skills/markdown-mermaid-writing/SKILL.md new file mode 100644 index 0000000..8c10893 --- /dev/null +++ b/scientific-skills/markdown-mermaid-writing/SKILL.md @@ -0,0 +1,288 @@ +--- +name: markdown-mermaid-writing +description: > + Comprehensive markdown and Mermaid diagram writing skill that establishes text-based + diagrams as the DEFAULT documentation standard. Use this skill when creating ANY + scientific document, report, analysis, or visualization — it ensures all outputs are + in version-controlled, token-efficient markdown with embedded Mermaid diagrams as the + source of truth, with clear pathways to downstream Python or AI-generated images. + Includes full style guides (markdown + mermaid), 24 diagram type references, and + 9 document templates ready to use. +allowed-tools: [Read, Write, Edit, Bash] +license: Apache-2.0 +metadata: + skill-author: Clayton Young / Superior Byte Works, LLC (Boreal Bytes) + skill-source: https://github.com/borealBytes/opencode + skill-version: "1.0.0" + skill-contributors: + - name: Clayton Young + org: Superior Byte Works, LLC / Boreal Bytes + role: Author and originator + - name: K-Dense Team + org: K-Dense Inc. + role: Integration target and community feedback +--- + +# Markdown and Mermaid Writing + +## Overview + +This skill teaches you — and enforces a standard for — creating scientific documentation +using **markdown with embedded Mermaid diagrams as the default and canonical format**. + +The core bet: a relationship expressed as a Mermaid diagram inside a `.md` file is more +valuable than any image. It is text, so it diffs cleanly in git. It requires no build step. +It renders natively on GitHub, GitLab, Notion, VS Code, and any markdown viewer. It uses +fewer tokens than a prose description of the same relationship. And it can always be +converted to a polished image later — but the text version remains the source of truth. + +> "The more you get your reports and files in .md in just regular text, which mermaid is +> as well as being a simple 'script language'. This just helps with any downstream rendering +> and especially AI generated images (using mermaid instead of just long form text to +> describe relationships < tokens). Additionally mermaid can render along with markdown for +> easy use almost anywhere by humans or AI." +> +> — Clayton Young (Boreal Bytes), K-Dense Discord, 2026-02-19 + +## When to Use This Skill + +Use this skill when: + +- Creating **any scientific document** — reports, analyses, manuscripts, methods sections +- Writing **any documentation** — READMEs, how-tos, decision records, project docs +- Producing **any diagram** — workflows, data pipelines, architectures, timelines, relationships +- Generating **any output that will be version-controlled** — if it's going into git, it should be markdown +- Working with **any other skill** — this skill defines the documentation layer that wraps every other output +- Someone asks you to "add a diagram" or "visualize the relationship" — Mermaid first, always + +Do NOT start with Python matplotlib, seaborn, or AI image generation for structural or relational diagrams. +Those are Phase 2 and Phase 3 — only used when Mermaid cannot express what's needed (e.g., scatter plots with real data, photorealistic images). + +## 🎨 The Source Format Philosophy + +### Why text-based diagrams win + +| What matters | Mermaid in Markdown | Python / AI Image | +| ----------------------------- | :-----------------: | :---------------: | +| Git diff readable | ✅ | ❌ binary blob | +| Editable without regenerating | ✅ | ❌ | +| Token efficient vs. prose | ✅ smaller | ❌ larger | +| Renders without a build step | ✅ | ❌ needs hosting | +| Parseable by AI without vision | ✅ | ❌ | +| Works in GitHub / GitLab / Notion | ✅ | ⚠️ if hosted | +| Accessible (screen readers) | ✅ accTitle/accDescr | ⚠️ needs alt text | +| Convertible to image later | ✅ anytime | — already image | + +### The three-phase workflow + +```mermaid +flowchart LR + accTitle: Three-Phase Documentation Workflow + accDescr: Phase 1 Mermaid in markdown is always required and is the source of truth. Phases 2 and 3 are optional downstream conversions for polished output. + + p1["📄 Phase 1\nMermaid in Markdown\n(ALWAYS — source of truth)"] + p2["🐍 Phase 2\nPython Generated\n(optional — data charts)"] + p3["🎨 Phase 3\nAI Generated Visuals\n(optional — polish)"] + out["📊 Final Deliverable"] + + p1 --> out + p1 -.->|"when needed"| p2 + p1 -.->|"when needed"| 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 +``` + +**Phase 1 is mandatory.** Even if you proceed to Phase 2 or 3, the Mermaid source stays committed. + +### What Mermaid can express + +Mermaid covers 24 diagram types. Almost every scientific relationship fits one: + +| Use case | Diagram type | File | +| -------------------------------------------- | ---------------- | ---------------------------------------------------- | +| Experimental workflow / decision logic | Flowchart | `references/diagrams/flowchart.md` | +| Service interactions / API calls / messaging | Sequence | `references/diagrams/sequence.md` | +| Data model / schema | ER diagram | `references/diagrams/er.md` | +| State machine / lifecycle | State | `references/diagrams/state.md` | +| Project timeline / roadmap | Gantt | `references/diagrams/gantt.md` | +| Proportions / composition | Pie | `references/diagrams/pie.md` | +| System architecture (zoom levels) | C4 | `references/diagrams/c4.md` | +| Concept hierarchy / brainstorm | Mindmap | `references/diagrams/mindmap.md` | +| Chronological events / history | Timeline | `references/diagrams/timeline.md` | +| Class hierarchy / type relationships | Class | `references/diagrams/class.md` | +| User journey / satisfaction map | User Journey | `references/diagrams/user_journey.md` | +| Two-axis comparison / prioritization | Quadrant | `references/diagrams/quadrant.md` | +| Requirements traceability | Requirement | `references/diagrams/requirement.md` | +| Flow magnitude / resource distribution | Sankey | `references/diagrams/sankey.md` | +| Numeric trends / bar + line charts | XY Chart | `references/diagrams/xy_chart.md` | +| Component layout / spatial arrangement | Block | `references/diagrams/block.md` | +| Work item status / task columns | Kanban | `references/diagrams/kanban.md` | +| Cloud infrastructure / service topology | Architecture | `references/diagrams/architecture.md` | +| Multi-dimensional comparison / skills radar | Radar | `references/diagrams/radar.md` | +| Hierarchical proportions / budget | Treemap | `references/diagrams/treemap.md` | +| Binary protocol / data format | Packet | `references/diagrams/packet.md` | +| Git branching / merge strategy | Git Graph | `references/diagrams/git_graph.md` | +| Code-style sequence (programming syntax) | ZenUML | `references/diagrams/zenuml.md` | +| Multi-diagram composition patterns | Complex Examples | `references/diagrams/complex_examples.md` | + +> 💡 **Pick the right type, not the easy one.** Don't default to flowcharts for everything. +> A timeline beats a flowchart for chronological events. A sequence beats a flowchart for +> service interactions. Scan the table and match. + +--- + +## 🔧 Core workflow + +### Step 1: Identify the document type + +Check if a template exists before writing from scratch: + +| Document type | Template | +| ------------------------------ | ----------------------------------------------- | +| Pull request record | `templates/pull_request.md` | +| Issue / bug / feature request | `templates/issue.md` | +| Sprint / project board | `templates/kanban.md` | +| Architecture decision (ADR) | `templates/decision_record.md` | +| Presentation / briefing | `templates/presentation.md` | +| Research paper / analysis | `templates/research_paper.md` | +| Project documentation | `templates/project_documentation.md` | +| How-to / tutorial | `templates/how_to_guide.md` | +| Status report | `templates/status_report.md` | + +### Step 2: Read the style guide + +Before writing any `.md` file: read `references/markdown_style_guide.md`. + +Key rules to internalize: + +- **One H1 per document** — the title. Never more. +- **Emoji on H2 headings only** — one emoji per H2, none in H3/H4 +- **Cite everything** — every external claim gets a footnote `[^N]` with full URL +- **Bold sparingly** — max 2-3 bold terms per paragraph, never full sentences +- **Horizontal rule after every ``** — mandatory +- **Tables over prose** for comparisons, configurations, structured data +- **Diagrams over walls of text** — if it describes flow, structure, or relationships, add Mermaid + +### Step 3: Pick the diagram type and read its guide + +Before creating any Mermaid diagram: read `references/mermaid_style_guide.md`. + +Then open the specific type file (e.g., `references/diagrams/flowchart.md`) for the exemplar, tips, and copy-paste template. + +Mandatory rules for every diagram: + +``` +accTitle: Short Name 3-8 Words +accDescr: One or two sentences explaining what this diagram shows. +``` + +- **No `%%{init}` directives** — breaks GitHub dark mode +- **No inline `style`** — use `classDef` only +- **One emoji per node max** — at the start of the label +- **`snake_case` node IDs** — match the label + +### Step 4: Write the document + +Start from the template. Apply the markdown style guide. Place diagrams inline with related text — not in a separate "Figures" section. + +### Step 5: Commit as text + +The `.md` file with embedded Mermaid is what gets committed. If you also generated a PNG or AI image, those are supplementary — the markdown is the source. + +--- + +## 🔗 Integration with other skills + +### With `scientific-schematics` + +`scientific-schematics` generates AI-powered publication-quality images (PNG). Use the Mermaid diagram as the **brief** for the schematic: + +``` +Workflow: +1. Create the concept as Mermaid in .md (this skill — Phase 1) +2. Describe the same concept to scientific-schematics for a polished PNG (Phase 3) +3. Commit both — the .md as source, the PNG as a supplementary figure +``` + +### With `scientific-writing` + +When `scientific-writing` produces a manuscript, all diagrams and structural figures should use this skill's standards. The writing skill handles prose and citations; this skill handles visual structure. + +``` +Workflow: +1. Use scientific-writing to draft the manuscript +2. For every figure that shows a workflow, architecture, or relationship: + - Replace placeholder with a Mermaid diagram following this skill's guide +3. Use scientific-schematics only for figures that truly need photorealistic/complex rendering +``` + +### With `literature-review` + +Literature review produces summaries with lots of relationship data. Use this skill to: + +- Create concept maps (Mindmap) of the literature landscape +- Show publication timelines (Timeline or Gantt) +- Compare methodologies (Quadrant or Radar) +- Diagram data flows described in papers (Sequence or Flowchart) + +### With any skill that produces output documents + +Before finalizing any document from any skill, apply this skill's checklist: + +- [ ] Does the document use a template? If so, did I start from the right one? +- [ ] Are all diagrams in Mermaid with `accTitle` + `accDescr`? +- [ ] No `%%{init}`, no inline `style`, only `classDef`? +- [ ] Are all external claims cited with `[^N]`? +- [ ] One H1, emoji on H2 only? +- [ ] Horizontal rules after every ``? + +--- + +## 📚 Reference index + +### Style guides + +| Guide | Path | Lines | What it covers | +| ----------------------- | ------------------------------------------- | ----- | -------------------------------------------------- | +| Markdown Style Guide | `references/markdown_style_guide.md` | ~733 | Headings, formatting, citations, tables, Mermaid integration, templates, quality checklist | +| Mermaid Style Guide | `references/mermaid_style_guide.md` | ~458 | Accessibility, emoji set, color classes, theme neutrality, type selection, complexity tiers | + +### Diagram type guides (24 types) + +Each file contains: production-quality exemplar, tips specific to that type, and a copy-paste template. + +`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 + +### Document templates (9 types) + +`templates/` — decision\_record, how\_to\_guide, issue, kanban, presentation, project\_documentation, pull\_request, research\_paper, status\_report + +### Examples + +`assets/examples/example-research-report.md` — a complete scientific research report demonstrating proper heading hierarchy, multiple diagram types (flowchart, sequence, gantt), tables, footnote citations, collapsible sections, and all style guide rules applied. + +--- + +## 📝 Attribution + +All style guides, diagram type guides, and document templates in this skill are ported from the `borealBytes/opencode` repository under the Apache-2.0 License. + +- **Source**: https://github.com/borealBytes/opencode +- **Author**: Clayton Young / Superior Byte Works, LLC (Boreal Bytes) +- **License**: Apache-2.0 + +This skill (as part of claude-scientific-skills) is distributed under the MIT License. The included Apache-2.0 content is compatible for downstream use with attribution retained, as preserved in the file headers throughout this skill. + +--- + +[^1]: GitHub Blog. (2022). "Include diagrams in your Markdown files with Mermaid." https://github.blog/2022-02-14-include-diagrams-markdown-files-mermaid/ + +[^2]: Mermaid. "Mermaid Diagramming and Charting Tool." https://mermaid.js.org/