agentleFS
Venkateshvenki404224Venkateshvenki404224/shipcraft-skills/skills/excalidraw-architecture/SKILL.md

excalidraw-architecture

Skill2 starsChanged 3 days agoMITView on GitHub

Design architecture before building it, as Excalidraw diagrams generated from code, rendered locally with the Excalidraw npm package to PNG, attached to the plan.md or design doc, and reviewed until every review lens approves. Use this whenever a plan, feature request, PRD or "how are we going to build X" needs a picture — current integrations, a target flow, a sync contract, data models and their links, a UI wireframe, a roadmap, or a full numbered "architecture pack" — and whenever the user says draw, diagram, sketch, map, wireframe, architect, Excalidraw, draw.io or Figma-style design doc, or wants to "see it" rather than read it. Also use it to revise a diagram made earlier with this skill or to share one as a live Excalidraw room.

  • Reads credentials

2 other projects use a version of this.

Adopted by

Most recently taken up by

  • Other versions2 projects use a version of this.

    Word for word · 0

    None found.

    Edited · 0

    None found.

    Wrote their own version · 2

    1. mergisi/awesome-openclaw-agents★ 4.1ksame name
    2. cubxxw/agent-kit★ 2same name

    How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.

  • In this repository9 other files it gives its agents.

The file

We split this skill into the rules it gives an agent

6 rules. About 0 are common, 2 are distinctive, and 4 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈2

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 4

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Write the builder in docs/architecture/_build/<name>.py (next to the output, so the diagram stays editable — edit the script, never the …

    line 35
  2. Very specific:

    Put the PNG(s) and the .excalidraw under docs/architecture/, and in the plan.md / design doc:

    line 81
  3. Distinctive:

    Check every code claim in the design yourself: file paths, lines, functions and framework behaviour.

    line 98
  4. Distinctive:

    Write yes/no questions for three lenses: seams & reuse, failure & scale, data & privacy.

    line 100
  5. Very specific:

    Run scripts/jev_review.py.

    line 102
  6. Very specific:

    If the user wants a link for people outside the repo, scripts/render.sh + scripts/publish_room.sh load the scene into a hosted Excalidraw …

    line 111

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Excalidraw architecture diagrams

A design that exists only as prose gets agreed by nobody. This skill makes the picture, puts it in the plan, and has reviewers argue with it while it is still cheap to change. Scenes are generated from a small Python builder (hand-placing hundreds of elements is slow and inconsistent), rendered by a local copy of Excalidraw (text widths, arrow crossings and library quirks are only visible once drawn), and attached as PNG + source to the document that will drive implementation.

1. Decide the shape

  • One diagram — a flow, an integration map, one ER view: title + subtitle, 2–5 colour zones left→right, cards carrying real file paths in grey, numbered badges on the steps we own.
  • Architecture pack — the user wants to design before building, or present to a senior: a cover with roadmap and contents, then numbered chapters 01 Today → 02 Target → 03 System design → 04 Under load → 05 Data model → 06 UI. references/architecture-pack.md says what each holds. Include only chapters the subject needs.

Ground every box in the code first: grep the modules, read the hooks, name the files. The small grey file paths are what make reviewers trust the picture.

2. Build the scene

S below is this skill's scripts/ folder (the directory this SKILL.md was loaded from, plus /scripts).

python3 $S/fetch_libraries.py            # once per machine: public icon/wireframe libraries

Write the builder in docs/architecture/_build/<name>.py (next to the output, so the diagram stays editable — edit the script, never the JSON) with from excalidraw_builder import * (references/example-builder.md):

NeedCall
swimlane / columnzone(x, y, w, h, title, colour)
box with title / body / file pathcard(x, y, w, h, title, body, code, colour, art=(lib, item))
numbered stepbadge(x, y, n) half outside the card's top-left
flow between cardsconnect(a, b, colour, label) or arrow(a, b, colour, point(a,"bottom"), point(b,"top"))
column of stepschain([c1, c2, c3], colour)
data modeler_card(x, y, w, fields, title, colour, key_fields)
document chapterschapter("03", "System design", title_y - 44)
wireframeframe(...) + icon("lofi","18",…,keep_text=False) + icon("ux",…) + icon("dash",…)
status / statepill(x, y, "Live", "green")

Colour language, kept consistent across chapters: green = data coming in / the customer's side, blue = exists in our system, red = new to build, purple = outside company, orange = third parties, decisions, open questions, grey = supporting. Icons come from public libraries (references/libraries.md); pass keep_text=False on wireframe and chart items so their sample labels do not fight yours.

save(path) writes docs/architecture/<name>.excalidraw, prints element count + bounds, and prints LINT lines for text that overlaps other text or spills out of its card. Fix every LINT line before rendering; they are the collisions a reviewer would otherwise spot in the PNG.

3. Render locally, look, fix

$S/render_local.sh docs/architecture/<name>.excalidraw docs/architecture/<name>.png 2     # full canvas
$S/export_chapters.py docs/architecture/<name>.excalidraw docs/architecture 2           # one PNG per chapter

export_chapters.py cuts at the dashed separators above each chapter and names files by the chapter pills (<name>-01.png, <name>-02.png …). Re-run both commands after the last change so no PNG in the plan is stale.

The first run installs @excalidraw/excalidraw from npm and bundles it (network once); after that it is offline on 127.0.0.1:7331 (EXCALIDRAW_LOCAL_PORT to change it). The scripts drive the page with agent-browser (AGENT_BROWSER to override). Open the PNG with Read and inspect it. The recurring faults and their fixes are in references/layout-rules.md: arrows through cards, clipped titles, labels inside cards, emoji boxes. Fix the builder, rebuild, re-render — two or three cycles is normal. Set EXCALIDRAW_SESSION=<name> when several diagram jobs may run at once.

4. Attach to the plan

Put the PNG(s) and the .excalidraw under docs/architecture/, and in the plan.md / design doc:

## Architecture
![Target architecture](docs/architecture/<name>-02-target.png)
Source: docs/architecture/<name>.excalidraw · builder: docs/architecture/_build/<name>.py

One PNG per chapter the plan refers to; the full-canvas export is for the appendix.

5. Review before anyone builds

An explanatory diagram of something that already exists needs no review. When the diagram is part of a plan or feature request, run the review loop in references/architecture-review.md. It runs in this session, with TypeSafe Jev as the checker when TYPESAFE_API_KEY is set. Do not spawn reviewer agents.

  1. Check every code claim in the design yourself: file paths, lines, functions and framework behaviour.
  2. Write yes/no questions for three lenses: seams & reuse, failure & scale, data & privacy. Use the standing checklist, the design's own promises, and every earlier finding.
  3. Run scripts/jev_review.py. Fix every fail, and check every unsure point in the code yourself.
  4. Repeat until all three lenses approve.

Record the verdict table and the list of checked code claims in the plan. A plan without three approvals is not ready to implement. Never send personal or customer data to an external reviewer. Spawn reviewer agents only when the user asks for a deep code review.

6. Share (optional)

If the user wants a link for people outside the repo, scripts/render.sh + scripts/publish_room.sh load the scene into a hosted Excalidraw ($EXCALIDRAW_SITE, default excalidraw.com, or a self-hosted copy) and start a live room. Every publish is a new URL; collaboration runs through Excalidraw's public servers — fine for architecture, never for personal or customer data.

7. Report

Room link if any, repo paths, the review table, the code claims you checked, and a short reading guide. Say what you could not verify. Files stay uncommitted unless asked.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.