Markdown Mermaid Writing

What it does

When your agent uses it

• Creating ANY scientific document
• 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

Example prompts

• “/markdown-mermaid-writing”

Requirements

• Python 3
• Pre-approved tools (allowed-tools): Read, Write, Edit, Bash

Workflow steps

5 steps, taken from the step headings in SKILL.md.

1. 1Identify the document type
2. 2Read the style guide
3. 3Pick the diagram type and read its guide
4. 4Write the document
5. 5Commit as text

What it can do on your machine

Read from SKILL.md and the folder at commit 46bea62. It shows what the files ask for, not the result of running them.

• Tool permissions

  Pre-approves these tools, so the agent can use them without asking each time:

  • Read
  • Write
  • Edit
  • Bash

  From allowed-tools in the SKILL.md frontmatter.

• Runs code

  No scripts in the folder and no shell commands in SKILL.md (its code samples are mermaid).

  From the folder's file list and the shell code blocks in SKILL.md.

• Network

  Links to these hosts (documentation or services it may open):

  • github.com
  • github.blog
  • mermaid.js.org

  From URLs in SKILL.md, links to its own repository left out.

• Credentials

  Names no API keys, tokens, secrets or passwords.

  From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Markdown Mermaid Writing loads about 3.8k tokens when it runs, and up to ~46k if it reads all its reference files. Until then it costs about 140 tokens; SKILL.md has 1,346 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it

~140

When it runs · the whole SKILL.md, loaded when a task matches

~3.8k

With references · SKILL.md plus every file in references/, read only if the agent opens them

~46k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

• NotePre-approves every shell command (allowed-tools: Bash)SKILL.md

  allowed-tools: Read, Write, Edit, Bash

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from neflibata-feng/MyArxiv-Agent at commit 46bea62, republished under its Apache-2.0 licence (© neflibata-feng). 1,346 words, ~3,753 tokens.

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 (@borealBytes)

metadata.skill-source

https://github.com/SuperiorByteWorks-LLC/agent-project

metadata.skill-version

1.0.0

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

accTitle: Short Name 3-8 Words
accDescr: One or two sentences explaining what this diagram shows.

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

radar-beta
title Example
axis a["A"], b["B"], c["C"]
curve series["Series"]{1, 2, 3}
max 3

radar-beta
...

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

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

© neflibata-feng, Apache-2.0. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 37 other files (references, assets) in agent/skills/CorePipeline/markdown-mermaid-writing of neflibata-feng/MyArxiv-Agent.

• SKILL.md
• assets/examples/example-research-report.md
• references/diagrams/architecture.md
• references/diagrams/block.md
• references/diagrams/c4.md
• references/diagrams/class.md
• references/diagrams/complex_examples.md
• references/diagrams/er.md
• references/diagrams/flowchart.md
• references/diagrams/gantt.md
• references/diagrams/git_graph.md
• references/diagrams/kanban.md
• references/diagrams/mindmap.md
• references/diagrams/packet.md
• references/diagrams/pie.md
• references/diagrams/quadrant.md
• references/diagrams/radar.md
• … and 21 more

Open the folder on GitHubat commit 46bea62

Used in 5 other repositories

We found 5 copies of this SKILL.md (exact, near-identical or edited) in other folders, from 5 other GitHub owners. This page covers the copy in neflibata-feng/MyArxiv-Agent, which our catalogue first saw on October 7, 2026.

• agent-skills-hub/agent-skills-hubskills/markdown-mermaid-writing
• foryourhealth111-pixel/Vibe-Skillsbundled/skills/markdown-mermaid-writing
• LeonChaoX/qinyan-academic-skillsskills/03-学术演示与可视化/markdown-mermaid-writing
• FreedomIntelligence/OpenClaw-Medical-Skillsskills/markdown-mermaid-writing
• BioTender-max/awesome-bio-agent-skillsskills/openclaw/markdown-mermaid-writing