Community画像github.com

vsdx-diagram

Use when the user asks for an architecture diagram, microservice topology, business flowchart, swimlane, or network topology that must be delivered as a real editable Microsoft Visio (.vsdx) file, or when an existing .vsdx must be read, modified incrementally, re-rendered, or validated without having Visio installed. Use when the user says "draw an architecture diagram", "generate a Visio file", "edit this diagram", or "rename this service", or asks for VSDX/PNG/SVG diagram output. Covers node/edge design, layered layout, connector routing, preview-based visual iteration, and round-trip-safe edits.

vsdx-diagram とは?

vsdx-diagram is a Claude Code agent skill that use when the user asks for an architecture diagram, microservice topology, business flowchart, swimlane, or network topology that must be delivered as a real editable Microsoft Visio (.vsdx) file, or when an existing .vsdx must be read, modified incrementally, re-rendered, or validated without having Visio installed. Use when the user says "draw an architecture diagram", "generate a Visio file", "edit this diagram", or "rename this service", or asks for VSDX/PNG/SVG diagram output. Covers node/edge design, layered layout, connector routing, preview-based visual iteration, and round-trip-safe edits.

対応~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/randomgitsrc/vsdx-engine/tree/HEAD/skill

Installed? Explore more 画像 skills: steipete/songsee, affaan-m/frontend-design, mattpocock/improve-codebase-architecture · View all 6 →

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

VSDX Diagram Skill

Produce and maintain real Microsoft Visio files through the vsdx-tool CLI, without Microsoft Visio installed. The engine writes genuine OPC/VSDX packages and renders PNG/SVG from those packages.

This skill is about designing and iterating the diagram. The tool does the file work. Never hand-write VSDX XML, and never deliver an SVG or PNG with a .vsdx extension.


0. Prerequisites

vsdx-tool version --json     # confirm the tool runs

If that fails, install per docs/installation.md (requires .NET 8). Then confirm the workspace is writable and that a CJK font exists when the diagram contains Chinese:

fc-list :lang=zh | head -3

1. Decide the diagram family first

Do not draw every system the same way. Pick the family from what the user is describing:

User is describingFamilyLayout shapeNode vocabulary
System internals, layers, tiersarchitectureHorizontal bands (access / service / data)Boxes, hexagons for gateways
Service-to-service calls, event flowsmicroservicesLeft-to-right pipeline + message bus columnRounded boxes, parallelogram for queues
A process with branches and actorsworkflowTop-to-bottom or swimlaneCircles for start/end, diamonds for decisions
Machines, zones, trust boundariesnetworkZones as nested regionsHexagons for firewalls, cylinders for stores

Ask the user only when the intent is genuinely ambiguous. Otherwise choose and state your choice in one line.


2. Design the structure before writing JSON

Work in this order. Skipping step 2 is the most common cause of an ugly result.

  1. List the nodes. Give each a stable kebab-case id (query-service, postgresql). Keep ids stable forever — renames happen on text, not id, when the thing is the same.
  2. Assign each node to a band and a column. Draw the grid on paper first: band = row semantics, column = left-to-right order in the flow.
  3. Order the pipeline so neighbours are adjacent. If A calls B calls C, put them in consecutive columns. A connector between columns 1 and 5 will cross everything between.
  4. Put each data store directly under the service that owns it. Then the edge is a clean vertical.
  5. Only then write coordinates. Use a fixed column table and reuse it.

Column grid template

COL  = {1: 2.60, 2: 5.50, 3: 8.40, 4: 11.30, 5: 14.20, 6: 17.10}
BAND = {"access": 9.70, "service": 6.45, "data": 3.30}
W, H = 2.20, 1.00          # node size; keep constant within a band

Coordinates are centres in inches, origin at the page's bottom-left, so larger y is higher on the page.

Node vocabulary

shape accepts Visio master names or these aliases:

rounded, rectangle, process, circle, ellipse, square, diamond, decision, data, hexagon, parallelogram, trapezoid, pentagon, triangle, text, container, cloud, database, queue, firewall, gateway

Use shape semantically: gateway → hexagon, queue/bus → parallelogram, decision → diamond, actor → circle, store → process or data. Two or more distinct families per diagram is expected; one family for everything looks like a checklist.


3. Write the model

Minimal but complete example:

{
  "id": "order-platform",
  "name": "订单平台架构图",
  "type": "architecture",
  "pageSize": { "width": 18.0, "height": 11.0, "unit": "inches" },
  "background": "#FFFFFF",
  "style": { "font": "Microsoft YaHei", "fontSize": 11 },
  "pages": [{
    "id": "page-0",
    "name": "Architecture",
    "size": { "width": 18.0, "height": 11.0, "unit": "inches" },
    "groups": [
      { "id": "grp_svc", "name": "服务层  Service Layer", "kind": "container",
        "autoSize": true,
        "style": { "fill": "#EDF7ED", "stroke": "#A9D08E", "textColor": "#375623",
                   "bold": true, "hAlign": "left" } }
    ],
    "nodes": [
      { "id": "api", "text": "API 网关\nKong", "shape": "hexagon",
        "bounds": { "x": 5.50, "y": 9.70, "w": 2.40, "h": 1.00 },
        "groupId": "grp_svc",
        "style": { "fill": "#F2B705", "stroke": "#BF8F00", "textColor": "#3F2E00",
                   "fontSize": 11, "bold": true },
        "shapeData": { "owner": "platform-team", "sla": "99.95%" } },
      { "id": "orders", "text": "订单服务\nOrder Service", "shape": "rounded",
        "bounds": { "x": 5.50, "y": 6.45, "w": 2.20, "h": 1.00 },
        "groupId": "grp_svc",
        "style": { "fill": "#70AD47", "textColor": "#FFFFFF", "bold": true } },
      { "id": "db", "text": "PostgreSQL", "shape": "process",
        "bounds": { "x": 5.50, "y": 3.30, "w": 2.20, "h": 1.10 },
        "style": { "fill": "#C55A11", "textColor": "#FFFFFF" } }
    ],
    "edges": [
      { "id": "e-api-orders", "from": "api", "to": "orders", "kind": "straight",
        "label": "REST", "endArrow": "triangle", "lineColor": "#507E32" },
      { "id": "e-orders-db", "from": "orders", "to": "db", "kind": "straight",
        "label": "SQL", "endArrow": "triangle", "lineColor": "#843C0C" }
    ]
  }]
}

Key field rules:

  • bounds = centre + size (x, y, w, h).
  • groupId alone is enough — the engine fills group.members and the container bounds.
  • shapeData becomes real Visio Shape Data (visible in the Shape Data window).
  • edge.kind: straight (default), rightAngle, curved, dynamic.
  • fromPort/toPort: left|right|top|bottom|auto. Omit and let the router decide.
  • waypoints: explicit [{x,y},…] when you need a route the router cannot find. Explicit waypoints are never overwritten.
  • Colours accept #RRGGBB, rgb(...), or CSS names. Text colour is auto-contrasted when omitted.

Validate against the schema if a validator is available: schemas/diagram.schema.json.


4. Create and render

vsdx-tool create --input model.json --output diagram.vsdx
vsdx-tool render --input diagram.vsdx --format png --output diagram.png --dpi 120
vsdx-tool render --input diagram.vsdx --format svg --output diagram.svg

Or let the engine place the nodes entirely

If you are generating a diagram from a model rather than editing an existing one, you usually do not need to hand-place anything:

vsdx-tool create --input model.json --output diagram.vsdx --layout auto --fit-page

--layout picks the arrangement; auto chooses from the diagram's type:

StrategyUse forWhat it does
layeredarchitecture, microservices, network, deploymentBands top-to-bottom, nodes ordered left-to-right inside each band
flowbusiness processes, pipelinesFollows the arrows; with containers, one band per container
treeorg chartsRoot on top, widens downward
gridinventories, no groupingUniform rows and columns
manualyou pinned every coordinateNothing moves

auto resolves to: architecture/network/microservices → layered; workflow with a decision node → flow; workflow without decisions → layered; org → tree.

When containers are present, grid and tree fall back to a banded layout rather than scattering members — grouping always wins over the nominal strategy.

Prefer authoring the model with only ids, text, groupId and edges, then let --layout auto --fit-text --fit-page derive all geometry. Hand-writing coordinates is what makes a diagram look assembled rather than designed.

Let the engine size the boxes, then look

Hand-writing every bounds is what makes a diagram look assembled rather than designed. If you do not have a strong reason to pin coordinates, let the engine derive size from text and fit the page:

vsdx-tool create --input model.json --output diagram.vsdx \
  --fit-text    # node/container size from label length (+ padding)
  --fit-page    # page shrinks or grows to the drawing
  --recenter    # equal margins around the content

It only ever grows a box to fit its text — it never clips a label and never shrinks a box you deliberately made large. Font size has a hard legibility floor; if content is too dense the engine says "split the diagram" instead of quietly shrinking type.

render re-opens the saved package and projects its real geometry, so the preview always matches the deliverable. CJK fonts are resolved automatically; pass --font-file to force a specific face.


5. Check layout, then look at the preview

Machine checks are necessary but not sufficient. Do both.

vsdx-tool check-layout --input diagram.vsdx --json

Read hardConstraintsPassed first, then score.

hardConstraintsPassed: false means the diagram is not deliverable. When it is false the score is forced to 0, so a high score can never hide a broken layout. Fix every error before looking at anything else.

CodeSeverityMeaningFix
node.overlaphardTwo nodes intersectRe-space the column or row
edge.through-nodehardA connector crosses an unrelated nodeMove the node, or add waypoints
group.overlaphardTwo container bands overlapSeparate the bands; do not just nudge one node
group.member-escapeshardA node pokes out of its containerUsually fixed by autoSize: true
edge.detoursoftConnector wanders > 2× the straight distanceMove endpoints closer, or rewrite waypoints
row.misalignedsoftNodes on one row differ in YGive the row a single baseline
row.size-jittersoftNeighbouring same-family nodes differ a lot in sizeUnify the row's node size
group.guttersoftTwo stacked bands are too closeWiden the vertical step
spacing.too-tightsoftNeighbours closer than ~0.18"Widen the column step
text.overflow-*softLabel does not fit its boxShorten text, raise w/h, or lower fontSize
edge.crossingsoftTwo connectors crossUsually acceptable; reduce when easy
label.overlaps-nodesoftA label sits on a nodeMove the edge or set labelPosition

Every issue also carries rootCause, recommendedFix and level (Local / RegionRelayout / FullRedraw). Follow level — patching one node when the diagnosis says RegionRelayout is how a diagram gets worse with each attempt.

edgeDetourRatio in the JSON gives the measured detour factor per edge, so you can see which connector is the outlier rather than guessing.

Then open the PNG and look at it. Ask yourself:

  1. Can I follow each arrow from source to target without tracing a maze?
  2. Does every layer read as one visual band?
  3. Is any label unreadable, clipped, or sitting on a line?
  4. Do the shapes' semantics match their roles?
  5. Is the page mostly filled, or is there a large empty region?

Iterate until it looks right. "The file was produced" is not acceptance.


6. Modify an existing diagram incrementally

Never regenerate the whole diagram to apply an edit. Load the model, change only what was asked, apply it onto the original package.

# 1. Read the current package into the editable model
vsdx-tool export-model --input diagram.vsdx --output current.json

# 2. Edit current.json (rename / add / move / regroup …)

# 3. Apply onto the ORIGINAL package so untouched objects keep their identity
vsdx-tool update --input diagram.vsdx --model current.json --output diagram_v2.vsdx
vsdx-tool render --input diagram_v2.vsdx --format png --output diagram_v2.png --dpi 120

# 4. Prove nothing else changed
vsdx-tool diff --before diagram.vsdx --after diagram_v2.vsdx

Renaming a node

Keep the same thing, change only how it is labelled:

// Before
{ "id": "query-service", "text": "查询服务\nQuery Service", "visioShapeId": "query-service" }
// After — id changes, visioShapeId pins the existing shape so this is a rename, not a rebuild
{ "id": "analytics-service", "text": "分析服务\nAnalytics Service",
  "visioShapeId": "query-service" }

Every edge that pointed at query-service must be re-pointed to analytics-service.

If you omit visioShapeId, the engine still matches by stored stable id or by text, but setting it explicitly is the reliable path.

Adding a node

Append it, give it a groupId, and add the edges. Then check the layout again — a new node often lands on an existing connector.

Deleting

Remove it from nodes (and its edges), then pass --delete-missing. Without that flag the engine keeps package content the model does not mention and says so in its report.


6b. When a fix makes things worse

This is the most common way a diagram degrades. You spot an overlap, nudge a node, a connector now crosses something, you nudge again, and after five rounds the figure is worse than when you started. The engine has an explicit loop for this — use it instead of patching coordinates by hand.

vsdx-tool repair --input diagram.vsdx --output fixed.vsdx --json

It plans, attempts, accepts or rolls back, escalates, and stops. Read attempts and stopReason in the JSON, not just the final score.

Repair level: follow the diagnosis, do not improvise

Every issue carries a level. It is the smallest change that can plausibly work:

LevelMeaningWhat you should do
Localone label or one isolated elementadjust that element only
RegionRelayouta container's contents, or two intersecting shapesre-lay that band as a whole
FullRedrawthe layout strategy itself is wrongregenerate from the model

Patching one node when the level says RegionRelayout is exactly how the spiral starts. Two intersecting shapes cannot be fixed by moving one of them in isolation — the collision just moves somewhere else.

Three rules the loop enforces

  1. A fix is only kept if it removes an issue and adds no new hard violation. Moving an overlap elsewhere counts as a regression and is rolled back.
  2. A strategy that already failed for an issue is never retried.
  3. When every level has been tried without improvement, it stops rather than burning rounds on known failures.

If stopReason says every level was tried, the honest response is to tell the user what remains — not to keep nudging.

Deliberately not automatic

edge.crossing is a soft quality item. Relayout rarely removes crossings, so the loop will report it and stop rather than thrash. Reduce crossings by choosing better column order, or accept them and say so.


6c. Titles, legends and custom shapes

A diagram without a title reads as a draft. The engine has three object kinds, and picking the wrong one corrupts the layout:

You wantUseWhy not a node
Chart title, subtitletextBlocksA node joins the layout graph and drags spacing around
Legend, footnotetextBlocksSame
A rule, separator, drawn curvepathsA node is a box with a label, not an outline

Text blocks

"textBlocks": [
  { "id": "title", "text": "订单处理平台", "role": "title",
    "box": { "x": 5.5, "y": 8.6, "width": 6, "height": 0.6 },
    "align": "center", "bold": true },
  { "id": "legend", "text": "蓝 = 服务   绿 = 数据", "role": "legend",
    "box": { "x": 5.5, "y": 1.2, "width": 6, "height": 0.35 },
    "align": "center" }
]

role sets the size for you — title 20pt, subtitle 12pt, legend 10pt, note 8pt. fontSize overrides it. box is required: text is not laid out, so where it goes is a design decision, not something the engine should guess.

Paths

"paths": [
  { "id": "rule", "box": { "x": 5.5, "y": 7.6, "width": 8, "height": 0.05 },
    "stroke": "#999999", "strokeWidth": 0.012,
    "rows": [
      { "type": "MoveTo", "cells": { "X": "0", "Y": "0" } },
      { "type": "LineTo", "cells": { "X": "8", "Y": "0" } }
    ] }
]

Coordinates are local to the box. MoveTo must come first. ArcTo, SplineKnot and any other instruction are carried through verbatim — the engine does not compute the curve, but it will not drop or straighten it either.

Two rules worth knowing

  • Decorations are not laid out. A title stays where you put it even when the services move. After layout they are nudged inside the page if they would otherwise fall off it.
  • Ids share one namespace across nodes, containers, text and paths, because z-order is a single list. A duplicate is rejected rather than silently resolved.

7. Confirm before delivering

vsdx-tool validate --input diagram.vsdx --json     # structure + OPC + Visio semantics
vsdx-tool inspect  --input diagram.vsdx --json     # counts, groups, layers, shape data

Deliver:

FilePurpose
diagram.vsdxThe deliverable — real, editable Visio
diagram.pngPreview for humans and for your own iteration
diagram.svgVector preview / embedding
diagram.jsonThe model, so the next edit is cheap

Report hardConstraintsPassed, the layout score, and any compatibility warnings alongside the files. If compatibility.issues is non-empty, quote the codes — they are meaningful, not noise.


8. Failure handling

SymptomCauseAction
Chinese renders as □No CJK font reachablefc-list :lang=zh; pass --font-file
update reports edge-from-missingEdge references an id that is not in nodesFix the id
Text clipped in PNG but correct in SVGLabel did not fit its boxEnlarge the node or shorten text
Container border cuts through nodesExplicit bounds smaller than membersRemove bounds, keep autoSize: true
validate fails on a foreign fileGenuinely different VSDX dialectRead inspect --json warnings; report limits honestly

9. Hard rules

  1. The .vsdx is the deliverable. A renamed PNG/SVG is a failure.
  2. Design the grid before writing coordinates.
  3. Change only what the user asked for; prove it with diff.
  4. Keep node ids stable across edits that do not rename the concept.
  5. check-layout reporting hardConstraintsPassed: false blocks delivery. A soft score is advisory and never overrides a hard failure.
  6. Open the PNG and judge it visually before claiming success.
  7. Do not claim Visio-native validation — that requires a real Visio install.
  8. When the engine reports a compatibility issue, surface it. Do not swallow it.

関連スキル