markdown-mermaid-writing
Writes scientific documents and documentation as markdown with embedded Mermaid diagrams as the canonical, git-diffable source format. Covers a markdown style guide, a Mermaid style guide, 24 Mermaid diagram type references (flowchart, sequence, ER, Gantt, state, mindmap, radar, sankey, XY chart, and others), and 9 templates (research paper, status report, decision record, how-to, pull request, issue, kanban, presentation, project documentation). Use when writing a report, manuscript, README, or analysis in markdown. Use when adding a workflow, pipeline, timeline, or architecture diagram to a document. Use when choosing the right Mermaid diagram type or fixing Mermaid syntax such as radar-beta or xychart-beta. Use when starting from a document template or checking citations and heading rules. Not for scatter plots of real data or photorealistic images; use Python plotting or scientific-schematics for those.
- License 许可
- Apache-2.0
- 最近更新
- 2026-11-14
- Stars
- ★ 1.6k
- Forks
- 491
01 前言 Front Matter
- name
- markdown-mermaid-writing
- license
- Apache-2.0
- metadata
- { "tags": "Markdown, Mermaid diagrams, technical writing, documentation, diagrams", "version": "1.1", "category": "research-writing", "maintainer": "Kalaris Labs", "contributor": "Clayton Young / Superior Byte Works, LLC (@borealBytes)", "skill-source": "https://github.com/SuperiorByteWorks-LLC/agent-project", "skill-version": "1.0.0", "skill-contributors": "Clayton Young (Superior Byte Works, LLC / @borealBytes; Author and originator)" }
- description
- Writes scientific documents and documentation as markdown with embedded Mermaid diagrams as the canonical, git-diffable source format. Covers a markdown style guide, a Mermaid style guide, 24 Mermaid diagram type references (flowchart, sequence, ER, Gantt, state, mindmap, radar, sankey, XY chart, and others), and 9 templates (research paper, status report, decision record, how-to, pull request, issue, kanban, presentation, project documentation). Use when writing a report, manuscript, README, or analysis in markdown. Use when adding a workflow, pipeline, timeline, or architecture diagram to a document. Use when choosing the right Mermaid diagram type or fixing Mermaid syntax such as radar-beta or xychart-beta. Use when starting from a document template or checking citations and heading rules. Not for scatter plots of real data or photorealistic images; use Python plotting or scientific-schematics for those.
- allowed-tools
- Read Write Edit Bash
02 资源文件 36
- 资产文件assets/examples/example-research-report.md8.8 KB
- 参考文档references/diagrams/architecture.md4.3 KB
- 参考文档references/diagrams/block.md4.7 KB
- 参考文档references/diagrams/c4.md6.1 KB
- 参考文档references/diagrams/class.md8.3 KB
- 参考文档references/diagrams/complex_examples.md16.7 KB
- 参考文档references/diagrams/er.md7.4 KB
- 参考文档references/diagrams/flowchart.md6.8 KB
- 参考文档references/diagrams/gantt.md5.7 KB
- 参考文档references/diagrams/git_graph.md2.0 KB
- 参考文档references/diagrams/kanban.md3.5 KB
- 参考文档references/diagrams/mindmap.md2.2 KB
- 参考文档references/diagrams/packet.md1.7 KB
- 参考文档references/diagrams/pie.md1.5 KB
- 参考文档references/diagrams/quadrant.md2.1 KB
- 参考文档references/diagrams/radar.md2.1 KB
- 参考文档references/diagrams/requirement.md2.4 KB
- 参考文档references/diagrams/sankey.md2.1 KB
- 参考文档references/diagrams/sequence.md5.4 KB
- 参考文档references/diagrams/state.md5.3 KB
- 参考文档references/diagrams/timeline.md4.1 KB
- 参考文档references/diagrams/treemap.md2.0 KB
- 参考文档references/diagrams/user_journey.md4.9 KB
- 参考文档references/diagrams/xy_chart.md1.8 KB
- 参考文档references/diagrams/zenuml.md2.2 KB
- 参考文档references/markdown_style_guide.md34.0 KB
- 参考文档references/mermaid_style_guide.md25.6 KB
- 参考文档templates/decision_record.md6.8 KB
- 参考文档templates/how_to_guide.md6.7 KB
- 参考文档templates/issue.md12.0 KB
- 参考文档templates/kanban.md10.7 KB
- 参考文档templates/presentation.md7.8 KB
- 参考文档templates/project_documentation.md11.2 KB
- 参考文档templates/pull_request.md12.1 KB
- 参考文档templates/research_paper.md9.9 KB
- 参考文档templates/status_report.md6.8 KB
03 SKILL.md 正文
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 (@borealBytes), 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
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<br/>Mermaid in Markdown<br/>(ALWAYS — source of truth)"]
p2["? Phase 2<br/>Python Generated<br/>(optional — data charts)"]
p3["? Phase 3<br/>AI Generated Visuals<br/>(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
</details>— 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— useclassDefonly - One emoji per node max — at the start of the label
snake_casenode 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.
⚠️ Common pitfalls
Radar chart syntax (radar-beta)
WRONG:
radar
title Example
x-axis ["A", "B", "C"]
"Series" : [1, 2, 3]
CORRECT:
radar-beta
title Example
axis a["A"], b["B"], c["C"]
curve series["Series"]{1, 2, 3}
max 3
- Use
radar-betanotradar(the bare keyword doesn't exist) - Use
axisto define dimensions, notx-axis - Use
curveto define data series, not quoted labels with colon - No
accTitle/accDescr— radar-beta doesn't support accessibility annotations; always add a descriptive italic paragraph above the diagram
XY Chart vs Radar confusion
| Diagram | Keyword | Axis syntax | Data syntax |
|---|---|---|---|
| XY Chart (bars/lines) | xychart-beta |
x-axis ["Label1", "Label2"] |
bar [10, 20] or line [10, 20] |
| Radar (spider/web) | radar-beta |
axis id["Label"] |
curve id["Label"]{10, 20} |
Forgetting accTitle/accDescr on supported types
Only some diagram types support accTitle/accDescr. For those that don't, always place a descriptive italic paragraph directly above the code block:
Radar chart comparing three methods across five performance dimensions. Note: Radar charts do not support accTitle/accDescr.
radar-beta
...
? 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 inlinestyle, onlyclassDef? - [ ] Are all external claims cited with
[^N]? - [ ] One H1, emoji on H2 only?
- [ ] Horizontal rules after every
</details>?
? 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 SuperiorByteWorks-LLC/agent-project repository under the Apache-2.0 License.
- Source: https://github.com/SuperiorByteWorks-LLC/agent-project
- Author: Clayton Young / Superior Byte Works, LLC (@borealBytes)
- License: Apache-2.0
This skill (as part of research-agent-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/
Agent operating procedure
- Check the environment. Collect the user's draft, data, figures and target venue before writing anything.
- Pin down the inputs. Confirm formats, identifiers and parameters from the data or the user. Ask rather than guess any value that changes the result.
- Run a small version first. Draft one section or paragraph and confirm tone, structure and terminology with the user.
- Execute the full task using the instructions and references above.
- Validate the result. Every claim traces to the user's data or a verified source; numbers match tables and figures; citations are real (
citation-verification). - Report. State what was run (versions, commands, parameters), what was checked, and what is still uncertain.
| If this happens | Do this |
|---|---|
| A claim has no supporting data or citation | Flag it in the text (e.g. [citation needed]) instead of inventing support. |
| A function, flag or endpoint in these instructions is missing in the installed version | Check the installed version's own documentation (help(), --help, official docs), adapt, and tell the user. Never invent an API. |
| A required input, identifier or parameter is ambiguous | Ask the user, or state the assumption explicitly before running. |
Integrity rules
- Never fabricate results, parameters, identifiers, citations or statistics. If something cannot be run or verified, say so plainly.
- The user is the author: never add results, references or claims they did not provide or approve.
- Treat version-specific details here as possibly outdated: confirm them against the official documentation for the installed version.
- Ask before actions that cost money, consume shared GPUs or cloud quota, touch personal or patient data, or cannot be undone.
Related skills
literature-review: Runs systematic literature reviews by searching PubMed, arXiv, bioRxiv, and Semantic Scholar (plus web search via parallel-cli), screening…academic-plotting: Generates publication-quality figures for ML papers from research context.
04 同仓库更多 Skills
worktable-review-with-annotations
Create, inspect, reply to, update, or resolve situated Worktable annotations. Use when feedback belongs to a Doc section, block, text range, or HTML Doc, or when the user asks to address existing review feedback and coordinate a requested artifact edit.
worktable-find-and-synthesize-context
Find, assess, and synthesize context from Worktable Docs and Records. Use when the user asks what a workspace contains, wants workspace-backed research, needs current facts reconciled across artifacts, or requests a cited synthesis without changing workspace state.
worktable-create-or-update-docs
Create, edit, rename, or maintain narrative Worktable Docs. Use for plans, decisions, briefs, notes, research syntheses, and other durable prose when the user requests a new artifact or a safe update to an existing one.
worktable-create-or-manage-records
Organize repeated structured information as durable Worktable Records. Use for research datasets, inventories, directories, pipelines, trackers, and other collections whose items need identity, fields, filtering, links, validation, or individual updates.
worktable-create-or-manage-interactive-html
Create or improve durable visual and interactive artifacts in Worktable. Use for dashboards, trackers, calculators, mini apps, slide presentations, and other requests that benefit from a polished HTML Doc.
worktable-collaborate-threads
Read, answer, and hand off messages through durable Worktable threads with users or other authenticated participants. Use when the user asks to check addressed messages, reply to a participant, continue a thread, request another agent's help, wait briefly for a response, or watch for comments and messages sent to the agent.