Guide · Agent skill
How to use the Markdown and Mermaid Writing agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The Markdown and Mermaid Writing skill is an add-on for an AI agent that makes it write Markdown documents and draw structural diagrams as Mermaid code inside the text. This guide is for readers who have never installed an agent skill. By the end you will know what the skill does, how to install it, how to ask for work in a way that triggers it, and what to check before relying on the output.
Markdown and Mermaid WritingK-Dense-AI/scientific-agent-skills · MIT Download the skill Quick start
- 1Download the ZIP. Get the skill ZIP from the download link on this page.
- 2Unzip into the skills folder. Extract it to ~/.claude/skills/ for personal use or to .claude/skills/ inside a project.
- 3Or upload it in the Claude apps. Go to Settings, then Capabilities, then Skills, and upload the ZIP.
- 4Make a request. Ask for a Markdown report, README or Mermaid diagram and describe what it should show.
- 5Check rendering. Preview the file where it will be published to confirm the Mermaid diagram displays.
- 6Keep the source. Save the Mermaid code in the repository alongside any exported images.
What an agent skill is and what this one changes
An agent skill is a folder of instructions and reference files that an AI agent can load when a task matches it. This skill, markdown-mermaid-writing, covers two kinds of output: Markdown reports, READMEs, methods overviews and research notes, and structural diagrams such as flowcharts, timelines, schemas, architecture diagrams and Gantt charts.
The diagrams are written as Mermaid code in a .md file. That keeps them as editable plain text that version control can track, and a compatible viewer draws them without a separate build step. The skill includes per-diagram-type reference guides and a house style that adds accessibility labels and rendering-version notes.
- Good fit: workflows, pipelines, schemas, timelines, Gantt charts, architecture and Git branching diagrams
- Not a fit: measured data charts, statistical graphics or publication figures, which the skill says should be made with proper plotting tools
How to install the skill
Download the skill ZIP from the download link on this page. Then choose one of the following locations.
For a personal install, unzip the folder into ~/.claude/skills/. For a single project, unzip it into the project's .claude/skills/ folder. In the Claude apps, you can instead upload the ZIP under Settings, then Capabilities, then Skills.
- Personal: ~/.claude/skills/
- Project only: .claude/skills/ inside the project folder
- Claude apps: Settings → Capabilities → Skills, then upload the ZIP
How to trigger the skill with a natural request
The skill is meant to load when a request asks for Markdown, Mermaid, or a text-based structural diagram. You do not need special syntax. Name the output you want and what it should show.
If you want a quantitative chart, say so. The skill's own guidance is to use plotting tools for measured data, so asking for a bar chart of measurements should lead to a plotting approach instead.
- Write a README for this repository that includes an architecture diagram in Mermaid.
- Draw a Gantt chart in Mermaid for the three phases of this project, with the dates from the plan file.
- Turn these meeting notes into a Markdown report with a timeline of events.
- Show the database schema for these tables as an ER diagram I can keep in git.
Diagram types the skill covers
The skill maps common needs to diagram types. Flowcharts suit decision logic and workflows, timelines suit chronological events, and Gantt charts suit project schedules. Architecture and C4 guides cover system layout, ER diagrams cover data models, and Git Graph covers branching and merge strategy.
The skill's guidance is to match the diagram type to the content rather than defaulting to a flowchart. The example below is a flowchart header copied from the skill's own example, showing the accessibility title and description lines it uses.
flowchart LR
accTitle: Three-Phase Documentation Workflow
accDescr: Markdown holds the structural diagram source. Quantitative charts come from data and plotting code; optional illustrations require a separate factual review.Check how your viewer renders Mermaid
Mermaid renders only where the host supports it. Plain Markdown viewers may show the raw code instead of a diagram, and different platforms ship different Mermaid versions. The skill's reference notes say to run a rendering probe in the place you will publish, rather than assuming every GitHub surface, editor or static-site generator behaves the same.
For local rendering, the skill lists Mermaid CLI, a Node.js version at or above the minimum in its compatibility notes, and a supported Chromium browser. Writing Markdown and Mermaid source needs no runtime. Check the SKILL.md file for the exact versions.
- Writing source: no runtime needed
- Local rendering: Mermaid CLI, Node.js and a supported Chromium browser
- Package or CDN installs: network access needed; no credentials required
Safety notes: scripts and network
According to the skill listing, it runs no scripts and makes no network calls on its own. Network access is only needed if you choose to install packages or CDN assets for local rendering. No credentials are required.
The skill's tool list includes Bash, Read, Write and Edit. Review what the agent is about to run in your environment as you would for any agent with those tools.
Tips for better results
Keep the Mermaid source in the repository next to any exported SVG or PNG files, so the diagram can be edited later. The skill's guidance is to retain the source alongside exported figures.
Treat AI-written diagrams and text as drafts. The skill states it does not replace scientific analysis, and every label and relationship should be checked against its sources.
- Name the document type (report, README, pull request) so the agent can use the matching template
- Say which diagram you want, such as a timeline or sequence, to avoid a generic flowchart
- Ask for accessibility labels if the diagram will be shared widely
What people use it for
- Writing a README with an architecture or deployment diagram that renders on a code host
- Drafting a research note whose workflow is kept as a flowchart in git
- Documenting a database schema as an ER diagram that diffs cleanly in pull requests
- Planning a project with a Gantt chart or timeline stored in a Markdown file
- Recording a Git branching strategy as a Git Graph
Frequently asked questions
Is the markdown-mermaid-writing skill free to use?
The listing states the skill is released under the MIT licence. The SKILL.md file inside the package, however, lists Apache-2.0, so check the LICENSE file in the repository before you redistribute or rely on either licence.
How do I install an agent skill like this one?
Download the ZIP and unzip it into ~/.claude/skills/ for personal use or into .claude/skills/ in a project. In the Claude apps, upload the ZIP under Settings, then Capabilities, then Skills.
What do I need to run the skill?
Writing Markdown and Mermaid source needs no runtime. Local rendering needs Mermaid CLI, a Node.js version meeting the skill's stated minimum, and a supported Chromium browser. No credentials are required.
Can this skill make charts from my data?
Not as a primary tool. The skill is designed for structural diagrams, and it says measured data, statistical graphics and publication figures should be made with proper plotting tools.
Why does my Mermaid diagram show as raw code?
The viewer probably does not support Mermaid, or it runs a different Mermaid version. Check the rendering in the exact place you will publish, since plain Markdown viewers often show only the code.
What are the alternatives to Mermaid for diagrams in Markdown?
The skill's own comparison contrasts Mermaid with Python plotting code and AI-generated images. Use plotting code for quantitative charts and an image tool for illustrations, keeping the Mermaid source where you need editable structure.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
This skill suits researchers, students and developers who want reports and structural diagrams kept as plain text in a git repository and rendered by Mermaid-capable viewers. It is the wrong choice for measured data charts, statistical graphics or publication figures, and for any claim that needs verified science, where dedicated plotting tools and expert review are the better options.
Download the skill