SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsinsight-diagram

insight-diagram

General & other

View repository

Updated 10-15 23:46

About this skill

Insight Diagram — Project Diagram Generation Skill

Analyze any codebase and automatically generate 14 types of UML diagrams + architecture diagrams + flowcharts, using /architecture-diagram to render as HTML+SVG.

Diagram Classification and Inventory

Structural Diagrams — Static

Describe the physical composition and static structure of a system.

No. Diagram Type English Identifier Focus
1 System Architecture Diagram architecture Component relationships, global perspective (non-UML, most commonly used)
2 Class Diagram class Define classes, attributes, operations, and relationships
3 Object Diagram object Object instances and their relationships at a specific point in time
4 Component Diagram component System components and their dependencies
5 Deployment Diagram deployment Physical hardware, nodes, and software deployment
6 Package Diagram package Group and organize model elements
7 Composite Structure Diagram composite-structure Internal structure of a class
8 Profile Diagram profile Extend the UML metamodel, customize stereotypes

Behavioral Diagrams — Dynamic

Describe the interaction process between the system and external actors or within the system.

No. Diagram Type English Identifier Focus
9 Flowchart flowchart Main flow and branches (non-UML, most commonly used)
10 Use Case Diagram usecase Show system functionality from the user's perspective
11 Activity Diagram activity The flow or steps of a process
12 State Machine Diagram state-machine State transitions in an object's lifecycle
13 Sequence Diagram sequence Show interactions between objects in chronological order
14 Communication Diagram communication Focus on the organizational relationships between objects
15 Timing Diagram timing Focus on time constraints of state changes
16 Interaction Overview Diagram interaction-overview Combines activity diagrams and sequence diagrams
17 Swimlane Diagram swimlane Cross-component/role responsibility flow (activity diagram variant)

Example Reference

This skill's examples/ directory contains 13 completed diagram HTML files, serving as reference templates for visual style and content structure.Before generating any diagram, you must first read the corresponding example file, to ensure consistent style and standardized structure.

Example File Inventory

File Diagram Type English Identifier
examples/architecture.html System Architecture Diagram architecture
examples/class.html Class Diagram class
examples/object.html Object Diagram object
examples/component.html Component Diagram component
examples/deployment.html Deployment Diagram deployment
examples/flowchart.html Flowchart flowchart
examples/usecase.html Use Case Diagram usecase
examples/activity.html Activity Diagram activity
examples/sequence.html Sequence Diagram sequence
examples/communication.html Communication Diagram communication
examples/dfd.html Data Flow Diagram dfd
examples/interaction-overview.html Interaction Overview Diagram interaction-overview
examples/swimlane.html Swimlane diagram swimlane

Reference rules

  1. Must-read before generation: Call /architecture-diagram Before, first use the Read tool to read the example file of the corresponding type, and extract from it:

    • SVG layout strategy (node spacing, grouping method, arrow direction)
    • Node style hierarchy (core nodes highlighted with accent, regular nodes with solid borders, optional nodes with dashed borders)
    • Annotation style (phase labels, Legend, card summaries)
    • Information density (how many fields/attributes each node displays)

  2. Structural alignment: The generated diagram should maintain the same structural hierarchy as the example:

    • Top of page: title + subtitle + chart type description
    • Middle body: SVG diagram area (with a light-colored border container)
    • Bottom: information summary card + footer

  3. Content replacement rather than copying: The business data in the example (NovaShield risk control system) is a fictional reference case; when generating, replace it with the real architecture information of the target project. Only reference the layout and style; do not copy the business content.

  4. Types without corresponding examples: For the 5 diagram types that have no example files—package diagram (package), composite structure diagram (composite-structure), profile diagram (profile), state machine diagram (state-machine), and timing diagram (timing)—refer to the closest existing examples (e.g., package diagram refers to component diagram, state machine diagram refers to activity diagram), and follow the same visual language.

Execution flow

Step 1: Analyze the codebase

Read key project files and extract architecture information:

  1. Read the project root directory's CLAUDE.md(if present) to get a project overview
  2. Read each subdirectory's CLAUDE.md(if present) to get module details
  3. Use Glob to scan the source code file structure (**/*.go, **/*.py, **/*.ts etc.)
  4. Read the entry files (main.go, app.py, index.ts etc.) to identify top-level components
  5. Use Grep to search for key patterns: interface definitions, function signatures, dependency injection, configuration items

From the above information, extract:

  • Component list: services, modules, external dependencies
  • Relationship diagram: who calls whom, who depends on whom, data flow direction
  • Core types: structs/classes, interfaces, enums
  • Flow: main business processes, exception handling processes
  • Deployment: processes, middleware, external services

Step 2: Select diagrams

Use AskUserQuestion to let the user select the diagrams to generate (multiSelect: true), displayed in 4 groups:

Group 1 — Structural diagrams (static):

  • System architecture diagram (architecture)
  • Class diagram (class)
  • Object diagram (object)
  • Component diagram (component)

Group 2 — Structural diagrams continued + deployment:

  • Deployment diagram (deployment)
  • Package diagram (package)
  • Composite structure diagram (composite-structure)
  • Profile diagram (profile)

Group 3 — Behavioral diagrams (dynamic):

  • Flowchart (flowchart)
  • Use case diagram (usecase)
  • Activity diagram (activity)
  • State machine diagram (state-machine)

Group 4 — Interaction diagrams + common non-UML:

  • Sequence diagram (sequence)
  • Communication diagram (communication)
  • Interaction overview diagram (interaction-overview)
  • Swimlane diagram (swimlane)
  • Generate all (all)

Default recommendation: architecture + sequence + flowchart

Step 3: Generate one by one

For each selected diagram type:

  1. First read the example: use the Read tool to read examples/<标识>.html(e.g. examples/architecture.html), extract the layout pattern, node styles, and annotation approach
  2. Based on the architecture information extracted in step 1, organize the elements and relationships that this diagram should display
  3. Invoke the /architecture-diagram skill, passing in the diagram type, title, content description, and output path,must specify the light style
  4. Save the output file to docs/<标识>.html(e.g. docs/architecture.html）
  5. After generation, must review: run the geometry validation script, correct according to the results before continuing to the next one (see "Step 3.5" below)
  6. Briefly report the completion status

Generation rules:

  • Style: must use the light Claude style (warm white background #FAF9F6, terracotta/sage/plum/rose color palette, Inter font, white card containers), consistent with Anthropic Claude brand visuals
  • Anti-occlusion: all SVG elements (nodes, arrows, labels) must not occlude one another. Specific practices:
    • Calculate the bounding box of each element to ensure no overlap
    • Draw arrows beneath the nodes (in SVG, draw arrows first, then nodes)
    • Leave sufficient spacing between nodes (at least 40px vertically, at least 30px horizontally)
    • Text must not exceed the boundaries of its node; truncate or wrap overly long text
    • Place connector line labels at an offset from the midpoint of the segment, to avoid covering the segment or nodes
    • If there are too many elements and the diagram becomes crowded, split it into multiple sub-diagrams or reduce the element sizes

Batch generation order (macro → micro): architecture → component → deployment → package → composite-structure → profile → class → object → usecase → flowchart → activity → state-machine → swimlane → sequence → communication → timing → interaction-overview

Step 3.5: Geometry review (mandatory after each diagram is generated)

Generated SVGs commonly have three types of geometry defects, which must be validated and corrected one by one using a script:

python3 skills/insight-diagram/scripts/review_svg.py docs/<标识>.html --min-gap 8
# 批量： python3 skills/insight-diagram/scripts/review_svg.py docs/*.html --min-gap 8

Script checks (corresponding one-to-one with the three core requirements):

  1. Arrow landing point: every endpoint with an arrow must land exactly on the target box/ellipse/diamond'sedge line(tolerance 6px).
    • ERROR 深入框内: endpoint penetrates more than 8px into the box interior → shorten the connector so it stops at the edge.
    • WARNING 空接: endpoint is dangling, more than 8px from the nearest box and not merging into any other connector → align the endpoint to the box edge or a merge point.
    • Legal cases: the endpoint lands on a box edge, a lifeline, or intersects another connector (branch/merge) — the script will not report these as false positives.
  2. Box overlap（ERROR): two non-nested boxes overlap in both the horizontal and vertical directions → one of them must be moved away. Nesting (one completely containing another, such as a group boundary box containing child nodes) is allowed.
  3. Box spacing（WARNING): the net spacing between two boxes that are adjacent in projection is < --min-gap(default 8px) → increase the spacing.

Handling principles:

  • ERRORs must be fixedbefore moving on to the next diagram; after fixing, rerun the script to confirm it is back to zero.
  • Check WARNINGs one by one: messages at the bottom of sequence diagram lifelines, swimlane boundaries, tightly adjacent groups, etc. may be intentional by design, and can be kept once confirmed correct; the rest should have their coordinates adjusted.
  • The fix is to directly edit docs/<标识>.html the corresponding <rect>/<line>/<path> coordinates in it, rather than regenerating the entire diagram.
  • Exit code: returns 1 if there are ERRORs, 0 if clean; in CI you can add --strict to make WARNINGs also block.

Step 4: Report

After everything is complete, output:

  • List of generated files
  • Brief description of each diagram

Content guidelines for each diagram

System architecture diagram (architecture) — non-UML, most commonly used

  • Show the system's top-level components and their connections
  • Distinguish internal modules from external dependencies
  • Mark the direction of core data flows

Class diagram (class)

  • Core types as class nodes (name + fields + methods)
  • Inheritance, composition, dependency relationships
  • Separation of interfaces and implementations
  • Limit to 10-15 core types

Object diagram (object)

  • Select a typical runtime scenario
  • Show object instances and their attribute values
  • Link relationships between objects

Component diagram (component)

  • Each component is a node
  • Arrows indicate dependency/call direction
  • Label interface names

Deployment diagram (deployment)

  • Physical nodes (servers, containers, Serverless)
  • Middleware (message queues, caches, databases)
  • External services (third-party APIs)
  • Label communication protocols

Package diagram (package)

  • Group by module/namespace
  • Dependencies between packages
  • Reflect the layered architecture

Composite structure diagram (composite-structure)

  • Internal structure of a class/component
  • Parts and Connectors
  • Ports and interfaces

Profile diagram (profile)

  • Custom stereotypes
  • Tagged Values extending the metamodel
  • Domain-specific modeling constraints

Flowchart (flowchart) — non-UML, most commonly used

  • Main flow + key branches
  • Failure/exception paths
  • Clear start and end nodes

Use case diagram (usecase)

  • Actors (people/external systems)
  • Use case ellipses
  • include/extend relationships

Activity diagram (activity)

  • Stages/steps as activity nodes
  • Parallel branches use fork/join
  • Decision points use diamonds

State machine diagram (state-machine)

  • Key states of the object
  • Events that trigger state transitions
  • Actions/guard conditions
  • Initial state and final state

Sequence diagram (sequence)

  • Participants as vertical lifelines
  • Horizontal arrows as message calls
  • Label key return values
  • Focus on 2-5 core interaction scenarios

Communication diagram (communication)

  • Components as nodes, messages as connecting lines
  • Label message sequence numbers
  • Emphasize collaboration relationships rather than timing

Timing diagram (timing)

  • Timeline expanded horizontally
  • Time constraints on state changes
  • Duration annotations

Interaction overview diagram (interaction-overview)

  • Control flow nodes with embedded interaction fragments
  • Show conditional branches and loops
  • Macro-level overview of each interaction scenario

Swimlane diagram (swimlane) — activity diagram variant

  • Swimlanes divided by component/role
  • Process steps within the corresponding swimlane
  • Cross-swimlane arrows indicate interactions