Skip to content
Skills Library
Design & UX · Conversion & formats

predictygraph

/predictygraph

Draw architecture diagrams, flowcharts and system maps as predictygraph (.pdg) files and render them to SVG or PNG. Use when someone asks for a diagram, a box-and-arrow picture of a system, a flowchart, or a figure for slides or docs, or when they share a .pdg file.

Licence
Apache-2.0
Last repository change
13.11.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
3
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 13.11.2026, without references to retired models or APIs.

Licence

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

What it does and when to use it

Draw architecture diagrams, flowcharts and system maps as predictygraph (.pdg) files and render them to SVG or PNG. Use when someone asks for a diagram, a box-and-arrow picture of a system, a flowchart, or a figure for slides or docs, or when they share a .pdg file.

Original author description

Draw architecture diagrams, flowcharts and system maps as predictygraph (.pdg) files and render them to SVG or PNG. Use when someone asks for a diagram, a box-and-arrow picture of a system, a flowchart, or a figure for slides or docs, or when they share a .pdg file.

How it works

  1. When to use
  2. Setup
  3. Procedure
  4. Template
  5. The features people ask for most
  6. Pitfalls
  7. Verification
Original SKILL.md headings · 106 lines, 721 words
SKILL.md preview
---
name: predictygraph
description: Draw architecture diagrams, flowcharts and system maps as predictygraph (.pdg) files and render them to SVG or PNG. Use when someone asks for a diagram, a box-and-arrow picture of a system, a flowchart, or a figure for slides or docs, or when they share a .pdg file.
version: 0.2.3
license: Apache-2.0
metadata:
  hermes:
    tags: [diagrams, graphs, svg, architecture, flowchart, slides]
    category: creative
---

# predictygraph

predictygraph turns a short text file (`.pdg`) into an SVG or PNG diagram. Each group of
boxes picks its own layout, so changing one part of a diagram never reshuffles the rest.

## When to use

- Someone wants an architecture diagram, a flowchart, a request path, a layer stack or a
  module tree.
- Someone has a `.pdg` file and wants it rendered, changed or fixed.
- Someone wants a diagram for slides: decktile renders ` ```pdg ` blocks directly.

For sequence diagrams, Gantt charts or pie charts, use a different tool; predictygraph
has none of those.

## Setup

```bash
uv tool install "predictygraph[apng]"   # or: pipx install "predictygraph[apng]"
pdg --help
```

`[apng]` adds PNG output (it needs the cairo library, which Linux desktops and CI images
usually have). SVG output needs nothing extra.

## Procedure

1. **Sketch the structure first.** List the boxes, group them into panels (one panel per
   layer, team, machine or step), and decide each panel's direction: `layout=row`
   (left to right) or `layout=column` (top to bottom). Use `layout=layered` (the
   default when a group has edges inside it) for a flow where arrows decide the order.
2. **Write the file.** Start from the template below, or from the closest example in
   `references/examples.md`. The full syntax is in `references/syntax.md`.
3. **Check it:** `pdg diagram.pdg --check` reports syntax errors with line numbers.
4. **Render:** `pdg diagram.pdg -o diagram.svg`. For chat or email, a small PNG:
   `pdg diagram.pdg -o diagram.png --width 900 --colors 64` (about 30 KB).
5. **Look at the result** (open the PNG, or ask a vision model) and fix what is wrong;
   the pitfalls below cover the usual problems.

## Template

```pdg
graph layout=column align=stretch gap=12 theme=hami caption="What this diagram shows"

group front "Front end" layout=row gap=40 {
  web "Web app" sub="React"
  cdn "CDN" sub="static files" .blue
}
group back "Back end" layout=row gap=40 {
  api "API" sub="checks the token" .green
  worker "Worker" sub="sends e-mails" .green
}
group data "Data" layout=row {
  db "PostgreSQL" shape=cylinder align-x=api   # straight under the API
}

web -> cdn
web -> api "REST"
api -> worker "jobs"
api -> db "SQL"

legend .green "ours"
legend .blue "third party"
```

## The features people ask for most

- **Two lines in a box:** `api "API" sub="checks the token"`. The second line is
  smaller and grey.
- **Numbered steps:** `graph steps=auto` numbers every arrow in file order;
  `a -> b step=3` sets one by hand. Circles on short arrows sit beside the arrow, so
  don't shrink them or widen gaps by hand.
- **Equal-width layers / equal-height panels:** `align=stretch` on the parent.
- **Line up boxes in different panels:** `align-x=ID` centres a box (or a group) over
  another one, so the arrow between them is straight.
- **A note over several boxes:** `bracket a, d "note"` draws a curly bracket beside them.
- **Key and caption:** `legend .green "our services"`, `graph caption="..."`.
- **Panel title on the side:** CSS `group { label-position: left; }`.
- **A coloured strip on a box:** CSS `node.green { accent-bar: 4px var(--green); }`.
- **Themes:** `graph theme=nord` (list them with `pdg --list-themes`); `hami` gives the
  look of the HAMi docs.

## Pitfalls

- **An arrow cuts through a box:** pin its sides with `exit=left enter=left`; matching
  sides draw a C-shaped route around everything in between.
- **A label covers a box or is cut off:** labels on arrows inside a `layout=row`
  widen that gap automatically. Elsewhere, shorten the label or raise `gap=`.
- **Text spills out of boxes in someone else's viewer:** their computer drew the text in
  a wider font. Render with `--target web` for files you share; it sizes every box for
  the widest font in the list.
- **Edges are tangled:** split the diagram into more panels. Each panel lays out on its
  own, and arrows between panels route around them.
- **`align-x` didn't move a box all the way:** it only moves within its own panel's free
  space, never past the panel edge. Widen the panel (`align=stretch` on the parent) or
  add `gap=`.
- **Labels with `#`:** a `#` followed by a space starts a comment. Inside quotes it is
  fine: `"issue #42"`.

## Verification

- `pdg diagram.pdg --check` prints `ok`.
- The rendered picture has no text outside boxes, no arrow crossing a box, and every
  box the user asked for.
Files in this package (3)
  • SKILL.md 5 KB
  • references/examples.md 2 KB
  • references/syntax.md 3 KB

Versions

The database has no other skills named predictygraph.

Database snapshot: 13.11.2026 · package version 43447639a1a5 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100anthropic-style-diagram
    Draw architecture, flow and structural diagrams in the Anthropic/Claude visual language as SVG, then render and save them as PNG. Trigger ONLY when the user names that visual language — 'Anthropic 风格架构图', 'Claude 风格流程图', 'Anthropic style diagram', 'Claude style flowchart',…
  • 100svg-figure
    This skill should be used when the user asks to "create an SVG figure", "make a schematic", "draw a diagram", "create a schematic diagram", "draw a flowchart", "draw a process flow", "draw a workflow", "draw a workflow diagram", "make an SVG schematic", "create a process…
  • 100mermaid
    Mermaid turns short text definitions into diagrams (flowcharts, sequence, ER, class, state, Gantt, C4 and architecture diagrams) that render in Markdown on GitHub, GitLab and docs sites. Use when a user asks to "draw a flowchart", "make a sequence diagram", "generate an ER…
  • 95excalidraw-diagram-generator
    Generate Excalidraw diagrams from natural language descriptions. Use when asked to "create a diagram", "make a flowchart", "visualize a process", "draw a system architecture", "create a mind map", or "generate an Excalidraw file". Supports flowcharts, relationship diagrams, mind…
  • 98drawio
    Always use when user asks to create, generate, draw, or design a diagram, flowchart, architecture diagram, ER diagram, sequence diagram, class diagram, network diagram, mockup, wireframe, or UI sketch, or mentions draw.io, drawio, drawoi, .drawio files, or diagram export to…
  • 95excalidraw-diagram-generator
    Generate Excalidraw diagrams from natural language descriptions. Use when asked to "create a diagram", "make a flowchart", "visualize a process", "draw a system architecture", "create a mind map", or "generate an Excalidraw file". Supports flowcharts, relationship diagrams, mind…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.