What languages does pactkit-visualize support?

It analyzes Python source files (.py) to generate the graphs. Other languages are not supported.

Where are the generated graphs stored?

Graphs are written to docs/architecture/graphs/ with names depending on the mode, e.g., code_graph.mmd for file mode, class_graph.mmd for class mode, and call_graph.mmd for call mode. Focus variants are stored as focus_* graph files.

What do --entry and --focus do?

--entry enables BFS-style transitive tracing from a specified function (only valid with --mode call). --focus narrows the graph to a particular module (valid for any mode when applicable).

pactkit-visualize

npx machina-cli add skill pactkit/claude-code-plugin/pactkit-visualize --openclaw

Files (1)

SKILL.md

2.8 KB

PactKit Visualize

Generate project code relationship graphs (Mermaid format), supporting three analysis modes.

Script location: Use the base directory from the skill invocation header to resolve script paths. Classic deployment: ${CLAUDE_PLUGIN_ROOT}/skills/pactkit-visualize/scripts/visualize.py

Prerequisites

The project must have Python source files (.py) to generate meaningful graphs
The docs/architecture/graphs/ directory is automatically created by init_arch

Command Reference

visualize -- Generate code dependency graph

python3 ${CLAUDE_PLUGIN_ROOT}/skills/pactkit-visualize/scripts/visualize.py visualize [--mode file|class|call] [--entry <func>] [--focus <module>]

Parameter	Description	Default
`--mode file`	File-level dependency graph (inter-module import relationships)	Default
`--mode class`	Class diagram (including inheritance)	-
`--mode call`	Function-level call graph	-
`--entry <func>`	BFS transitive chain tracing from specified function (requires `--mode call`)	-
`--focus <module>`	Focus on call relationships of specified module (requires `--mode call`)	-

init_arch -- Initialize architecture directory

python3 ${CLAUDE_PLUGIN_ROOT}/skills/pactkit-visualize/scripts/visualize.py init_arch

Creates docs/architecture/graphs/ and docs/architecture/governance/
Generates placeholder file system_design.mmd

list_rules -- List governance rules

python3 ${CLAUDE_PLUGIN_ROOT}/skills/pactkit-visualize/scripts/visualize.py list_rules

Outputs the list of rule files under docs/architecture/governance/

Output Files

Mode	Output Path	Mermaid Type
`--mode file`	`docs/architecture/graphs/code_graph.mmd`	graph TD
`--mode class`	`docs/architecture/graphs/class_graph.mmd`	classDiagram
`--mode call`	`docs/architecture/graphs/call_graph.mmd`	graph TD
`--focus` (file)	`docs/architecture/graphs/focus_file_graph.mmd`	graph TD
`--focus` (class)	`docs/architecture/graphs/focus_class_graph.mmd`	classDiagram
`--focus` (call)	`docs/architecture/graphs/focus_call_graph.mmd`	graph TD

Usage Scenarios

/project-plan: Run visualize to understand current project state before making design decisions
/project-act: Run visualize --focus <module> to understand dependencies of the modification target
pactkit-doctor skill: Run visualize to check whether architecture graphs can be generated correctly
pactkit-trace skill: Run visualize --mode call --entry <func> to trace call chains

Source

git clone https://github.com/pactkit/claude-code-plugin/blob/main/pactkit-plugin/skills/pactkit-visualize/SKILL.mdView on GitHub

Overview

pactkit-visualize generates Mermaid diagrams that map code relationships in a Python project. It supports file-level, class-level, and function-level call graphs, helping you understand imports, inheritance, and call chains. Graphs are produced under docs/architecture/graphs and can be generated via the visualize script using the project’s base path.

How This Skill Works

The tool analyzes Python source files in the project (resolved from the skill invocation header). Running python3 ... visualize.py with --mode (file, class, or call) builds the corresponding Mermaid graph and writes it to the appropriate path in docs/architecture/graphs. Optional parameters like --entry enable BFS-style function tracing, and --focus narrows the graph to a specific module.

When to Use It

/project-plan: Run visualize to understand current project state before making design decisions
/project-act: Run visualize --focus <module> to understand dependencies of the modification target
pactkit-doctor: Run visualize to check whether architecture graphs can be generated correctly
pactkit-trace: Run visualize --mode call --entry <func> to trace call chains
General refactoring: Run visualize to refresh file/class/call graphs after significant code changes

Quick Start

Step 1: Ensure you have Python sources and run init_arch to create graph directories
Step 2: Run the desired graph with python3 ${CLAUDE_PLUGIN_ROOT}/skills/pactkit-visualize/scripts/visualize.py visualize --mode <file|class|call> [--entry <func>] [--focus <module>]
Step 3: Open docs/architecture/graphs/*.mmd (or the focus_* variants) to review the Mermaid diagrams

Best Practices

Ensure your project contains Python (.py) source files to produce meaningful graphs
Run init_arch at least once to create docs/architecture/graphs/ before generating graphs
Choose the appropriate --mode (file, class, or call) for the insight you need
Use --entry when tracing specific function call chains and --focus to limit scope to a module
Regularly regenerate graphs as the codebase evolves to keep diagrams up-to-date

Example Use Cases

A multi-package Python project runs visualize --mode file to map module import relationships across packages
A library author uses visualize --mode class to visualize class diagrams including inheritance
A developer runs visualize --mode call --entry process_data to see the function call graph starting from process_data
During architecture review, init_arch is run to create graphs and an initial system_design.mmd placeholder
PactKit-trace is used with visualize to validate that call chains exist for critical entry points

Frequently Asked Questions

Add this skill to your agents