AgentSkillsCN

ascii-guard

修复并验证 Markdown 文件中 ASCII 箱形绘图的对齐问题。在创建架构图、检查图表对齐、修复 ASCII 艺术，或在提交包含图表的文档之前使用。

SKILL.md
--- frontmatter
name: ascii-guard
description: Fix and validate 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 Guard

Fix and validate alignment issues in ASCII box-drawing diagrams in markdown code blocks.

What It Does

ASCII boxes drawn with Unicode characters (┌┐└┘│─ and ╔╗╚╝║═) often have misaligned right borders because content lines are wider or narrower than the border. ASCII Guard detects these mismatches and fixes them automatically by adjusting borders and padding content to a consistent width.

Before

code
┌──────────────────────────────┐
│   Context Personalization     │   ← right │ doesn't align with ┐
│   (welcome msg, ICP,          │
└──────────────┬───────────────┘   ← ┘ doesn't align with ┐ either

After

code
┌───────────────────────────────┐
│   Context Personalization     │   ← all right borders aligned
│   (welcome msg, ICP,          │
└──────────────┬────────────────┘

How to Run

The script is at: scripts/ascii_guard.py

It has zero dependencies (pure Python 3, stdlib only), so run it directly:

Fix files in-place (default)

bash
python3 ${SKILL_DIR}/scripts/ascii_guard.py <file.md>
python3 ${SKILL_DIR}/scripts/ascii_guard.py docs/

Check only (report issues, no modifications)

bash
python3 ${SKILL_DIR}/scripts/ascii_guard.py --check <file.md>

Preview changes as unified diff

bash
python3 ${SKILL_DIR}/scripts/ascii_guard.py --diff <file.md>

Multiple files or directories

bash
python3 ${SKILL_DIR}/scripts/ascii_guard.py docs/*.md README.md
python3 ${SKILL_DIR}/scripts/ascii_guard.py docs/    # recursively finds *.md

Verbose mode (shows box counts per file)

bash
python3 ${SKILL_DIR}/scripts/ascii_guard.py -v <file.md>

When to Use This Skill

Invoke when:

  • •Creating or editing ASCII architecture diagrams in markdown
  • •User mentions "ASCII alignment", "diagram alignment", "box drawing", or "fix ascii"
  • •Before committing docs with box-drawing diagrams
  • •After generating or editing flowcharts in code blocks
  • •When boxes look misaligned in rendered markdown

How It Works

  1. •Finds markdown code blocks (between ``` markers)
  2. •Detects boxes by matching ┌...┐ top borders with └...┘ bottom borders at the same column
  3. •For each box, calculates the maximum inner width across all lines (borders + content)
  4. •Extends narrower borders by adding ─ to the right (preserving ┬/┴ connector positions)
  5. •Pads narrower content lines with trailing spaces
  6. •Processes side-by-side boxes right-to-left to avoid column shifting

Supported Characters

Single-Line

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

Double-Line

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

Exit Codes

CodeMeaning
0All boxes aligned (or fixed)
1Issues found (with --check/--diff)

What It Preserves

  • •Annotations after box borders (<-- NEW, <-- UPDATED)
  • •Vertical connector positions (┬/┴ stay at same column)
  • •Side-by-side box layout
  • •Content that's already at max width (unchanged)
  • •Everything outside code blocks (untouched)