Agent Skill

Design Doc Mermaid skill

design-doc-mermaidSpillwaveSolutions/design-doc-mermaidSKILL.md

Create Mermaid diagrams (flowchart, sequence, class, ER, state, C4, architecture) from text or source code. Default for GitHub wiki. Use when asked to create a diagram, generate mermaid, document architecture, or convert code to diagram. PlantUML is only for leftover types. Confluence needs PNG/SVG as well as the fence.

177

always on

79 tokname + description

once used

5,478 tokSKILL.md body

bundled files

243 scripts

installs

78kskills.sh

Install the Design Doc Mermaid skill

Skills CLI (Claude Code, Codex, Cursor and others)

npx skills add https://github.com/SpillwaveSolutions/design-doc-mermaid --skill design-doc-mermaid

Claude Code, by hand (all projects)

git clone --depth 1 https://github.com/SpillwaveSolutions/design-doc-mermaid.git /tmp/design-doc-mermaid
mkdir -p ~/.claude/skills
cp -R /tmp/design-doc-mermaid ~/.claude/skills/design-doc-mermaid

For one project only, copy the folder into .claude/skills/ in that project instead. The agent picks it up when a task matches its description.

What it costs your context

Agent Skills load in three steps. Tokens counted with the o200k tokenizer; your model's count will differ a little.

When	What loads	Cost
Every session	Name and description	79 tok
When the agent uses it	The SKILL.md instructions	5,478 tok
Only if opened	24 bundled files (422 KB)	varies

Until it is used, design-doc-mermaid costs about 17× less than the median MCP server we measured (1,362 tokens on every turn). Skills vs MCP study

Checks

Ships scripts the agent can run. Read them before installing.
The instructions are over 5,000 tokens, the Agent Skills specification's guideline for SKILL.md.
The instructions are over 500 lines; the specification suggests moving detail into reference files.

Checked 2026-10-22 · method

What's inside

The headings of its SKILL.md. Read the full file on GitHub.

Mermaid Architect - Hierarchical Diagram and Documentation Skill
Table of Contents
Decision Tree
Available Guides and Resources
Diagram Type Guides (references/guides/diagrams/)
Code-to-Diagram Guide & Examples
Design Document Templates
Unicode Symbols Guide
Python Scripts (scripts/)
GitHub wiki, WikiTicket, and Confluence
Usage Patterns
Resilient Workflow
Workflow Overview
Key Principle
Using the Script (Recommended)
File Naming Convention
Error Recovery Priority
Manual Fallback Steps
Pattern 6: Resilient Diagram Generation
Unicode Semantic Symbols
Infrastructure & Deployment
Activity Flow with States
Microservices Architecture
Python Utilities