ascii-diagram-validator — Claude Code skill: validate ASCII diagrams
The ascii-diagram-validator skill finds structural alignment problems in Markdown box diagrams and reports where they occur. Run it after editing architecture docs or README files.
MIT 217 installs ★ 3 updated 2026-10-25
npx skills add terrylica/cc-skills --skill ascii-diagram-validator -a claude-codeWhat ascii-diagram-validator does
The skill checks Unicode box diagrams for broken vertical connections, invalid corners, and open edges. Its scripts/check_ascii_alignment.py script reports a file, line, and column for each issue, with a suggested correction. It can scan a single file or a directory.
Run the script with uv run, using its path under plugins/doc-tools/skills/ascii-diagram-validator. The check focuses on structure, not visual spacing. It does not inspect diagrams made with ASCII characters such as +---+, and tabs can produce false positives, so convert them to spaces before running the validator.
What it helps with
- locate misaligned vertical connectors in Markdown diagrams
- catch open box edges and unterminated lines
- scan a directory of Markdown files for diagram issues
- get line and column coordinates for broken connections
Example prompts for the agent
- Check
docs/ARCHITECTURE.mdfor structural problems in its box diagrams and fix the reported issues. - Scan the Markdown files in
docs/for broken diagram connections. - Validate the box diagram in the README and show the coordinates of any issues.
How to install ascii-diagram-validator
1Skills CLI (Vercel)
npx skills add terrylica/cc-skills --skill ascii-diagram-validator -a claude-code2Manually: put the files in place
~/.claude/skills/ascii-diagram-validator/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/ascii-diagram-validator/
1Skills CLI (Vercel)
npx skills add terrylica/cc-skills --skill ascii-diagram-validator -a codex2Manually: put the files in place
.agents/skills/ascii-diagram-validator/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add terrylica/cc-skills --skill ascii-diagram-validator -a cursor2Manually: put the files in place
.cursor/skills/ascii-diagram-validator/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install terrylica/cc-skills plugins/doc-tools/skills/ascii-diagram-validator2Manually: put the files in place
.github/skills/ascii-diagram-validator/SKILL.md1Skills CLI (Vercel)
npx skills add terrylica/cc-skills --skill ascii-diagram-validator -a gemini-cli2Platform CLI
gemini skills install https://github.com/terrylica/cc-skills --path plugins/doc-tools/skills/ascii-diagram-validatorManually: put the files in place
.devin/skills/ascii-diagram-validator/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add terrylica/cc-skills --skill ascii-diagram-validator -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about ascii-diagram-validator
How do I install ascii-diagram-validator in Claude Code?
Run npx skills add terrylica/cc-skills --skill ascii-diagram-validator -a claude-code. The skill file is at ~/.claude/skills/ascii-diagram-validator/SKILL.md.
What does ascii-diagram-validator do?
It checks Unicode box diagrams in Markdown for structural problems, including broken connectors and open edges. Its report gives the file, line, and column.
Which diagrams can ascii-diagram-validator check?
It checks diagrams made with single-line and double-line box-drawing characters, including mixed connectors. It does not validate ASCII-style boxes such as +---+.
Source text
SKILL.md · MIT
--- name: ascii-diagram-validator description: Validate ASCII diagram alignment in markdown. TRIGGERS - diagram alignment, ASCII art, box-drawing diagrams. allowed-tools: Bash, Read, Glob --- # ASCII Diagram Validator Validate and fix alignment issues in ASCII box-drawing diagrams commonly used in architecture documentation, README files, and code comments. > **Self-Evolving Skill**: This skill improves through use. If instructions are wrong, parameters drifted, or a workaround was needed — fix this file immediately, don't defer. Only update for real, reproducible issues. ## Overview ASCII diagrams using box-drawing characters (─│┌┐└┘├┤┬┴┼ and double-line variants ═║╔╗╚╝╠╣╦╩╬) require precise column alignment. This skill provides: 1. **Validation script** - Detects misaligned characters with file:line:column locations 2. **Actionable fixes** - Specific suggestions for correcting each issue 3. **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 ```bash /usr/bin/env bash << 'PREFLIGHT_EOF' uv run "$(cc-plugin-root doc-tools)/skills/ascii-diagram-validator/scripts/check_ascii_alignment.py" docs/ARCHITECTURE.md PREFLIGHT_EOF ``` ### Validate Multiple Files ```bash /usr/bin/env bash << 'PREFLIGHT_EOF_2' uv run "$(cc-plugin-root doc-tools)/skills/ascii-diagram-validator/scripts/check_ascii_alignment.py" docs/*.md PREFLIGHT_EOF_2 ``` ### Validate Directory ```bash /usr/bin/env bash << 'PREFLIGHT_EOF_3' uv run "$(cc-plugin-root doc-tools)/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: 1. **Vertical Alignment** - Vertical connectors (│║) must align with characters above/below 2. **Corner Connections** - Corners (┌┐└┘╔╗╚╝) must connect properly to adjacent lines 3. **Junction Validity** - T-joins and crosses must have correct incoming/outgoing connections 4. **Line Continuity** - Horizontal lines (─═) should terminate at valid endpoints 5. **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: 1. Run the validator script on the file 2. Review any errors in the output 3. Apply suggested fixes 4. Re-run until clean ### Example Workflow ```bash /usr/bin/env bash << 'PREFLIGHT_EOF_4' # After editing docs/ARCHITECTURE.md uv run "$(cc-plugin-root doc-tools)/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](https://github.com/joelparkerhenderson/architecture-decision-record) - [Unicode Box Drawing block](https://www.unicode.org/charts/PDF/U2500.pdf) --- ## 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 | ## Post-Execution Reflection After this skill completes, check before closing: 1. **Did the command succeed?** — If not, fix the instruction or error table that caused the failure. 2. **Did parameters or output change?** — If the underlying tool's interface drifted, update Usage examples and Parameters table to match. 3. **Was a workaround needed?** — If you had to improvise (different flags, extra steps), update this SKILL.md so the next invocation doesn't need the same workaround. Only update if the issue is real and reproducible — not speculative.
© terrylica · MIT · terrylica/cc-skills