ASCII Diagram Validator Skill

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 |

Troubleshooting

| Issue | Cause | Solution | | --------------------------- | ----------------------------- | --------------------------------------------------- | | Script not found | Plugin not installed | Verify plugin installed with claude plugin list | | False positives with tabs | Tab characters misalign | Convert tabs to spaces before validation | | Mixed ASCII not detected | Using +---+ style | Script only validates Unicode box-drawing chars | | Column numbers off | Unicode width calculation | Use pre-composed characters, avoid combining marks | | No issues but looks wrong | Aesthetic spacing not checked | Validator checks structure, not visual spacing | | Exit code 2 unexpected | warnings only mode | Use --warn-only flag to treat warnings as success | | Can't find validation error | Complex nested diagram | Check line numbers in output, validate section only | | Unicode chars not rendering | Terminal font missing glyphs | Use font with full Unicode box-drawing support |

Agent Skills: ASCII Diagram Validator

Install this agent skill to your local

Skill Files