Render Mermaid diagrams as terminal-friendly ASCII using https://github.com/AlexanderGrooff/mermaid-ascii

render_mermaid_ascii.sh

#!/usr/bin/env bash
set -euo pipefail

if ! command -v mermaid-ascii >/dev/null 2>&1; then
  echo "error: mermaid-ascii is not installed or not in PATH" >&2
  exit 127
fi

# Pass through non-render subcommands as-is.
if [ "$#" -gt 0 ]; then
  case "$1" in
    web|completion|help)
      exec mermaid-ascii "$@"
      ;;
  esac
fi

has_file_flag=0
expect_file_value=0

for arg in "$@"; do
  if [ "$expect_file_value" -eq 1 ]; then
    expect_file_value=0
    continue
  fi

  case "$arg" in
    -f|--file)
      has_file_flag=1
      expect_file_value=1
      ;;
    -f=*|--file=*)
      has_file_flag=1
      ;;
  esac
done

if [ "$has_file_flag" -eq 1 ]; then
  exec mermaid-ascii "$@"
fi

# Default to stdin input so callers can pipe Mermaid source directly.
exec mermaid-ascii -f - "$@"

SKILL.md

name	description
mermaid-ascii-diagrams	Render Mermaid diagrams as terminal-friendly ASCII using a local mermaid-ascii binary. Use when an explanation or planning discussion needs a visual of component interactions, data flow, process steps, decision paths, or sequence/state transitions.

Mermaid ASCII Diagrams

Overview

Use this skill to turn Mermaid snippets into ASCII diagrams directly in the terminal. Apply it to architecture explanations and planning conversations where visual structure improves clarity.

Workflow

1. Decide if a diagram improves understanding. Prefer diagrams when multiple entities interact, branching exists, or ordering matters.
2. Draft Mermaid source from verified context only.
3. Render with scripts/render_mermaid_ascii.sh.
4. If rendering fails, fix Mermaid syntax and render again.
5. Return:

• The ASCII output in a fenced text block.
• A short explanation tied to the user's question.

Commands

Render from stdin (default behavior when --file is not passed):

cat <<'EOF' | scripts/render_mermaid_ascii.sh --ascii
flowchart TD
  User --> API
  API --> DB[(Database)]
EOF

Render from a Mermaid file:

scripts/render_mermaid_ascii.sh --file /tmp/diagram.mmd --ascii

Render with Unicode border characters (default style):

cat /tmp/diagram.mmd | scripts/render_mermaid_ascii.sh

Diagram Conventions

• Use flowchart TD for component/data flow and planning pipelines.
• Use sequenceDiagram for request/response timelines.
• Keep diagrams under ~12 nodes; split larger systems into focused diagrams.
• Name nodes by responsibility (Auth Service, Queue Worker) rather than low-level implementation details.
• Keep one primary story per diagram.

Resources

• scripts/render_mermaid_ascii.sh: Wrapper around mermaid-ascii that defaults to stdin input (-f -) and validates binary availability.