visio-skill

name	visio-skill
description	Generate or modify Microsoft Visio .vsdx diagrams using local Visio COM automation. Use when the user asks Codex to create Visio files, draw flowcharts, architecture diagrams, sequence diagrams, swimlane-style layouts, network topology diagrams, process maps, or to automate shapes/connectors/text in Microsoft Visio on Windows.

Visio Skill

Workflow

Use local Microsoft Visio COM automation when Visio is installed and the user wants a real .vsdx file. Prefer the bundled script for new diagrams:

python "<skill>/scripts/New-VisioDiagram.py" "<diagram.json>" "<diagram.vsdx>"

Create a JSON spec first, then run the script. Keep output files in the user's requested folder, or in the active workspace when unspecified.

RTL / Verilog Logic Block Diagrams

When the user provides Verilog sources or asks for an FPGA / RTL logic block diagram, prefer the deterministic RTL generator instead of manually writing a JSON layout:

python "<skill>/scripts/verilog_to_visio.py" "<verilog-dir-or-top.v>" "<output.vsdx>" \
  --top top_module \
  --json "<output.json>" \
  --preview "<preview.png>"

Read references/rtl-verilog.md for the supported role inference and layout rules. The generator intentionally summarizes global clock and reset fanout to keep the module-level diagram readable. Use the generated JSON only as a fallback customization point for unusual designs.

Reconstruct Editable Visio from an Image

When the user provides a non-editable PNG, JPG, screenshot, scanned flowchart, architecture diagram, timeline, table, or Gantt chart and wants an editable Visio reconstruction, use:

python "<skill>/scripts/image_to_visio.py" "<input.png>" "<output.vsdx>" \
  --mode auto \
  --json "<output.json>" \
  --preview "<preview.png>"

Read references/image-reconstruction.md for the complete workflow. The local parser extracts shapes, bars, sampled colors, and line geometry. OCR is optional. For text-heavy or visually complex diagrams, inspect the user image and pass a small --annotations JSON overlay to correct labels and semantic connections without rebuilding the whole page manually.

JSON Spec

This skill supports two diagram types:

1. Standard Diagrams (flowcharts, architecture, etc.)

Read references/spec-format.md for the full format. Minimum example:

{
  "title": "Example",
  "pages": [
    {
      "name": "Page-1",
      "nodes": [
        { "id": "start", "text": "Start", "x": 1, "y": 6, "w": 2, "h": 0.8 },
        { "id": "process", "text": "Process", "x": 4, "y": 6, "w": 2, "h": 0.8 }
      ],
      "connections": [
        { "from": "start", "to": "process", "text": "flow" }
      ]
    }
  ]
}

Coordinates are in Visio inches. x and y are the lower-left corner of the node; w and h are width and height.

Using Visio Stencil Icons:

To use professional Visio stencil icons (network devices, servers, computers, etc.), declare them in the stencils array:

{
  "stencils": [
    { "id": "network", "file": "NETSYM_M.VSSX" },
    { "id": "server", "file": "SERVER_M.VSSX" }
  ],
  "nodes": [
    { "id": "router1", "stencil": "network", "master": "路由器", "text": "Core Router", "x": 2, "y": 5 },
    { "id": "srv1", "stencil": "server", "master": "服务器", "text": "Web Server", "x": 5, "y": 5 }
  ]
}

Finding stencil icons:

• Quick reference (recommended): references/stencil-reference.md — Common network/server/computer stencils with verified master names
• Full catalog: references/visio-stencil-index.md — All 362 built-in Visio stencils

Most commonly used stencils:

• NETSYM_M.VSSX (24 masters) - Network symbols (路由器, 工作组交换机, 网桥, 网关)
• SERVER_M.VSSX (17 masters) - Servers (Web 服务器, 数据库服务器, 应用程序服务器)
• COMPS_M.VSSX (10 masters) - Computers and monitors (PC, 笔记本电脑, 平板电脑)

2. Sequence Diagrams (UML interaction diagrams)

Read references/sequence-format.md for the full specification. Minimum example:

{
  "type": "sequence",
  "title": "Login Flow",
  "actors": [
    { "id": "user", "name": "User", "type": "actor" },
    { "id": "api", "name": "API", "type": "system" },
    { "id": "db", "name": "Database", "type": "database" }
  ],
  "messages": [
    { "from": "user", "to": "api", "text": "POST /login", "type": "sync" },
    { "from": "api", "to": "db", "text": "Query user", "type": "sync" },
    { "from": "db", "to": "api", "text": "User record", "type": "return" },
    { "from": "api", "to": "user", "text": "JWT token", "type": "return" }
  ]
}

Key features:

• Set "type": "sequence" to activate sequence diagram mode
• Define actors (participants) with optional type (actor, system, database, external)
• Define messages with from, to, text, and type (sync, async, or return)
• Actors are positioned left-to-right, messages flow top-to-bottom
• Lifelines and activation boxes are drawn automatically

Drawing Guidance

When to Use Stencil Icons vs Basic Shapes

Use BASIC SHAPES ONLY (no stencils) for:

• ✅ Flowcharts / 流程图
• ✅ Process diagrams / 过程图
• ✅ Decision trees / 决策树
• ✅ BPMN diagrams / 业务流程图
• ✅ State machines / 状态机
• ✅ Mind maps / 思维导图
• ✅ Org charts / 组织结构图

Use STENCIL ICONS (when user explicitly mentions "icons" or specific devices) for:

• 🔧 Network topology / 网络拓扑图 (routers, switches, firewalls)
• 🔧 Infrastructure diagrams / 基础设施图 (servers, storage, devices)
• 🔧 Cloud architecture / 云架构图 (Azure, AWS services)
• 🔧 Data center layout / 机房布局图

Default behavior: Unless the user explicitly asks for "icons", "professional icons", "network devices", or "cloud services", use basic shapes only.

Standard Diagrams

• Use explicit coordinates for predictable layout.
• Keep diagrams readable: align nodes in rows/columns, leave at least 0.6 to 1.0 inches between shapes, and route left-to-right or top-to-bottom unless the user asks otherwise.
• ⚠️ Dynamic Canvas Sizing Rule: Do NOT compress nodes, decrease fonts, or reduce spacings just to squeeze a large diagram into standard page sizes (e.g. 11x8.5 inches). Instead, dynamically increase the single-page canvas size (pageWidth/pageHeight) based on the coordinates and quantity of nodes (e.g., A3 size, or custom dimensions like 15x11 inches, 18x12 inches) to ensure all nodes and connection lines have plenty of breathing room. Each diagram should remain on a single page, but the page canvas size must scale up to fit the content beautifully.
• ⚠️ Flowchart "结束" (End) Node Rule: In flowcharts and process flow diagrams (especially top-to-bottom vertical flows), the final "结束" (End) node must always be placed at the very bottom of the diagram (i.e., having the lowest y coordinate). Do not place it to the side or parallel to intermediate steps, ensuring that the visual flow terminates cleanly at the lowest vertical level of the page.
• Default shape is roundrect (rounded rectangle). Default fill is a premium light blue #EFF6FF with a border of #3B82F6. Default node text is Microsoft YaHei at 11 pt.
• Default connector line color is slate gray #475569 with 10 pt text, automatically using "textPinX": 0.35 and "textOffsetY": 0.18 to avoid overlap.
• Utilize premium, low-saturation pastel colors for different layers/roles (e.g., #EFF6FF / #3B82F6 for main logic, #ECFDF5 / #10B981 for start/success, #FEF3C7 / #D97706 for storage, #F5F3FF / #8B5CF6 for external API).
• For side-by-side boxes with labeled connectors, leave at least max(1.4 in, label characters * 0.12 in) of horizontal gap, plus arrowhead room.
• Use short labels inside shapes. Put longer explanations in callouts or external notes.
• For architecture diagrams, group by layer: clients, edge/API, services, data, external systems.
• For process diagrams, use left-to-right flow unless there are many steps; then use rows.
• For swimlane-like diagrams, represent lanes with lightly filled large rectangles behind nodes, or create separate rows with lane labels.
• Stencil sizing: When using stencil masters, w and h are optional and will use the master's default size if omitted. Typical stencil icon size is 1.0 to 1.5 inches.

Sequence Diagrams

• Define actors in logical order (left-to-right), typically: user → frontend → backend → database → external services.
• Use descriptive actor names that clearly identify each participant (e.g., "User", "Web App", "Auth Service", "PostgreSQL").
• Choose appropriate actor types for automatic color coding:
  • "actor" for users/people (blue)
  • "system" for internal services (purple)
  • "database" for data stores (amber)
  • "external" for third-party APIs (green)
• Order messages chronologically from top to bottom, representing the actual execution flow.
• Use "type": "sync" for method calls/requests, "type": "return" for responses (shown as dashed arrows).
• Keep message labels concise but meaningful (e.g., "POST /login", "Query user", "JWT token").
• ⚠️ Sequence Diagram Page Sizing: For sequence diagrams with many messages or actors, do not squeeze actors or messages by reducing actorSpacing or messageSpacing. Instead, increase the page dimensions (pageWidth/pageHeight) of the single page to fit all elements with comfortable margins.
• For complex flows, limit to 4-6 actors maximum; split into multiple diagrams if needed.
• Default spacing is sensible; override layout.actorSpacing or layout.messageSpacing only if the diagram is too cramped or sparse.

Validation

After generating a .vsdx, confirm the file exists and has nonzero size. If the user needs visual QA, open it with Visio COM and optionally export a PNG/PDF preview.

If COM creation fails, check whether Visio is installed and registered:

import win32com.client
win32com.client.Dispatch("Visio.Application")

When Visio is unavailable, offer Mermaid, SVG, draw.io, or another importable format instead of pretending the .vsdx was created.