graph-easy_skill

Overview

This skill creates ASCII architecture and flow diagrams for GitHub Flavored Markdown using graph-easy. It produces pure-text, machine-aligned diagrams suitable for README files and docs without image rendering. The skill enforces reproducibility by requiring the original graph-easy source be embedded alongside the rendered ASCII output.

How this skill works

It accepts a graph-easy DSL describing nodes, edges, groups, flow direction, labels, and styles, then runs graph-easy to render ASCII or boxart output. The skill prefers platform-aware rendering: --as=ascii for GitHub (solid ASCII borders) and --as=boxart for local terminal viewing. It also provides preflight checks and install guidance to ensure Graph::Easy and graph-easy are present and functional.

When to use it

• Add diagrams to README or design docs
• Document flows, pipelines, or system architecture in Markdown
• Create quick ASCII flowcharts when images are not allowed
• Visualize component relationships inside collapsible GFM sections
• When maintainability and reproducibility of diagrams matter

Best practices

• Always specify graph { flow: ... } explicitly (no defaults)
• Use ASCII-safe markers inside boxes (e.g., [+], [x], [!]) and avoid emojis inside node boxes
• Render with --as=ascii for GitHub to preserve solid box borders; use --as=boxart for local terminal visuals
• Include a collapsible <details> block after the diagram containing the graph-easy source for reproducibility
• Validate alignment after embedding to catch copy/paste drift

Example use cases

• Embed a left-to-right CI/CD pipeline diagram in a README using graph { flow: east; }
• Document microservice interactions and shared database in a documentation page
• Create a decision tree or routing diagram for an API gateway
• Produce a layered architecture diagram (presentation, business, data) for design specs
• Show before/after component changes with ASCII markers in a migration note