name: ascii-diagram-validator description: Validates ASCII box-drawing diagram alignment in markdown files. Use when creating architecture diagrams, checking diagram alignment, fixing ASCII art, or before committing documentation with diagrams.

ASCII Diagram Validator

Validate and fix alignment issues in ASCII box-drawing diagrams commonly used in architecture documentation, README files, and code comments.

Overview

ASCII diagrams using box-drawing characters (─│┌┐└┘├┤┬┴┼ and double-line variants ═║╔╗╚╝╠╣╦╩╬) require precise column alignment. This skill provides:

Validation script - Detects misaligned characters with file:line:column locations
Actionable fixes - Specific suggestions for correcting each issue
Multi-file support - Validate individual files or entire directories

When to Use This Skill

Invoke when:

Creating or editing ASCII architecture diagrams in markdown
Reviewing documentation with box-drawing diagrams
Fixing "diagram looks wrong" complaints
Before committing docs/ARCHITECTURE.md or similar files
When user mentions "ASCII alignment", "diagram alignment", or "box drawing"

Supported Characters

Single-Line Box Drawing

Corners: ┌ ┐ └ ┘
Lines:   ─ │
T-joins: ├ ┤ ┬ ┴
Cross:   ┼

Double-Line Box Drawing

Corners: ╔ ╗ ╚ ╝
Lines:   ═ ║
T-joins: ╠ ╣ ╦ ╩
Cross:   ╬

Mixed (Double-Single)

╞ ╟ ╤ ╧ ╪ ╫

Quick Start

Validate a Single File

uv run ${CLAUDE_PLUGIN_ROOT}/skills/ascii-diagram-validator/scripts/check_ascii_alignment.py docs/ARCHITECTURE.md

Validate Multiple Files

uv run ${CLAUDE_PLUGIN_ROOT}/skills/ascii-diagram-validator/scripts/check_ascii_alignment.py docs/*.md

Validate Directory

uv run ${CLAUDE_PLUGIN_ROOT}/skills/ascii-diagram-validator/scripts/check_ascii_alignment.py docs/

Output Format

The script outputs issues in a compiler-like format for easy navigation:

docs/ARCHITECTURE.md:45:12: error: vertical connector '│' at column 12 has no matching character above
  → Suggestion: Add '│', '├', '┤', '┬', or '┼' at line 44, column 12

docs/ARCHITECTURE.md:67:8: warning: horizontal line '─' at column 8 has no terminator
  → Suggestion: Add '┐', '┘', '┤', '┴', or '┼' to close the line

Severity Levels

Level	Description
error	Broken connections, misaligned verticals
warning	Unterminated lines, potential issues
info	Style suggestions (optional cleanup)

Validation Rules

The script checks for:

Vertical Alignment - Vertical connectors (│║) must align with characters above/below
Corner Connections - Corners (┌┐└┘╔╗╚╝) must connect properly to adjacent lines
Junction Validity - T-joins and crosses must have correct incoming/outgoing connections
Line Continuity - Horizontal lines (─═) should terminate at valid endpoints
Box Closure - Boxes should be properly closed (no dangling edges)

Exit Codes

Code	Meaning
0	No issues found
1	Errors detected
2	Warnings only (errors ignored with --warn-only)

Integration with Claude Code

When Claude Code creates or edits ASCII diagrams:

Run the validator script on the file
Review any errors in the output
Apply suggested fixes
Re-run until clean

Example Workflow

# After editing docs/ARCHITECTURE.md
uv run ${CLAUDE_PLUGIN_ROOT}/skills/ascii-diagram-validator/scripts/check_ascii_alignment.py docs/ARCHITECTURE.md

# If errors found, Claude Code can read the output and fix:
# docs/ARCHITECTURE.md:45:12: error: vertical connector '│' at column 12 has no matching character above
# → Edit line 44, column 12 to add the missing connector

Limitations

Detects structural alignment issues, not aesthetic spacing
Requires consistent use of box-drawing characters (no mixed ASCII like +---+)
Tab characters may cause false positives (convert to spaces first)
Unicode normalization not performed (use pre-composed characters)

Bundled Scripts

Script	Purpose
`scripts/check_ascii_alignment.py`	Main validation script

ascii-diagram-validator