Claude-skill-registry-data mermaid-collab

Create and collaborate on Mermaid diagrams and UI wireframes with real-time preview and team sharing

install

source · Clone the upstream repo

git clone https://github.com/majiayu000/claude-skill-registry-data

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/majiayu000/claude-skill-registry-data "$T" && mkdir -p ~/.claude/skills && cp -r "$T/data/mermaid-collab" ~/.claude/skills/majiayu000-claude-skill-registry-data-mermaid-collab && rm -rf "$T"

manifest: data/mermaid-collab/SKILL.md

source content

Mermaid Collaboration Tool

This skill helps you create, edit, and collaborate on Mermaid diagrams and UI wireframes using the claude-mermaid-collab server.

What This Tool Provides

Real-time Diagram Editor: Live preview with pan, zoom, and auto-save for Mermaid diagrams
Real-time Document Editor: Markdown document collaboration with live preview
UI Wireframe Plugin: Text-based wireframe creation for mobile, tablet, and desktop
Team Collaboration: Real-time updates across all connected clients via WebSocket
File-Based Storage: Simple
```
.mmd
```
and
```
.md
```
files for version control
Unified Dashboard: Browse and manage both diagrams and documents in one place
MCP Integration: Create and manage diagrams and documents directly from Claude Code

Running the Server

The server can be run from any directory. Use

STORAGE_DIR

to specify where diagrams and documents are stored.

Run from the claude-mermaid-collab repository:

# Store diagrams/docs in a specific project directory
STORAGE_DIR=/path/to/your/project bun run src/server.ts

# Or store in current directory (default)
bun run dev

The server starts on

http://localhost:3737

. The

PUBLIC_DIR

(HTML/CSS/JS) is always resolved relative to the server installation, so static files work regardless of where you run it from.

When to Use This Skill

Use this skill when you need to:

Create flowcharts, state diagrams, sequence diagrams, or any Mermaid diagram
Design UI wireframes and mockups with text-based syntax
Write and collaborate on markdown documentation, specs, or notes
Collaborate with team members in real-time on diagrams or documents
Quickly prototype and iterate on visual designs
Document workflows, architectures, or processes
Create technical documentation with live preview

MCP Tools Available

The server provides these MCP tools through Claude Code:

Diagrams

```
list_diagrams()
```
- List all diagrams with metadata
```
get_diagram(id)
```
- Read diagram content
```
create_diagram(name, content)
```
- Create new diagram (auto-validates)
```
update_diagram(id, content)
```
- Replace full diagram content (auto-validates)
```
patch_diagram(id, old_string, new_string)
```
- Preferred for small edits - efficient search-replace
```
validate_diagram(content)
```
- Check syntax without saving
```
preview_diagram(id)
```
- Get browser URL for diagram

Documents

Documents are markdown files (

.md

) for collaborative writing - specs, documentation, meeting notes, etc.

```
list_documents()
```
- List all markdown documents with metadata
```
get_document(id)
```
- Read full document content and metadata
```
create_document(name, content)
```
- Create new markdown document (returns ID and preview URL)
```
update_document(id, content)
```
- Replace full document content with real-time sync
```
patch_document(id, old_string, new_string)
```
- Preferred for small edits - efficient search-replace
```
preview_document(id)
```
- Get browser URL for document viewer

Patch vs Update

Prefer

patch_document

/
patch_diagram
for targeted changes:

Changing a status field
Updating a single value
Adding text at a specific location

Use

update_document

/
update_diagram
for:

Adding entirely new sections
Restructuring large portions
When patch fails (old_string not found or matches multiple locations)

Note: There is no delete_document MCP tool yet. Use the dashboard delete button or REST API for deletion.

Creating Standard Mermaid Diagrams

Flowchart Example

graph TD
  A[Start] --> B{Is it working?}
  B -->|Yes| C[Great!]
  B -->|No| D[Debug]
  D --> A

Direction Toggle

Use the direction toggle button (⤡) in the editor to switch between:

LR (Left to Right) - Horizontal layout
TD (Top Down) - Vertical layout

Supported directions: TD, TB, BT, RL, LR

Creating UI Wireframes

The built-in wireframe plugin lets you create UI mockups with text syntax.

Basic Wireframe Syntax

wireframe mobile TD
  screen "Login Screen"
    col padding=16
      Title "Welcome Back"
      Input "Email"
      Input "Password"
      Button "Sign In" primary

Viewports

```
wireframe mobile
```
- 375px width
```
wireframe tablet
```
- 768px width
```
wireframe desktop
```
- 1200px width

Layout Directions

```
TD
```
- Top Down (vertical, default)
```
LR
```
- Left Right (horizontal)

Container Types

```
screen "Title"
```
- Top-level screen container
```
col
```
- Vertical column layout
```
row
```
- Horizontal row layout
```
Card
```
- Card container with rounded corners

UI Widgets

Input Controls:

Button "Label"

- Button (can add

primary

secondary

danger

success

)

```
Input "Placeholder"
```
- Text input field
```
Checkbox "Label"
```
- Checkbox with label
```
Radio "Label"
```
- Radio button with label
```
Switch "Label"
```
- Toggle switch
```
Dropdown "Label"
```
- Dropdown selector

Display Elements:

```
Text "Content"
```
- Normal text
```
Title "Heading"
```
- Bold heading text
```
Icon "name"
```
- Icon placeholder
```
Image
```
- Image placeholder
```
Avatar
```
- User avatar circle

Navigation:

```
AppBar "Title"
```
- Top app bar
```
NavMenu "Home|About|Contact"
```
- Horizontal navigation (use
```
|
```
to separate items)
```
BottomNav "Home|Search|Profile"
```
- Bottom navigation
```
FAB "+"
```
- Floating action button

Structure:

```
Grid
```
- Table/grid layout (use with
```
header
```
and
```
row
```
children)
```
List "Item 1|Item 2|Item 3"
```
- List of items
```
divider
```
- Horizontal divider line
```
spacer
```
- Flexible space

Layout Modifiers

Add modifiers after widget names:

```
width=200
```
- Fixed width in pixels
```
height=100
```
- Fixed height in pixels
```
padding=16
```
- Padding around content
```
flex
```
or
```
flex=2
```
- Take remaining space (optionally with weight)
```
align=start|center|end|space-between
```
- Horizontal alignment
```
cross=start|center|end
```
- Vertical alignment

Complex Wireframe Example

wireframe mobile TD
  screen "Dashboard"
    AppBar "My App"
    col padding=16
      Title "Welcome"
      Text "Here's your overview"
      spacer
      row
        Card padding=8 flex
          Text "Sales"
          Title "$1,234"
        Card padding=8 flex
          Text "Orders"
          Title "56"
      spacer
      List "Recent|Pending|Complete"
    BottomNav "Home|Stats|Profile"

Collaborating on Markdown Documents

The document collaboration feature allows teams to write and edit markdown documents with real-time updates, just like diagrams.

What Documents Are For

Documents are markdown (

.md

) files for:

Technical Specifications: API docs, requirements, design specs
Meeting Notes: Collaborative note-taking during meetings
Project Documentation: README files, wikis, guides
Architecture Decisions: ADRs, technical decision records
User Stories: Feature descriptions, acceptance criteria
Team Knowledge: How-tos, troubleshooting guides, onboarding docs

Creating Documents

create_document("api-spec", """
# Payment API Specification

## Overview
This document describes the payment API endpoints.

## Authentication
All requests require Bearer token authentication.

## Endpoints

### POST /api/payments
Create a new payment transaction.

**Request Body:**
```json
{
  "amount": 100.00,
  "currency": "USD",
  "customer_id": "cust_123"
}
\```

**Response:**
```json
{
  "id": "pay_456",
  "status": "pending",
  "created_at": "2024-01-13T10:00:00Z"
}
\```

## Error Codes
- `400` - Invalid request
- `401` - Unauthorized
- `500` - Server error
""")

Document Editor Features

The document editor (

/document.html?id=<id>

) provides:

Split-pane view: Markdown source on left, rendered preview on right
Live preview: See formatted output as you type
Auto-save: Saves automatically 500ms after you stop typing
Undo/Redo: Full history with Ctrl+Z / Ctrl+Shift+Z
Syntax highlighting: Code blocks with language support
Real-time collaboration: See updates from other users instantly
Resizable panes: Drag the separator to adjust layout
Clean content API: Get sanitized HTML for safe rendering
Review workflow: Comment, propose, approve, and reject content

Review Workflow

The document editor includes a review workflow for collaborative editing with visual status indicators:

Toolbar Buttons:

💬 Comment - Add comments to selections or at cursor
◇ Propose (cyan) - Mark content as proposed/suggested
✓ Approve (green) - Mark content as approved
✗ Reject (red) - Mark content as rejected with reason
⊘ Clear - Remove any status markers

Status Types:

Status	Color	Section Marker	Inline Marker
Proposed	Cyan	`<!-- status: proposed: label -->`	`<!-- propose-start: label -->...<!-- propose-end -->`
Approved	Green	`<!-- status: approved -->`	`<!-- approve-start -->...<!-- approve-end -->`
Rejected	Red	`<!-- status: rejected: reason -->`	`<!-- reject-start: reason -->...<!-- reject-end -->`
Comment	Yellow	`<!-- comment: text -->`	`<!-- comment-start: text -->...<!-- comment-end -->`

How It Works:

Select text then click a button → wraps selection with inline markers
Cursor on list item then click → wraps the list item content
Cursor under heading then click → adds section-level status after heading
Toggle between states → clicking Approve on proposed content switches it to approved
Markers are HTML comments, so they're invisible in standard markdown renderers

Example Usage:

## Feature Proposal
<!-- status: proposed: new authentication flow -->

This section describes the new login system.

We should use <!-- propose-start: needs discussion -->OAuth 2.0<!-- propose-end --> for authentication.

- <!-- approve-start -->Email/password login<!-- approve-end -->
- <!-- reject-start: too complex for MVP -->Biometric auth<!-- reject-end -->

Markdown Features Supported

The editor supports full GitHub-Flavored Markdown:

Headings:
```
# H1
```
through
```
###### H6
```
Bold:
```
**bold**
```
or
```
__bold__
```
Italic:
```
*italic*
```
or
```
_italic_
```
Links:
```
[text](url)
```
Images:
```
![alt](url)
```
Code blocks: ```language ... ```
Inline code: `code`
Lists: Unordered (
```
-
```
,
```
*
```
,
```
+
```
) and ordered (
```
1.
```
,
```
2.
```
)
Blockquotes:
```
> quote
```
Tables: Pipe-separated tables
Task lists:
```
- [ ]
```
unchecked,
```
- [x]
```
checked
Horizontal rules:
```
---
```
,
```
***
```
, or
```
___
```

Document Workflow Example

# 1. Create a spec document
result = create_document("feature-spec", """
# User Authentication Feature

## Problem Statement
Users need a secure way to log into the application.

## Proposed Solution
Implement JWT-based authentication with refresh tokens.

## Requirements
1. Email/password login
2. JWT tokens with 15-minute expiry
3. Refresh token rotation
4. Password reset flow

## API Endpoints
- POST /auth/login
- POST /auth/refresh
- POST /auth/logout
- POST /auth/reset-password

## Security Considerations
- Passwords hashed with bcrypt
- Tokens stored in httpOnly cookies
- Rate limiting on login attempts
""")

# 2. Share preview URL with team
preview_document("feature-spec")

# 3. Team reviews and adds comments/updates in real-time

# 4. Update based on feedback
update_document("feature-spec", """
# User Authentication Feature

## Problem Statement
Users need a secure way to log into the application.

## Proposed Solution
Implement JWT-based authentication with refresh tokens and optional 2FA.

## Requirements
1. Email/password login
2. JWT tokens with 15-minute expiry
3. Refresh token rotation
4. Password reset flow
5. **NEW**: Optional TOTP 2FA

## API Endpoints
- POST /auth/login
- POST /auth/refresh
- POST /auth/logout
- POST /auth/reset-password
- **NEW**: POST /auth/2fa/enable
- **NEW**: POST /auth/2fa/verify

## Security Considerations
- Passwords hashed with bcrypt (cost factor 12)
- Tokens stored in httpOnly, secure cookies
- Rate limiting: 5 attempts per 15 minutes
- 2FA backup codes generated on enable
""")

Document Best Practices

Use descriptive names:
```
api-architecture
```
not
```
doc1
```
Structure with headings: Use H1 for title, H2 for sections
Keep it focused: One document per topic/feature
Link related docs: Use markdown links to connect documents
Version in git: Documents are
```
.md
```
files - commit them
Add timestamps: Include "Last updated" dates for living docs
Use code blocks: Properly format code examples with language tags
Create templates: Standardize document structure for consistency

Dashboard Features

The unified dashboard shows both diagrams and documents:

Type badges: Blue "Diagram" and purple "Document" badges
Type filter: Filter by "All Items", "Diagrams Only", or "Documents Only"
Search: Search across both diagrams and documents
Preview: Documents show first heading or first 100 characters
Thumbnails: Diagrams show rendered preview, documents show text excerpt
Sort by date: Newest items first
Delete all: Remove all diagrams and documents at once

Best Practices

Diagram Naming

Use descriptive names:
```
user-login-flow
```
not
```
diagram1
```
Use hyphens, not spaces:
```
api-architecture
```
not
```
api architecture
```
Keep names lowercase for consistency

Collaboration Workflow

Create diagram:
```
create_diagram("feature-flow", content)
```
Share the preview URL with team members
Team members can view real-time updates in their browsers
Everyone sees changes instantly via WebSocket

Wireframe Design Tips

Start with screens: Define your main screens first
Use containers: Group related elements in
```
col
```
and
```
row
```
Add padding: Use
```
padding=16
```
on containers for spacing
Flexible layouts: Use
```
flex
```
for responsive elements
Toggle direction: Try both LR and TD to see what works best

Version Control

All diagrams are stored as

.mmd

files in the

diagrams/

folder:

Easy to commit to git
Plain text, easy to diff
Can edit externally with any text editor
Auto-reloads in the web interface

Editor Features

Keyboard Shortcuts

Undo: Ctrl+Z (managed by editor)
Redo: Ctrl+Shift+Z (managed by editor)
Auto-save: 500ms after typing stops

Pan & Zoom Controls

Mouse wheel: Zoom in/out
Drag: Pan around diagram
⊡ Fit: Fit entire diagram to viewport
↔ Fit Width: Fit diagram width
↕ Fit Height: Fit diagram height
↻ Reset: Reset zoom to 100%
+ / −: Zoom in/out buttons

Resizable Panes

Drag the separator between code and preview
Customize your preferred layout
Setting persists across sessions

Common Patterns

Mobile App Wireframe

wireframe mobile TD
  screen "Profile"
    AppBar "Profile"
    col padding=16
      Avatar
      Title "John Doe"
      Text "john@example.com"
      divider
      List "Settings|Privacy|Help|Logout"

Desktop Dashboard

wireframe desktop LR
  screen "Analytics Dashboard"
    col width=200
      NavMenu "Dashboard|Reports|Users"
    col flex padding=20
      Title "Analytics Overview"
      row
        Card flex padding=16
          Text "Total Users"
          Title "1,234"
        Card flex padding=16
          Text "Revenue"
          Title "$56,789"

Form Layout

wireframe tablet TD
  screen "Registration"
    col padding=24
      Title "Create Account"
      Input "Full Name"
      Input "Email Address"
      Input "Password"
      Checkbox "I agree to terms"
      spacer
      Button "Sign Up" primary
      Text "Already have an account?"

Troubleshooting

Diagram Not Rendering

Check syntax with
```
validate_diagram(content)
```
first
Look at error banner in editor for line-specific errors
Make sure Mermaid syntax is valid

Wireframe Not Showing

Verify first line starts with
```
wireframe
```
Check indentation (use spaces, not tabs)
Make sure viewport is specified:
```
wireframe mobile
```

Real-time Updates Not Working

Check WebSocket connection status (top-right indicator)
Click the status indicator to reconnect if disconnected
Make sure you're subscribed to the correct diagram

Pro Tips

Use validate before save: Call
```
validate_diagram()
```
to catch errors early
Preview URL sharing: Use
```
preview_diagram(id)
```
to get sharable links
Direction matters: Horizontal (LR) works better for wide diagrams, vertical (TD) for tall ones
Prototype fast: Wireframes are text-based, so iterate quickly
Version everything: Commit
```
.mmd
```
files to git for history
Test viewports: Try mobile, tablet, desktop to see what works best
Use badges: Dashboard shows diagram vs document badges for easy identification

Example Workflow

# 1. Create a new wireframe
create_diagram("checkout-flow", """
wireframe mobile TD
  screen "Cart"
    AppBar "Shopping Cart"
    col padding=16
      List "Item 1|Item 2|Item 3"
      divider
      row
        Text "Total"
        spacer
        Title "$99.99"
      Button "Checkout" primary
""")

# 2. Get preview URL
preview_diagram("checkout-flow")

# 3. Share with team, iterate based on feedback

# 4. Update diagram
update_diagram("checkout-flow", """
wireframe mobile TD
  screen "Cart"
    AppBar "Shopping Cart"
    col padding=16
      List "Item 1 - $29.99|Item 2 - $39.99|Item 3 - $30.01"
      divider
      row
        Text "Subtotal"
        spacer
        Text "$99.99"
      row
        Text "Tax"
        spacer
        Text "$8.00"
      row
        Title "Total"
        spacer
        Title "$107.99"
      spacer
      Button "Proceed to Checkout" primary
""")

Resources

Web Dashboard: http://localhost:3737/
Editor: http://localhost:3737/diagram.html?id=<diagram-id>
Mermaid Docs: https://mermaid.js.org/
Project README: See
```
/README.md
```
for full documentation
Wireframe Plugin: See
```
/plugins/wireframe/README.md
```
for detailed syntax

Remember: This is a collaboration tool - diagrams update in real-time for all connected users. Perfect for pair programming, design reviews, and team brainstorming sessions!