Graph-Easy Diagram Skill

Create ASCII architecture diagrams for any GitHub Flavored Markdown file using graph-easy. Pure text output with automatic layout - no image rendering required.

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.

When to Use This Skill

• Adding diagrams to README files
• Design specification documentation
• Any GFM markdown file needing architecture visualization
• Creating flowcharts, pipelines, or system diagrams
• User mentions "diagram", "ASCII diagram", "graph-easy", or "architecture chart"

NOT for ADRs - Use

adr-graph-easy-architect

Preflight Check

Ensure graph-easy is installed and functional before rendering. See Preflight Check for the full layered installation guide (mise-first approach, macOS + Linux).

Quick verify:

echo "[Test] -> [OK]" | graph-easy &>/dev/null && echo "✓ graph-easy ready"

DSL Quick Reference

Full syntax reference: DSL Syntax

Essentials

[Node] -> [Node]              # Basic edge
[A] -- label --> [B]          # Labeled edge
[A] <-> [B]                   # Bidirectional
( Group: [Node A] [Node B] )  # Container
[n] { label: "Display Name"; }  # Custom label

Mandatory Graph Attributes

graph { label: "Title"; flow: south; }   # Top-to-bottom
graph { label: "Title"; flow: east; }    # Left-to-right

• Every diagram MUST have

  label:

  with semantic emoji + title
• Every diagram MUST have explicit

  flow:

  direction

Character Safety

ASCII markers:

[x]

[+]

[!]

[OK]

[>]

[*]

[~]

[?]

[=]

Node & Edge Styling

{ shape: rounded; }

{ border: double; }

{ border: bold; }

{ border: dotted; }

->

<->

..>

==>

Common Patterns

See Diagram Patterns for full examples (pipeline, multi-component, decision, grouped, bidirectional, layered architecture).

Quick templates:

# Pipeline (left-to-right)
graph { label: "Pipeline"; flow: east; }
[Input] -> [Process] -> [Output]

# Multi-component (top-down)
graph { label: "System"; flow: south; }
[Gateway] -> [Service A]
[Gateway] -> [Service B]
[Service A] -> [Database]
[Service B] -> [Database]

Rendering

Command (Platform-Aware)

# For GitHub markdown (RECOMMENDED) - renders as solid lines
graph-easy --as=ascii << 'EOF'
graph { flow: south; }
[A] -> [B] -> [C]
EOF

# For terminal/local viewing - prettier Unicode lines
graph-easy --as=boxart << 'EOF'
graph { flow: south; }
[A] -> [B] -> [C]
EOF

Output Modes

ascii

--as=ascii

+--+

boxart

--as=boxart

┌──┐

Why ASCII for GitHub? GitHub renders Unicode box-drawing characters (

┌─┐│└─┘

+---+

|

Post-Generation Alignment Validation (Recommended)

After embedding, validate with:

Skill(doc-tools:ascii-diagram-validator)

• Catches copy-paste alignment drift and font rendering issues
• Skip if diagram was just generated and not manually edited

Embedding in Markdown

Full guide with GFM collapsible section syntax: Embedding Guide

CRITICAL: Every diagram MUST include a

<details>

## Architecture

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

<details>
<summary>graph-easy source</summary>

```
graph { flow: east; }
[Input] -> [Process] -> [Output]
```

</details>

Monospace-Safe Symbols

Full reference: Monospace Symbols

Key markers:

[+]

[x]

[*]

[!]

[>]

Graph Label (MANDATORY: EVERY diagram MUST have emoji + title)

WARNING: This is the most commonly forgotten requirement. Diagrams without labels are invalid.

Correct Example

graph { label: "Deployment Pipeline"; flow: east; }
[Build] -> [Test] -> [Deploy]

Anti-Pattern (INVALID - DO NOT DO THIS)

graph { flow: east; }
[Build] -> [Test] -> [Deploy]

Why this is wrong: Missing

label:

Mandatory Checklist (Before Rendering)

Graph-Level (MUST have)

• graph { label: "Title"; }

  - semantic emoji + title (MOST FORGOTTEN - check first!)

• graph { flow: south; }

  or

  graph { flow: east; }

  - explicit direction
• Command uses

  --as=ascii

  for GitHub markdown (or

  --as=boxart

  for terminal only)

Embedding (MUST have - non-negotiable)

• <details>

  block with source - EVERY diagram MUST have collapsible source code block
• Never commit a diagram without its reproducible source

Post-Embedding Validation (Recommended)

• Run

  ascii-diagram-validator

  on the file after embedding diagram
• Especially important if diagram was manually edited after generation

Node & Edge Styling

• Start/end:

  { shape: rounded; }

  | Critical:

  { border: double; }

  | Optional:

  { border: dotted; }

• Main path:

  ->

  | Conditional:

  ..>

  | Critical:

  ==>

  | Labels: 1-3 words
• NO graphical emojis inside nodes; emojis ONLY in

  graph { label: "..."; }

Structure

• Groups

  ( Name: ... )

  for 4+ related nodes
• Node IDs short, labels descriptive:

  [db] { label: "PostgreSQL"; }

• Max 7-10 nodes per diagram (split if larger)

Success Criteria

Correctness

1. Parses without error - graph-easy accepts the DSL
2. Renders cleanly - no misaligned boxes or broken lines
3. Matches content - all key elements from description represented
4. Source preserved (MANDATORY) - EVERY diagram MUST have

   <details>

   block with graph-easy DSL source

Aesthetics

1. Platform-appropriate output -

   --as=ascii

   for GitHub,

   --as=boxart

   for terminal
2. Readable labels - multiline with

   \n

   , no truncation
3. Clear flow - direction matches natural reading (top-down or left-right)
4. Consistent styling - same border style = same semantic meaning throughout

Comprehensiveness

1. Edge semantics - solid=normal, dotted=conditional, bold=critical
2. Logical grouping - related nodes in

   ( Group: ... )

   containers

Troubleshooting

command not found

--as=boxart

--as=ascii

graph { label: "Title"; flow: south; }

graph { flow: south; }

flow: east

Resources

• Graph::Easy on CPAN
• Graph::Easy Manual
• Graph::Easy GitHub

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.