Agent skill

Ascii Diagram

by SethGammon in SethGammon/Citadel

Generate perfectly aligned ASCII diagrams — architecture, flow, sequence, box-and-arrow.

MITAuto-check passedDevelopment

Install Ascii Diagram

skills CLI
$ npx skills add SethGammon/Citadel --skill ascii-diagram -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install SethGammon/Citadel ascii-diagram --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/SethGammon/Citadel.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills/ascii-diagram .claude/skills/ascii-diagram && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
ascii-diagram
GitHub stars
923
Token cost
~2.7k tokens
SKILL.md length
933 words
Files
3
Skills in repo
48
Repo updated
First seen
Licence
MIT

At a glance

Generate perfectly aligned ASCII diagrams — architecture, flow, sequence, box-and-arrow.

  • Works in 4 steps: PLAN THE LAYOUT → BUILD ON A CHARACTER GRID → VERIFY ALIGNMENT → …
  • Tasks that involve Diagrams
  • SKILL.md covers Orientation, Protocol, Style Guide and Failure Modes & Recovery, plus 6 more sections
  • Calls node

What it does

Ascii Diagram is an agent skill from SethGammon/Citadel. Generate perfectly aligned ASCII diagrams — architecture, flow, sequence, box-and-arrow. Uses a programmatic character-grid approach so alignment is guaranteed by math, not token prediction. Includes post-render verification.

Its SKILL.md is about 2.7k tokens, which your agent loads only when the skill is triggered. The skill folder holds 3 other files (for example `__benchmarks__/no-citadel-scripts.md` and `__benchmarks__/simple-pipeline.md`).

It sits in Development, covering Diagrams. The repository describes itself as: The operating layer for Claude Code + OpenAI Codex: persistent project memory, intent routing, safety hooks, cost telemetry, and parallel agent fleets. The licence is MIT.

When your agent uses it

  • Tasks that involve Diagrams

Example prompts

  • “/ascii-diagram”

Workflow steps

4 steps, taken from the step headings in SKILL.md.

  1. PLAN THE LAYOUT
  2. BUILD ON A CHARACTER GRID
  3. VERIFY ALIGNMENT
  4. OUTPUT

What it can do on your machine

Read from SKILL.md and the folder at commit 6678bbb. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Shell commands in SKILL.md call:

    • node

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Ascii Diagram loads about 2.7k tokens when it runs. Until then it costs about 60 tokens; SKILL.md has 933 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~60
When it runs · the whole SKILL.md, loaded when a task matches
~2.7k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from SethGammon/Citadel at commit 6678bbb, republished under its MIT licence (© SethGammon). 933 words, ~2,711 tokens.

Download SKILL.mdSave it as .claude/skills/ascii-diagram/SKILL.md (or your agent's skills folder). This skill also uses 2 other files; get the full folder from GitHub.
name
ascii-diagram
description
Generate perfectly aligned ASCII diagrams — architecture, flow, sequence, box-and-arrow. Uses a programmatic character-grid approach so alignment is guaranteed by math, not token prediction. Includes post-render verification.
license
MIT
user-invocable
true
auto-trigger
false
trigger_keywords
ascii diagram, ascii art, box diagram, architecture diagram, flow diagram, sequence diagram, draw a diagram, text diagram

/ascii-diagram — Perfectly Aligned ASCII Diagrams

Orientation

Use when:

  • The user wants any kind of text/ASCII diagram: architecture, flow, sequence, box-and-arrow, tree, table, org chart, network topology
  • A diagram needs to be embedded in markdown, code comments, or plain text
  • Visual alignment matters

Do NOT use when:

  • The user wants an image (suggest Mermaid, PlantUML, or an image tool instead)
  • The diagram is trivial (a single box or a one-line arrow)

What this skill needs:

  • A description of what to diagram
  • Optional: preferred style (single-line +--+, double-line ╔══╗, rounded ╭──╮, heavy ┏━━┓)
  • Optional: target width constraint

Protocol

Step 1: PLAN THE LAYOUT

Before writing ANY characters, plan the diagram structurally:

  1. Identify elements: List every box/node and its label text
  2. Identify connections: List every arrow/line between elements, with optional labels
  3. Choose layout direction: left-to-right, top-to-bottom, or mixed
  4. Calculate dimensions:
    • Each box width = max label line length + 4 (2 padding + 2 border)
    • Each box height = label line count + 2 (top + bottom border)
    • Gutters between boxes: minimum 3 characters for arrows (→)
    • For vertical arrows: minimum 1 row gap

Write this plan out explicitly before proceeding. Example:

Elements:
  A: "Client" → width=10, height=3
  B: "Server" → width=10, height=3
  C: "Database" → width=12, height=3
Layout: left-to-right
Connections: A→B (HTTP), B→C (SQL)
Total width: 10 + 6 + 10 + 6 + 12 = 44
Step 2: BUILD ON A CHARACTER GRID

Use this JavaScript approach mentally (or actually execute it via Bash if the diagram is complex):

javascript
// For complex diagrams, RUN this — don't try to hand-align
class Grid {
  constructor(w, h) {
    this.w = w; this.h = h;
    this.cells = Array.from({length: h}, () => Array(w).fill(' '));
  }
  put(x, y, char) {
    if (x >= 0 && x < this.w && y >= 0 && y < this.h) this.cells[y][x] = char;
  }
  text(x, y, str) {
    for (let i = 0; i < str.length; i++) this.put(x + i, y, str[i]);
  }
  box(x, y, w, h, label) {
    // Top border
    this.put(x, y, '+');
    for (let i = 1; i < w-1; i++) this.put(x+i, y, '-');
    this.put(x+w-1, y, '+');
    // Bottom border
    this.put(x, y+h-1, '+');
    for (let i = 1; i < w-1; i++) this.put(x+i, y+h-1, '-');
    this.put(x+w-1, y+h-1, '+');
    // Sides
    for (let j = 1; j < h-1; j++) {
      this.put(x, y+j, '|');
      this.put(x+w-1, y+j, '|');
    }
    // Label (centered)
    const lines = label.split('\n');
    const startY = y + Math.floor((h - lines.length) / 2);
    for (let li = 0; li < lines.length; li++) {
      const line = lines[li];
      const startX = x + Math.floor((w - line.length) / 2);
      this.text(startX, startY + li, line);
    }
  }
  hArrow(x1, x2, y, label) {
    // Horizontal arrow from x1 to x2 at row y
    const dir = x2 > x1 ? 1 : -1;
    for (let x = x1; x !== x2; x += dir) this.put(x, y, '-');
    this.put(x2, y, dir > 0 ? '>' : '<');
    if (label) {
      const lx = Math.min(x1, x2) + Math.floor((Math.abs(x2-x1) - label.length) / 2);
      this.text(lx, y - 1, label);
    }
  }
  vArrow(x, y1, y2, label) {
    // Vertical arrow from y1 to y2 at column x
    const dir = y2 > y1 ? 1 : -1;
    for (let y = y1; y !== y2; y += dir) this.put(x, y, '|');
    this.put(x, y2, dir > 0 ? 'v' : '^');
    if (label) this.text(x + 2, Math.min(y1, y2) + Math.floor(Math.abs(y2-y1) / 2), label);
  }
  render() {
    return this.cells.map(row => row.join('').trimEnd()).join('\n');
  }
}

For any diagram with 4+ boxes or crossing connections, ACTUALLY RUN the script via Bash using Node. Do not attempt to mentally compute grid coordinates for complex diagrams. This is the entire point of the skill — let code handle alignment.

Pre-built grid engine: .citadel/scripts/grid.cjs provides Grid and autoLayout(). For auto-layout, pass a JSON spec:

bash
node .citadel/scripts/grid.cjs '{"direction":"horizontal","boxes":[{"id":"a","label":"Input"},{"id":"b","label":"Output"}],"arrows":[{"from":"a","to":"b","label":"data"}]}'

For complex/nested diagrams, use the Grid class directly via require():

bash
node -e "
const {Grid} = require('./.citadel/scripts/grid.cjs');
const g = new Grid(60, 10);
g.box(0, 0, 20, 5, 'Box A');
g.box(30, 0, 20, 5, 'Box B');
g.hArrow(20, 29, 2, 'flow');
console.log(g.render());
"

Verification: .citadel/scripts/verify.cjs checks alignment:

bash
echo "<diagram>" | node .citadel/scripts/verify.cjs --stdin
Step 3: VERIFY ALIGNMENT

After generating the diagram, verify these properties:

  1. Box closure: Every + corner has matching corners forming a rectangle
  2. Consistent widths: All rows within a box have the same width
  3. Arrow continuity: Every arrow is an unbroken sequence of -, |, or diagonal characters ending in >, <, v, ^
  4. Label centering: Labels are centered within their boxes (±1 char)
  5. No trailing whitespace issues: Right edges of boxes in the same column align vertically

Verification method: Count characters. Pick any two | side borders that should be in the same column — they MUST be at the same character offset from the start of their respective lines.

If verification fails, fix by adjusting coordinates and re-rendering — do NOT try to patch individual characters.

Step 4: OUTPUT

Present the diagram in a fenced code block:

```
[diagram here]
```

If the diagram was generated by a script, also offer to save the generator script so the user can modify and re-run it.

Style Guide

Box styles (use single-line by default):
Single:  +--------+     Double:  ╔════════╗     Rounded: ╭────────╮
         | Label  |              ║ Label  ║              │ Label  │
         +--------+              ╚════════╝              ╰────────╯
Arrow styles:
Horizontal: ----->    <----->    ──────>
Vertical:   |         |          │
            |         |          │
            v         v          ▼
Labeled:      HTTP
            ------->
Common patterns:

Pipeline (left-to-right):

+-------+     +-------+     +-------+
| Input |---->| Process|--->| Output|
+-------+     +-------+     +-------+

Layered (top-to-bottom):

+-------------------+
|    Presentation   |
+-------------------+
         |
+-------------------+
|     Business      |
+-------------------+
         |
+-------------------+
|       Data        |
+-------------------+

Nested (container with children):

+--[ Kubernetes cluster ]------------------+
|                                          |
|  +----------+  +----------+  +--------+ |
|  | Service  |  | Service  |  |Registry| |
|  +----------+  +----------+  +--------+ |
|                                          |
+------------------------------------------+

Failure Modes & Recovery

SymptomCauseFix
Boxes misaligned verticallyComputed wrong Y offsetRecalculate from top, re-render full grid
Arrow doesn't reach targetOff-by-one in x/y rangeUse box.x + box.w for right edge, not box.x + box.w - 1
Label overflows boxBox width too smallRecalculate: width = max(label.length + 4, minWidth)
Pipes don't line up across rowsMixed tabs/spaces or variable-width charsUse ONLY spaces, ONLY ASCII (unless explicitly using Unicode box-drawing)

Complexity Thresholds

  • 1-3 boxes, linear flow: Render mentally, verify by counting
  • 4-7 boxes, simple topology: Use the Grid class, run via Node
  • 8+ boxes or crossing connections: Use the Grid class, AND generate a reusable script the user can tweak
  • Sequence diagrams: Always use the Grid class — column alignment across many rows is error-prone
Show full SKILL.md (359 more words)Show less

Anti-Patterns (NEVER do these)

  • NEVER freehand complex diagrams — you WILL misalign them
  • NEVER use tabs — only spaces for monospace alignment
  • NEVER mix Unicode box-drawing with ASCII +--+ — pick one style
  • NEVER try to "fix" a misaligned diagram by editing individual lines — re-render from the grid
  • NEVER assume your output is aligned — always verify by counting columns

Fringe Cases

  • .citadel/scripts/grid.cjs not present: The harness hasn't been initialized in this project yet. Either run /do setup to initialize, or use the inline Grid class from Step 2 directly — it's embedded in this skill's protocol as a copy-paste template.
  • User asks for an image, not ASCII: Suggest Mermaid (for GitHub/GitLab rendering), PlantUML, or an image generation tool. Do not attempt to produce ASCII for an image request.
  • Diagram has crossing arrows: ASCII doesn't handle crossings well. Either restructure the layout (change direction, use layered topology) or note the limitation and offer Mermaid instead.
  • Unicode box-drawing renders incorrectly: The user's terminal or font may not support Unicode box-drawing characters. Fall back to single-line ASCII (+--+ style) and note the switch.
  • Diagram is trivial (1-2 nodes): Skip the full protocol. Render directly in a code block without running the grid engine.
  • Very large diagram (20+ nodes): Warn the user that ASCII has width limits. Consider breaking into sub-diagrams or using a proper diagramming tool for publication.

Quality Gates

  • Every diagram MUST pass the verification step (Step 3) — count characters to confirm alignment, or run verify.cjs --stdin
  • No tabs — only spaces
  • Box corners must form closed rectangles
  • All arrows must be unbroken sequences ending in a head character
  • Unicode and ASCII box-drawing styles must not be mixed in the same diagram
  • For diagrams with 4+ boxes: the Grid class was used (not freehand)

Contextual Gates

Disclosure: "Generating ASCII diagram. Output to screen (or file if requested)." Reversibility: green — outputs ASCII diagram to screen or a new file; no existing files modified Trust gates:

  • Any: full diagram generation, verification, and output.

Exit Protocol

Present the diagram in a fenced code block. If a script was used to generate it, offer to save it so the user can tweak and re-run. If verification found issues, fix them before presenting.

© SethGammon, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 2 other files in skills/ascii-diagram of SethGammon/Citadel.

  • SKILL.md
  • __benchmarks__/no-citadel-scripts.md
  • __benchmarks__/simple-pipeline.md

Open the folder on GitHubat commit 6678bbb

Compare with similar skills

Ascii Diagram next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Ascii Diagram compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Ascii Diagram this skillSethGammon/Citadel923—~2.7kAutomated safety check: PassMIT
Archify Diagramstt-a1i/archify82k—~2.9kAutomated safety check: PassMIT
JSON Canvasheyitsnoah/claudesidian2.6k18 repos~3.5kAutomated safety check: PassMIT
Diagram Designcathrynlavery/diagram-design49k1 repos~7.6kAutomated safety check: PassMIT
Fireworks Tech Graphtisfeng/Easydict15k1 repos~1.4kAutomated safety check: PassMIT
Excalidraw Diagramcoleam00/excalidraw-diagram-skill5k2 repos~6.1kAutomated safety check: PassNone

Similar skills

  • Archify Diagrams

    tt-a1i/archify

    Creates interactive architecture, workflow, sequence, data-flow and lifecycle diagrams as standalone HTML with inline SVG, themes and image or video export.

    82k GitHub stars~2.9k tokensUpdated today
    DevelopmentAuto-check passed
  • JSON Canvas

    heyitsnoah/claudesidian

    Create and edit JSON Canvas files (.canvas) with nodes, edges, groups, and connections.

    2.6k GitHub starsUsed in 18 repos~3.5k tokens
    DevelopmentAuto-check passed
  • Diagram Design

    cathrynlavery/diagram-design

    Creates branded diagrams, from architecture, flowchart and sequence to charts and maps, as self-contained HTML with inline SVG, with import from draw.io, Mermaid and Excalidraw.

    49k GitHub starsUsed in 1 repo~7.6k tokens
    DevelopmentAuto-check passed
  • Fireworks Tech Graph

    tisfeng/Easydict

    Create precise SVG technical diagrams, export PNG or offline HTML, and animate supported semantic SVGs to GIF.

    15k GitHub starsUsed in 1 repo~1.4k tokens
    DevelopmentAuto-check passed
  • Excalidraw Diagram

    coleam00/excalidraw-diagram-skill

    Create Excalidraw diagram JSON files that make visual arguments.

    5k GitHub starsUsed in 2 repos~6.1k tokens
    DevelopmentAuto-check passed
  • Draw.io Diagram Studio

    Agents365-ai/drawio-skill

    Creates and edits editable draw.io diagrams from descriptions, code, infrastructure files, SQL and API schemas, with sync, review, test and export tools.

    10k GitHub stars~2.4k tokensUpdated today
    DevelopmentAuto-check: notes

More from SethGammon/Citadel

All 48 skills in this repo
  • Create Skill

    SethGammon/Citadel

    Creates new skills from the user's repeating patterns. An agent skill from SethGammon/Citadel.

    923 GitHub stars~1.9k tokensUpdated today
    Auto-check passed
  • Houseclean

    SethGammon/Citadel

    Cross-drive storage audit and cleanup. An agent skill from SethGammon/Citadel.

    923 GitHub stars~2.2k tokensUpdated today
    Auto-check passed
  • Loop

    SethGammon/Citadel

    Bounded foreground repetition for the current session. An agent skill from SethGammon/Citadel.

    923 GitHub stars~1.4k tokensUpdated today
    Auto-check passed
  • Triage

    SethGammon/Citadel

    GitHub issue and PR investigator. An agent skill from SethGammon/Citadel.

    923 GitHub stars~2.7k tokensUpdated today
    Auto-check passed
  • Watch

    SethGammon/Citadel

    File sentinel that monitors the working directory for changes and marker comments, then auto-triggers appropriate skills.

    923 GitHub stars~2.9k tokensUpdated today
    Auto-check passed
  • Archon

    SethGammon/Citadel

    Autonomous multi-session campaign agent. An agent skill from SethGammon/Citadel.

    923 GitHub stars~5.5k tokensUpdated today
    Auto-check passed

Categories

Questions about Ascii Diagram

What does Ascii Diagram do?

Generate perfectly aligned ASCII diagrams — architecture, flow, sequence, box-and-arrow. Ascii Diagram is an agent skill from SethGammon/Citadel. Generate perfectly aligned ASCII diagrams — architecture, flow, sequence, box-and-arrow.

When should I use Ascii Diagram?

Ascii Diagram fits situations like: tasks that involve Diagrams.

How do I install Ascii Diagram in Claude Code?

Run `npx skills add SethGammon/Citadel --skill ascii-diagram -a claude-code`. Or copy the skill folder (skills/ascii-diagram in SethGammon/Citadel) into .claude/skills/ascii-diagram in your project. Claude Code loads it when a task matches its description.

How do I install Ascii Diagram in Codex?

Run `npx skills add SethGammon/Citadel --skill ascii-diagram -a codex`. Or copy the skill folder (skills/ascii-diagram in SethGammon/Citadel) into .agents/skills/ascii-diagram in your project. Codex loads it when a task matches its description.

Can I use Ascii Diagram in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add SethGammon/Citadel --skill ascii-diagram -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/ascii-diagram, .gemini/skills/ascii-diagram, .github/skills/ascii-diagram and .opencode/skills/ascii-diagram in your project.

What does Ascii Diagram need to run?

Going by SKILL.md and its folder, Ascii Diagram needs the command-line tools its instructions call (node).

Does Ascii Diagram access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is Ascii Diagram safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Ascii Diagram use?

Ascii Diagram is published under the MIT licence (declared in SKILL.md). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Ascii Diagram use?

About 2.7k tokens (SKILL.md is roughly 11k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Ascii Diagram?

Skills that share tags, products or a category with Ascii Diagram: Archify Diagrams (tt-a1i/archify, 82k stars), JSON Canvas (heyitsnoah/claudesidian, 2.6k stars), Diagram Design (cathrynlavery/diagram-design, 49k stars) and Fireworks Tech Graph (tisfeng/Easydict, 15k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Ascii Diagram?

SethGammon (a GitHub user) maintains it in SethGammon/Citadel, which has 923 GitHub stars. The repository holds 48 skills in this directory. The repository was last updated on October 10, 2026.

Source: SethGammon/Citadel on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.