# Box Diagram

> Generate perfectly aligned Unicode box diagrams (replaces ASCII art). Use when the user asks for box diagrams, flowcharts, architecture diagrams, or ASCII art in text format.

- **Type:** Skill
- **Install:** `agentstack add skill-ilia-pluzhnikov-box-diagram-box-diagram`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [ilia-pluzhnikov](https://agentstack.voostack.com/s/ilia-pluzhnikov)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [ilia-pluzhnikov](https://github.com/ilia-pluzhnikov)
- **Source:** https://github.com/ilia-pluzhnikov/box-diagram/tree/master/skills/box-diagram

## Install

```sh
agentstack add skill-ilia-pluzhnikov-box-diagram-box-diagram
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Box Diagram Generator

## Purpose

Generate **perfectly aligned** box diagrams where every box, line, and arrow lines up correctly in monospace fonts. Uses a Python validator to catch misalignment before outputting.

## Workflow

1. Generate the diagram following the Rules below
2. Write diagram to a temp file
3. Run validator: `python ${CLAUDE_SKILL_DIR}/validate.py `
4. If validator reports errors — fix them and re-validate
5. Only output the diagram to the user after it passes validation
6. **Output from the file** — read the validated file and paste its content into the code block. NEVER re-type the diagram manually, as even one lost space breaks alignment

## Validator

Located at `${CLAUDE_SKILL_DIR}/validate.py`

```bash
# Validate a file
python ${CLAUDE_SKILL_DIR}/validate.py diagram.txt

# Validate inline
python ${CLAUDE_SKILL_DIR}/validate.py --inline "╭──╮\n│  │\n╰──╯"
```

Checks:
- Double-width characters (emoji, CJK) that break alignment
- Inconsistent line widths within box groups
- Vertical connector (`│`, `╭`) misalignment between consecutive lines
- Broken box borders (`╭───╮` with wrong fill)
- Tab characters

Returns `OK: N lines, max width M chars` on success, or list of errors.

**IMPORTANT: Always validate before showing the diagram to the user.**

## Rules

### Character Set

Use Unicode box-drawing characters:

| Element | Character | Code point |
|---------|-----------|------------|
| Corners | `╭ ╮ ╰ ╯` | U+256D-256F |
| Horizontal | `─` | U+2500 |
| Vertical | `│` | U+2502 |
| Arrow right | `▸` | U+25B8 |
| Arrow down | `▾` | U+25BE |
| Content arrow | `→` | U+2192 |
| Branch corners | `┌ ┐ └ ┘` | U+250C-2518 |
| T-junctions | `┬ ┴ ├ ┤ ┼` | U+252C-253C |

**NEVER** use emoji — they are double-width and break alignment.

### Box Format

```
╭──────────────────╮
│  Content here    │
╰──────────────────╯
```

Width = left `╭` + dashes + right `╮`. Content lines: `│` + space + text padded to fixed width + space + `│`. The corners and `│` must be in the same columns.

### Construction Method

1. **Define grid**: assign exact column positions for each box (col_A=0, col_B=25, col_C=50)
2. **Fixed-width boxes**: every line in a box must be the same character count
3. **Draw row by row**: pad each content line to match the border width
4. **Connectors**: horizontal dashes count = gap between boxes, vertical `│` shares column with box center
5. **Assert text fits**: `assert len(text) <= inner_width` before generating — one char overflow breaks everything
6. **Validate**: run the Python validator before output

**Prefer Python generation** for diagrams with 3+ boxes. Define helper functions for borders, content lines, and padding — hand-counting spaces is error-prone. Example pattern:

```python
H = '\u2500'  # ─
V = '\u2502'  # │
TL, TR = '\u256d', '\u256e'  # ╭ ╮
BL, BR = '\u2570', '\u256f'  # ╰ ╯

def box_line(text, w):
    return V + ' ' + text + ' ' * (w - len(text)) + ' ' + V
def border_top(w):
    return TL + H * (w + 2) + TR
def border_bot(w):
    return BL + H * (w + 2) + BR
```

### Connector Patterns

```
Horizontal:   ──────────▸     ◂──────────     ◂──────────▸
Vertical:     │               ▴
              │               │
              ▾               │
```

### Branching (fan-out / fan-in)

Fan-out (1 → 3): use `┌` `┬` `┤` or `┐` with `─` between them.
Fan-in (3 → 1): use `└` `┼` `┘` with `─` between them.

```
         │                     (source)
┌────────┼────────┐            fan-out
│        │        │
▾        ▾        ▾
```

```
│        │        │
└────────┼────────┘            fan-in
         │                     (destination)
         ▾
```

### Labels on Arrows

```
       label
A ──────────────────▸ B

    │
    │ label
    ▾
```

## Anti-patterns

- NEVER use emoji (double-width)
- NEVER eyeball alignment — always validate with the script
- NEVER manually re-type the diagram for output — always read from the validated file. Even one lost space breaks alignment between corners and `│`
- NEVER mix tabs and spaces
- Avoid boxes wider than 60 chars

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [ilia-pluzhnikov](https://github.com/ilia-pluzhnikov)
- **Source:** [ilia-pluzhnikov/box-diagram](https://github.com/ilia-pluzhnikov/box-diagram)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-ilia-pluzhnikov-box-diagram-box-diagram
- Seller: https://agentstack.voostack.com/s/ilia-pluzhnikov
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.