ascii-diagram-validator_skill

Overview

This skill validates and helps fix alignment issues in ASCII box-drawing diagrams embedded in Markdown and text files. It detects misaligned corners, broken verticals/horizontals, and invalid junctions, then reports file:line:column locations. Use it to catch structural diagram errors before committing documentation or publishing architecture notes.

How this skill works

The validator scans files for Unicode box-drawing characters and checks column-by-column alignment rules for single- and double-line glyphs. It classifies problems as errors, warnings, or info and emits compiler-style diagnostics with suggestions to correct each issue. You can run it against a single file, multiple files, or an entire directory and use exit codes to drive automation.

When to use it

• Before committing docs with ASCII diagrams (e.g., docs/ARCHITECTURE.md)
• When a diagram 'looks wrong' or connectors break after edits
• During code review of README or inline code comments containing box-drawing art
• As a CI step to prevent malformed diagrams from merging
• When authoring or updating architecture decision records that include diagrams

Best practices

• Convert tabs to spaces before validating to avoid false positives
• Use consistent single- or double-line box-drawing characters (avoid mixing +---+ style)
• Run validator after any automated edit step that changes line lengths or wrapping
• Treat errors as blocking and warnings as optional cleanup that still merit review
• Normalize Unicode (pre-composed characters) and use a monospace font when editing diagrams

Example use cases

• Validate a single Markdown file: run the script on docs/ARCHITECTURE.md to get precise fix suggestions
• Batch-validate docs: run against docs/*.md to find diagrams broken by bulk edits
• CI integration: fail the job when the validator returns errors to enforce diagram integrity
• Interactive fix loop: edit based on suggestions, re-run until exit code 0
• Authoring workflow: run after an LLM or code assistant updates an ASCII diagram to catch misaligned joints