Skills · Documents

DocumentsSkillDugout-created

/diagrams-from-spec

Generates architecture and flow diagrams from a spec file you commit, so fixing a diagram is a one-line edit, not redrawing boxes.

Created by Piyush Baheti · Source: piyush-tkd/skillsdugout/tree/main/plugins/diagrams-from-spec

Who it is for

Engineers who keep architecture or flow diagrams in docs or a web app and want them to stay accurate.

House rules built on Archify, written after several hand-drawn diagrams quietly went out of date.

When to use it

  • Adding a diagram to documentation or a page.
  • A diagram has gone stale after a code change.
  • A diagram is too tall, cramped or hard to read.

Example

You ask

Draw the architecture of our online shop: browser, web app, shop-api, Postgres, and the two third parties, Stripe and Postmark, inside a boundary.

It writes a diagram from a committed spec

Architecture diagram: Browser to Web app to shop-api; shop-api to Postgres below, and to Stripe and Postmark inside a dashed Third parties boundary.

Sample run on 2026-10-03 with Archify 3.0.1 and illustrative data. Passed showcase validation with no errors or warnings.

Evidence

Our test

No baseline test yet. We will publish one, with and without the skill, when testing is done.

Reported by the community, by app

Claude Code: Tested
No outcomes reported yet
Claude apps: Not tested
No outcomes reported yet
Cursor: Not tested
No outcomes reported yet
Codex: Not tested
No outcomes reported yet
GitHub Copilot: Not tested
No outcomes reported yet

Compatibility labels come from our tests only. Community reports add detail but cannot mark an app as tested.

Editorial assessment · not a community rating

Editorial review in progress

We have not finished testing this listing against doing the task without it. The verdict appears here when we have. Our team made this skill; it gets the same test as external work.

How we review

Setup and customization

  • Requires Archify (MIT, github.com/tt-a1i/archify). The skill checks for it and gives the install commands.
  • Needs Node.js.

What it can access

Reads
The diagram spec and the code or docs it describes
Changes
Writes the spec, the generated diagram and a sources note in your docs folder

Install

Claude Code: Tested
  1. Add the Skills Dugout marketplace once.
    /plugin marketplace add piyush-tkd/skillsdugout
  2. Install /diagrams-from-spec.
    /plugin install diagrams-from-spec@skillsdugout
  3. Start a new session and ask for it, for example "draw the architecture of this service as a diagram".

Community reviews

No reviews yet. Be the first to rate it after you try it.

Each review records the app, version, task and outcome; those outcomes feed the Evidence section. One rating per person; creators reply but cannot rate their own work.

No reviews yet. Be the first to rate it after you try it.

Source, license and versions

Source
github.com/piyush-tkd/skillsdugout/tree/main/plugins/diagrams-from-spec
License
MIT, as stated in the repository
  • 0.1.0 · 2026-10-03 · First release.
Show the full skill instructions

Diagrams from a spec

Every diagram is generated by Archify (MIT) from a committed JSON specification. This file is a house style on top of it. Archify's own SKILL.md remains the reference for its schema and commands — read it for anything this file does not cover.

The rule underneath all of it: a diagram is documentation, and documentation is only worth having if it is true. A stale picture is read as fact faster than stale prose, because nobody proofreads a picture. Generating from a spec is what makes a correction an edit to a sentence rather than a nudge to a rectangle.

The file has two kinds of rule:

  • General rules (sections 0, 1 and 3–7) apply to any diagram generated from a spec.
  • House defaults (section 2) are presentation choices. Keep them for consistency across one site; change them deliberately if your pages need something else.

Figures marked "at 3.0.1" were checked against Archify 3.0.1 on 2026-10-03. Trust the installed version's own diagnostics over them.


0. Make sure Archify is available

Use the repository's own copy first, so everyone generates with the same version. Look in this order and use the first hit:

<repo>/tools/archify/bin/archify.mjs
~/.agents/skills/archify/bin/archify.mjs
~/.claude/skills/archify/bin/archify.mjs

Confirm it works and check the version:

node <path>/bin/archify.mjs doctor
node -e "console.log(require('<path>/package.json').version)"

If it is missing, install it. This is a git clone of an MIT-licensed repository — no sudo, no PATH change, no package manager, and deleting the folder undoes it. Run it when the session's permission mode allows; when it does not, print the commands and stop.

# The current stable ref comes from the project's own release manifest.
curl -s https://tt-a1i.github.io/archify/skill-updates/archify/stable.json
# → { "source": { "repository": "...", "ref": "v3.0.1" }, ... }

git clone --depth 1 --branch <ref> https://github.com/tt-a1i/archify /tmp/archify-src
mkdir -p <repo>/tools
cp -R /tmp/archify-src/archify <repo>/tools/archify
node <repo>/tools/archify/bin/archify.mjs doctor

The skill is the archify/ subdirectory of the repository, not its root. Pointing at the root fails with Cannot find module. The repository also carries benchmarks, docs and experiments, which is why the copy above takes only what is needed. Archify has no runtime dependencies; there is nothing to npm install.


1. Where the files go

<docs-or-public-folder>/diagrams/<topic>/<name>.json         the specification — edit THIS
<docs-or-public-folder>/diagrams/<topic>/<name>.html         generated — never hand-edit
<docs-or-public-folder>/diagrams/<topic>/<name>.delivery.json  generated receipt — keep out of the published site
<docs-or-public-folder>/diagrams/<topic>/<name>.sources.md   where the example values came from

Commit them side by side, so a picture can be regenerated by whoever finds it wrong. deliver overwrites the .html; anything typed into it by hand is gone at the next run.

Keep the caption and title with the page's other content, not hard-coded in the component that embeds the diagram. If the sources.md would sit in a published folder, move it next to the page's source instead.


2. House defaults

Layout:

  1. Let Archify size the canvas. Archify's own guidance is to omit meta.viewBox for a fresh architecture diagram so it measures the height it needs. Set one only to match a fixed frame, and then lay nodes out to fill it — a fixed box around a small diagram leaves empty bands.
  2. Keep the width readable. The showcase desktop-readability check sets the limit. At 3.0.1 it is the 930px desktop budget scaled by your smallest text: about 1085 wide with 7px labels, 1240 with 8px. Read the diagnostic rather than relying on a fixed number.
  3. Widen and flatten rather than stack. A column of nodes is what produces a diagram taller than the screen. Empty grid cells are routing corridors, not wasted space — a node with more than four partners needs one.

Style:

  1. No cards. The surrounding page should carry that content, where it gets corrected.
  2. Omit meta.visual_preset so every diagram opens in the same default style.
  3. meta.quality_profile: "showcase", always.

3. Authoring rules

  1. Prefer a boundary to an ordering when the point is trust or ownership. architecture can draw a security-group around a third party; sequence cannot, and "where does our data go" should be visible rather than inferred from which lifeline an arrow lands on.
  2. A node's label must clear its own icon. The icon sits top-left and the label is centred, so a label filling the node collides with it. It can pass every check and still look broken. Shorten the label and put the full name in the sublabel.
  3. A crossing is a layout problem, not a routing problem. When composition/proper-crossing fires, routing hints tend to fail in turn. Move a lane or a column instead — for example, put a shared sink lane between the two lanes that write to it.

If the diagram is a workflow

  1. schema_version: 2, not 1. At 3.0.1, version 1 still pins a legacy fixed grid and rejects ordinary node widths with a column-capacity error; version 2 computes lanes from node widths. (Other diagram types, such as architecture, accept only version 1.)
  2. Width and height come from the content, not meta.viewBox. To narrow the diagram, trim node widths and shorten labels. Check the delivered viewBox after every run.
  3. The canvas has fixed empty margins above the lanes and below the legend, which meta.viewBox cannot crop. Handle them in the embed step (section 5), never by editing the generated file.

4. Validate, then deliver

Check Archify's own SKILL.md for the preferred command. At 3.0.1 a single finalize run does validate, deliver, check and browser-check together; the separate steps still work:

node <archify>/bin/archify.mjs validate <type> <spec>.json --quality showcase --json
node <archify>/bin/archify.mjs deliver  <type> <spec>.json <out>.html --quality showcase --json
  • A pass means 0 composition errors and 0 warnings under the showcase profile. Check that the output names the showcase profile — at 3.0.1 the standard and showcase profiles run the same artifact checks, so the check count does not tell them apart.
  • deliver refuses to write unless it passes. That refusal is the feature.
  • On a diagnostic, apply one fix at a time, taken from the diagnostic's own supportedFixes or its suggested labelAt / labelDy. Do not add routing hints before something asks for one.
  • A relationship label is data. When one collides, move it, then re-route, then shorten the wording — deleting it is not a geometry fix.
  • visual-check <out>.html --json --out-dir <somewhere-unpublished> gives browser evidence and writes screenshots. Look at them. It needs a browser: if it reports "skipped", set ARCHIFY_CHROME to a Chrome or Chromium binary. Always pass an --out-dir outside the published folder, or the screenshots ship with the site.

5. Embedding

Use one shared component or include for every diagram rather than a fresh iframe each time. It owns every change between the generated file and the page, so the generated file stays untouched and the result is the same on every build:

  1. Fixed-height frame, content scaled into it — never size the frame from the diagram.
  2. Crop at display time. After the iframe loads, set the SVG's viewBox to its content bounds and give it both width and height, so it scales instead of cropping. The .html on disk is not modified.
  3. Make the frame a still picture. ?embed=1 hides the toolbar but leaves click handlers live, which strands people in a zoom with no way back. Disable pointer events on the frame.
  4. Interaction is a link above the picture, opening the full viewer. Use a real <a>, not a button calling window.open, so middle-click, cmd-click and "copy link address" keep working.
  5. Give the iframe a descriptive title — that is its accessible name. Add a prose caption under it describing the whole picture; it is what sighted readers skim and the fuller description a screen-reader user can reach.
  6. Load the iframe with loading="lazy". At 3.0.1 each generated .html is around 750KB because the viewer inlines its runtime; lazy loading keeps that off the page until it is scrolled to.
  7. Match the host theme if the page has one. At 3.0.1 the viewer reads a ?theme= query parameter; the embed component can pass the page's current theme. Otherwise the viewer uses its own light/dark control.

6. Content rules

  1. Prefer values from the real system — query the database, read the code, probe the API.
  2. Label anything illustrative as illustrative, in the caption or the node. Never use an invented value that looks real: an id made up for a design document, copied into a diagram, gets read as fact for months. Do not put real customer or record ids in a diagram that others will see.
  3. Distinguish what exists from what is proposed. A planned service drawn like a running one is a stale diagram on the day it is published.
  4. Record where example values came from — the query, the file, the endpoint — in the sources.md, not in the diagram or caption. The next person refreshes them instead of inventing replacements.
  5. Preserve exact identifiers — service names, endpoints, table and column names, env vars. Shorten a node's label if you must and put the exact name in its sublabel.
  6. When a diagram becomes wrong, the diagram is part of the change, in the same commit as the code that made it wrong.

7. Finishing

  • Add a changelog entry only if the diagram changes what users of the page see or rely on.
  • Update the nearest CLAUDE.md if the change alters how diagrams are built.
  • Run the project's normal build, not a bare bundler command, so any checks it runs still apply.