Skip to content
Skills Library
Programming · Building & coding

linework

/linework

Draw software diagrams (architecture, system design, data flow, flowcharts, state machines, sequence diagrams, ER and database schemas, class diagrams, timelines) as .drawio.svg files that render in Markdown, HTML and GitHub and that people can edit by hand in draw.io. Use whenever a design doc, README, ADR, wiki page or PR needs a diagram, when asked to draw, visualize or diagram a system, when converting a Mermaid diagram, or when changing an existing .drawio.svg. Use it instead of writing Mermaid, PlantUML or ASCII art unless the user asks for one of those.

Repository
linework ↗
Licence
MIT
Last repository change
10.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
20
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

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

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Draw software diagrams (architecture, system design, data flow, flowcharts, state machines, sequence diagrams, ER and database schemas, class diagrams, timelines) as .drawio.svg files that render in Markdown, HTML and GitHub and that people can edit by hand in draw.io. Use whenever a design doc, README, ADR, wiki page or PR needs a diagram, when asked to draw, visualize or diagram a system, when converting a Mermaid diagram, or when changing an existing .drawio.svg. Use it instead of writing Mermaid, PlantUML or ASCII art unless the user asks for one of those.

Original author description

Draw software diagrams (architecture, system design, data flow, flowcharts, state machines, sequence diagrams, ER and database schemas, class diagrams, timelines) as .drawio.svg files that render in Markdown, HTML and GitHub and that people can edit by hand in draw.io. Use whenever a design doc, README, ADR, wiki page or PR needs a diagram, when asked to draw, visualize or diagram a system, when converting a Mermaid diagram, or when changing an existing .drawio.svg. Use it instead of writing Mermaid, PlantUML or ASCII art unless the user asks for one of those.

How it works

  1. New diagram
  2. Changing a diagram
  3. Spec
  4. More
Original SKILL.md headings · 97 lines, 1,105 words
SKILL.md preview
---
name: linework
description: Draw software diagrams (architecture, system design, data flow, flowcharts, state machines, sequence diagrams, ER and database schemas, class diagrams, timelines) as .drawio.svg files that render in Markdown, HTML and GitHub and that people can edit by hand in draw.io. Use whenever a design doc, README, ADR, wiki page or PR needs a diagram, when asked to draw, visualize or diagram a system, when converting a Mermaid diagram, or when changing an existing .drawio.svg. Use it instead of writing Mermaid, PlantUML or ASCII art unless the user asks for one of those.
compatibility: Needs Node 20+, a Chromium-based browser (Chrome, Edge, or Playwright's Chromium via `linework install-browser`) and network access to fetch the package with npx.
---

# Linework

You describe the diagram as a small YAML spec. Linework does the layout, styling and rendering, and writes a `.drawio.svg`: a normal SVG for docs with the editable draw.io model inside it. Never write coordinates, SVG or draw.io XML yourself, and don't fall back to Mermaid, PlantUML or ASCII art unless the user asks for one.

`linework` below means `npx -y @itsthecsguy/linework` (plain `linework` if it's on the PATH). Keep specs and preview PNGs in your temp directory, not in the repo. If a command fails to download, find a browser or accept an option this guide names, read `references/troubleshooting.md`.

## New diagram

1. **Look for existing diagrams.** Search for `*.drawio.svg`. If one already shows what you need, change it (next section). Save new ones where the others live, else `docs/diagrams/`.
2. **Pick the type.** One diagram makes one point.
   - `architecture`: components and how they talk.
   - `flow`: a process with steps and decisions.
   - `state`: the lifecycle of one thing.
   - `sequence`: who calls whom, in order, for one scenario.
   - `er`: tables, columns and relationships.
3. **Write the spec**, starting from the closest file in `examples/` next to this guide: `checkout.yaml` and `platform.yaml` (architecture), `serverless-aws.yaml`, `orders-azure.yaml` and `gcp-ingest.yaml` (cloud icons), `refund-flow.yaml` and `deploy-flow.yaml` (flow), `payment-state.yaml` and `job-state.yaml` (state), `pay-sequence.yaml` and `auth-seq.yaml` (sequence), `billing-er.yaml` and `shop-er.yaml` (ER), `billing-class.yaml` (class), `launch-timeline.yaml` (timeline). A Mermaid block converts directly: `linework import doc.md --block 1 -o out.drawio.svg`.
4. **Build:** `linework build /tmp/spec.yaml -o docs/diagrams/checkout.drawio.svg --png /tmp/checkout.png`
5. **Read the output.** `spec error` lines say exactly what to fix. `check:` lists layout problems. Fix every error and the warnings that matter, then rebuild. Look at the PNG if you can view images.
6. **Embed the `.drawio.svg`**, never the PNG: `![Checkout API charges cards through Stripe and writes orders to Postgres](diagrams/checkout.drawio.svg)`. Write alt text that says what the diagram shows in one sentence.
7. **Tell the user** where the file is and that they can edit it by hand in draw.io (`linework edit <file>` opens it in their browser).

## Changing a diagram

The `.drawio.svg` is the source of truth. Every command below keeps what is already there in place, including boxes someone moved by hand in draw.io. Only what you change moves.

For one or two changes, edit the file directly:

```bash
linework set d.drawio.svg api.label="Checkout API v2" api.highlight=true   # id.field=value; empty value clears; also theme= accent= title= direction=
linework add d.drawio.svg "fraud: { label: Fraud check, in: vpc }" "api -> fraud: score"
linework rm  d.drawio.svg cache "api -> stripe"                              # a box goes with its edges
```

For a larger change, round-trip the spec. Always start from the file, never from an old copy of the spec:

```bash
linework show d.drawio.svg > /tmp/spec.yaml    # current spec, hand edits included
# edit it; keep the "# linework-base:" line at the top
linework build /tmp/spec.yaml -o d.drawio.svg --png /tmp/d.png
```

- The `merged into the existing layout:` line says what was kept, placed, grown and rerouted. Pass it on to the user.
- If the user moved boxes by hand and left lines or labels in odd places, `linework tidy d.drawio.svg` reroutes those edges and re-places those labels. Boxes stay put.
- `--relayout` throws the layout away and starts over. Use it only if the user asks: it undoes their work.
- When the user says they finished editing in draw.io, run `show` and carry on from its output.

## Spec

```yaml
type: architecture            # architecture | flow | state | sequence | er | class | timeline
title: Checkout               # optional
direction: auto               # auto (default) | TB | LR | BT | RL
theme: clean                  # clean (default) | soft | paper | dark | midnight | mono | bold | sketch | blueprint | c4
accent: "#E11D48"             # optional: the highlight color, a name or a quoted hex
groups:                       # optional boxes around nodes; nest with `in`
  vpc: { label: Production VPC }
nodes:                        # id: { label, kind, tech, in }, all optional
  web:    { label: Web app, kind: client, tech: Next.js }
  api:    { label: Checkout API, tech: Go, in: vpc, highlight: true }
  queue:  { label: order-events, kind: queue, tech: Kafka, in: vpc }
  db:     { label: Orders, kind: database, tech: Postgres, in: vpc }
  stripe: { kind: external }   # label defaults to "Stripe"
edges:                        # "from ARROW to: label"
  - web ==> api: HTTPS         # ==> highlighted: the path the doc is about
  - api -> db: SQL
  - api -.-> queue: OrderPlaced # -.-> async or event, dashed
  - api -> stripe: charge
```

- Arrows: `->` call or flow, `==>` highlighted, `-.->` async, `<->` two-way, `--` no arrowhead. Spaces around the arrow. Quote an edge whose label contains `: ` or `#`.
- List nodes and edges in reading order. Layout follows it, and an edge that points back at an earlier node is drawn as the loop.
- `tech` is the quiet second line: the technology, not a description.
- Color is for meaning. `highlight: true` or `==>` marks the one path the text is about. `color: red|green|blue|...` marks a category; say what it means in the doc.
- Cloud icons on architecture nodes: `icon: aws.lambda`, `gcp.cloud_run`, `azure.functions`, `k8s.pod`. Search with `linework icons aws lambda`.

| type | kinds (default first) |
|---|---|
| architecture | `service`, `person`, `client`, `function`, `database`, `cache`, `storage`, `queue`, `external` |
| flow | `step`, `decision`, `terminal`, `data`, `error` |
| state | `state`, `success`, `error`; start and end are `"[*] -> first"` and `"last -> [*]"`, quoted |
| sequence | `participants:` and `messages:` instead of nodes and edges; `-->` is a reply |
| er | `fields:` on nodes (`- id: uuid pk`), crow's-foot edges (`users }o--|| orgs: belongs to`) |
| class | `members:` (`- "+ total(): Money"`), UML edges (`Animal <|-- Duck`, `Order *-- Line`) |
| timeline | `start:`/`end:` dates, `at:` on a `milestone`; groups are lanes; no edges |

In a flow, keep decision text to a short question and label every edge leaving it (`window -> refund: "yes"`).

## More

- `references/spec.md`: every option, sequence blocks (`alt`, `loop`, notes), ER, class, timeline, themes, colors.
- `references/style-guide.md`: what makes a diagram read well. Read it before anything non-trivial.
- `references/troubleshooting.md`: download, browser and sandbox failures.
- `references/google-docs.md`: putting a diagram in Google Docs with `linework publish`.
- Excalidraw: `linework render d.drawio.svg -o d.excalidraw` writes an editable copy; `linework import d.excalidraw -o d.drawio.svg` merges edits. `linework share` uploads it: only if asked.
- `linework help` lists every command, including `check`, `sync` (rebuild diagrams whose YAML changed), `kinds`, `schema` and `git-setup` (readable `git diff` for diagrams).
Files in this package (20)
  • SKILL.md 8 KB
  • examples/auth-seq.yaml 1 KB
  • examples/billing-class.yaml 1 KB
  • examples/billing-er.yaml 1 KB
  • examples/checkout.yaml 1 KB
  • examples/deploy-flow.yaml 1 KB
  • examples/gcp-ingest.yaml 1 KB
  • examples/job-state.yaml 1 KB
  • examples/launch-timeline.yaml 1 KB
  • examples/orders-azure.yaml 1 KB
  • examples/pay-sequence.yaml 1 KB
  • examples/payment-state.yaml 1 KB
  • examples/platform.yaml 2 KB
  • examples/refund-flow.yaml 1 KB
  • examples/serverless-aws.yaml 1 KB
  • examples/shop-er.yaml 1 KB
  • references/google-docs.md 3 KB
  • references/spec.md 15 KB
  • references/style-guide.md 5 KB
  • references/troubleshooting.md 1 KB

Versions

The database has no other skills named linework.

Database snapshot: 13.11.2026 · package version bebaa5a6dacd (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

  • 90drawio-diagrams
    Create, edit, review, or export editable draw.io diagrams. Use when the user needs .drawio architecture, flow, sequence, network, or other technical diagrams; not data plots or artistic images.
  • 100html-svg-diagrams
    Create SVG-based technical diagrams inside HTML — flowcharts, sequence diagrams, state machines, data-flow diagrams, dependency graphs, request/response timelines. Use whenever the user wants to visualize, illustrate, diagram, or sketch a technical concept, system, or process.…
  • 100draw-io
    Create and edit draw.io diagrams (.drawio files). Use when user asks to "create a diagram", "edit drawio", mentions .drawio files, wants AWS architecture diagrams, or needs to convert diagrams to PNG. Triggers on "drawio", "draw.io", ".drawio", "diagram xml".
  • 100diagram
    Create an editable draw.io diagram from a plain description. Writes a .drawio file, or a .drawio.svg when the diagram belongs in a repo next to its docs. Covers flowcharts, architecture, sequence, swimlane, ER and org diagrams. Use when the user asks for a diagram they can edit…
  • 100draw-io-diagram-generator
    Use when creating, editing, or generating draw.io diagram files (.drawio, .drawio.svg, .drawio.png). Covers mxGraph XML authoring, shape libraries, style strings, flowcharts, system architecture, sequence diagrams, ER diagrams, UML class diagrams, network topology, layout…
  • 100drawio-diagrams
    Use when the user wants a diagram: UML, ER, network topology, data flow, a flowchart, or an architecture or system diagram, or a picture to clarify a system with 3+ parts. It makes editable draw.io XML, lints it, delivers a local SVG. Excalidraw suits casual sketches; mermaid, diagrams-as-code.

Feedback and reports

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