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 /usr/bin/env bash << 'PREFLIGHT_EOF' uv run ${CLAUDE_PLUGIN_ROOT}/skills/ascii-diagram-validator/scripts/check_ascii_alignment.py docs/ARCHITECTURE.md PREFLIGHT_EOF

Validate Multiple Files /usr/bin/env bash << 'PREFLIGHT_EOF_2' uv run ${CLAUDE_PLUGIN_ROOT}/skills/ascii-diagram-validator/scripts/check_ascii_alignment.py docs/*.md PREFLIGHT_EOF_2

Validate Directory /usr/bin/env bash << 'PREFLIGHT_EOF_3' uv run ${CLAUDE_PLUGIN_ROOT}/skills/ascii-diagram-validator/scripts/check_ascii_alignment.py docs/ PREFLIGHT_EOF_3

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 /usr/bin/env bash << 'PREFLIGHT_EOF_4'

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

PREFLIGHT_EOF_4

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 Related ARCHITECTURE.md best practices Unicode Box Drawing block