claude-scientific-skills/docs/project/issues/issue-00000001-markdown-mermaid-skill.md

Issue-00000001: Add Markdown and Mermaid Writing Skill

Field	Value
Issue	#00000001
Type	✨ Feature
Severity	🟡 Medium
Priority	P1
Reporter	Clayton Young (Boreal Bytes / Superior Byte Works, LLC)
Assignee	Unassigned
Date reported	2026-02-19
Status	Open
Users affected	All scientific skill users producing documentation, reports, or diagrams
Revenue impact	Indirect — improves skill quality, adoption, and downstream reproducibility
Resolved in	PR-00000001
Time to resolution	TBD

---

📋 Summary

Create a new skill — markdown-mermaid-writing — that establishes markdown with embedded Mermaid diagrams as the DEFAULT and canonical format for scientific documentation output. The core principle: text-based diagrams are the source of truth. Python-generated or AI-generated images are downstream conversions, never the starting point.

Customer impact

Dimension	Assessment
Who's affected	Researchers, scientists, data engineers using skills for documentation
How many	All users producing reports, papers, analysis docs, or any diagrams
Business impact	Reduces downstream rendering failures; improves reproducibility and AI-readability of outputs
Workaround exists	Yes — users can continue using existing image generation methods

---

💡 Motivation and origin

The conversation that sparked this

This feature request emerged from a discussion in the K-Dense Discord on 2026-02-19 about balancing AGENTS.md vs skills and the importance of documentation standards for sharing and combining scientific skills¹ .

"One note I might offer you all in the claude-scientific-skills that would make it even better is better directions for writing markdown. Specifically using mermaid diagrams extensively and using tables and those instead of python created diagrams when it makes sense. From my experience, 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

The K-Dense team responded positively and confirmed this direction aligns with their upcoming reorganization plans² .

Why markdown + Mermaid as source

Aspect	Mermaid in Markdown	Python / AI Images
Version control	✅ Full git diff	❌ Binary blob
Token efficiency	✅ Less than prose descriptions	❌ Base64 or external refs
Human editable	✅ Any text editor	❌ Requires regeneration
AI parseable	✅ Structured text, no vision model	❌ Requires vision model
Platform support	✅ GitHub, GitLab, Notion, VS Code	⚠️ Requires image hosting
Downstream flexibility	✅ Convert to images anytime	❌ One-way
Accessibility	✅ accTitle / accDescr on every diagram	❌ Alt-text often missing

Three-phase workflow

flowchart LR
    accTitle: Documentation Production Workflow
    accDescr: Mermaid in markdown is the required source phase. Python and AI-generated images are optional downstream phases for polished output only.

    source["📄 Phase 1 — Mermaid in Markdown\n(ALWAYS — source of truth)"]
    python["🐍 Phase 2 — Python Generated\n(optional — when charts needed)"]
    ai["🎨 Phase 3 — AI Generated\n(optional — polished visuals)"]
    final["📊 Final Output"]

    source --> python
    source --> ai
    python --> final
    ai --> final
    source --> final

    classDef source 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 source source
    class python,ai optional
    class final output

---

🎯 Acceptance criteria

Must have

• New skill directory: scientific-skills/markdown-mermaid-writing/
• SKILL.md with YAML frontmatter, philosophy section, workflow guide
• Markdown style guide (references/markdown_style_guide.md) — full guide, ~730 lines
• Mermaid style guide (references/mermaid_style_guide.md) — full guide, ~454 lines
• All 24 diagram type guides (references/diagrams/*.md)
• All 9 document templates (templates/*.md)
• Example research report in assets/examples/
• Issue and PR documents following the AGENTS.md "Everything is Code" convention

Must not have

• Modification of any existing skills
• Breaking changes to repo structure
• Removal of Python/AI image generation options — those remain valid as downstream phases

Integration points

• scientific-schematics — use after mermaid source to generate AI-polished images
• scientific-writing — use this skill for all document structure and diagrams within manuscripts
• literature-review — use this skill for formatting findings and relationship diagrams

---

🔍 Technical details

Content sources

All style guides and templates ported from the borealBytes/opencode repository under Apache-2.0 license with attribution retained³ .

Source path	Destination
agentic/markdown_style_guide.md	references/markdown_style_guide.md
agentic/mermaid_style_guide.md	references/mermaid_style_guide.md
agentic/mermaid_diagrams/*.md (24 files)	references/diagrams/*.md
agentic/markdown_templates/*.md (9 files)	templates/*.md

Skill directory structure

scientific-skills/markdown-mermaid-writing/
├── SKILL.md
├── references/
│   ├── markdown_style_guide.md
│   ├── mermaid_style_guide.md
│   └── diagrams/           ← 24 diagram type guides
│       ├── flowchart.md
│       ├── sequence.md
│       └── [22 more]
├── templates/              ← 9 document templates
│   ├── pull_request.md
│   ├── issue.md
│   └── [7 more]
└── assets/
    └── examples/
        └── example-research-report.md

---

📝 References

---

Last updated: 2026-02-19

---

1. K-Dense Discord thread, 2026-02-19. Discussion between Clayton Young (Boreal Bytes), Orion Li (K-Dense), and Timothy about AGENTS.md standards and scientific documentation. ↩︎

2. Orion Li (K-Dense), responding: "Thanks for letting us know! We'll make sure to include this into our sauce when we implement our upcoming reorganization of the skills." — K-Dense Discord, 2026-02-19. ↩︎

3. Boreal Bytes / Superior Byte Works, LLC. opencode repository. https://github.com/borealBytes/opencode. Apache-2.0 License. ↩︎