Code Visualizer Skill
Purpose
Automatically generate and maintain visual code flow diagrams. This skill analyzes Python module structure, detects import relationships, and generates mermaid diagrams. It also monitors for staleness when code changes but diagrams don't.
Philosophy Alignment
This skill embodies amplihack's core philosophy:
Ruthless Simplicity
- Single responsibility: Visualize code structure - nothing more
- Minimal dependencies: Uses only Python AST for analysis, delegates diagram syntax to mermaid-diagram-generator
- No over-engineering: Timestamp-based staleness is simple and "good enough" for 90% of cases
Zero-BS Implementation
- Real analysis: Actually parses Python AST to extract imports - no mock data
- Honest limitations: Staleness detection is timestamp-based, not semantic (see Limitations section)
- Working code: All algorithms shown are functional, not pseudocode
Modular Design (Bricks & Studs)
- This skill is one brick: Code analysis and staleness detection
- Delegates to other bricks: mermaid-diagram-generator for syntax, visualization-architect for complex diagrams
- Clear studs (public contract): Analyze modules, generate diagrams, check freshness
Skill Delegation Architecture
code-visualizer (this skill)
├── Responsibilities:
│ ├── Python module analysis (AST parsing)
│ ├── Import relationship extraction
│ ├── Staleness detection (timestamp-based)
│ └── Orchestration of diagram generation
│
└── Delegates to:
├── mermaid-diagram-generator skill
│ ├── Mermaid syntax generation
│ ├── Diagram formatting and styling
│ └── Markdown embedding
│
└── visualization-architect agent
├── Complex multi-level architecture
├── ASCII art alternatives
└── Cross-module dependency graphs
Invocation Pattern:
modules = analyze_python_modules("src/")
relationships = extract_import_relationships(modules)
Skill(skill="mermaid-diagram-generator")
Task(subagent_type="visualization-architect", prompt="Create multi-level diagram for...")
When to Use This Skill
- New Module Creation: Auto-generate architecture diagram for new modules
- PR Reviews: Show architecture impact of proposed changes
- Staleness Detection: Check if existing diagrams reflect current code
- Dependency Analysis: Visualize import relationships
- Refactoring: Understand module dependencies before changes
Quick Start
Generate Diagram for Module
User: Generate a code flow diagram for the authentication module
Check Diagram Freshness
User: Are my architecture diagrams up to date?
Show PR Impact
User: What architecture changes does this PR introduce?
Core Capabilities
1. Module Analysis
Analyzes Python files to extract:
- Import statements (internal and external)
- Class definitions and inheritance
- Function exports (
__all__)
- Module dependencies
2. Diagram Generation
Creates mermaid diagrams showing:
- Module relationships (flowchart)
- Class hierarchies (class diagram)
- Data flow between components
- Dependency graphs
3. Staleness Detection
Compares:
- File modification timestamps
- Git history for changes
- Diagram content vs actual code structure
- Missing modules in diagrams
Analysis Process
Step 1: Discover Modules
modules = glob("**/*.py")
packages = identify_packages(modules)
Step 2: Extract Relationships
For each module:
- Parse import statements
- Identify local vs external imports
- Build dependency graph
- Detect circular dependencies
Step 3: Generate Diagram
flowchart TD
subgraph core["Core Modules"]
auth[auth.py]
users[users.py]
api[api.py]
end
subgraph utils["Utilities"]
helpers[helpers.py]
validators[validators.py]
end
api --> auth
api --> users
auth --> helpers
users --> validators
Step 4: Check Freshness
Compare diagram timestamps with source files:
- Diagram older than sources = STALE
- Missing modules in diagram = INCOMPLETE
- Extra modules in diagram = OUTDATED
Diagram Types
Module Dependency Graph
Best for: Showing import relationships between files
flowchart LR
main[main.py] --> auth[auth/]
main --> api[api/]
auth --> models[models.py]
api --> auth
Class Hierarchy
Best for: Showing inheritance and composition
classDiagram
class BaseService {
+process()
}
class AuthService {
+login()
+logout()
}
BaseService <|-- AuthService
Data Flow
Best for: Showing how data moves through system
flowchart TD
Request[HTTP Request] --> Validate{Validate}
Validate -->|Valid| Process[Process]
Validate -->|Invalid| Error[Return Error]
Process --> Response[HTTP Response]
Staleness Detection
How It Works
- Find Diagrams: Locate mermaid diagrams in README.md, ARCHITECTURE.md
- Extract Modules: Parse diagram for referenced modules
- Compare: Check if all current modules are represented
- Report: Generate freshness report
Freshness Report Format
## Diagram Freshness Report
### Status: STALE
**Diagrams Checked**: 3
**Fresh**: 1
**Stale**: 2
### Details
| ------------ | ------------ | ------------ | ------ |
| README.md | 2025-01-01 | 2025-01-15 | STALE |
| docs/ARCH.md | 2025-01-10 | 2025-01-10 | FRESH |
### Missing from Diagrams
- `new_module.py` (added 2025-01-12)
- `api/v2.py` (added 2025-01-14)
### Recommended Actions
1. Update README.md architecture diagram
2. Add new_module.py to dependency graph
PR Architecture Impact
What It Shows
For a given PR or set of changes:
- New modules/files added
- Changed import relationships
- Deleted dependencies
- Modified class hierarchies
Impact Diagram
flowchart TD
subgraph added["New"]
style added fill:#90EE90
new_api[api/v2.py]
end
subgraph modified["Modified"]
style modified fill:#FFE4B5
auth[auth.py]
end
subgraph existing["Unchanged"]
users[users.py]
models[models.py]
end
new_api --> auth
auth --> models
users --> models
Integration with Other Skills
Mermaid Diagram Generator
This skill uses mermaid-diagram-generator for:
- Syntax generation
- Diagram formatting
- Embedding in markdown
Visualization Architect Agent
Delegates to visualization-architect for:
- Complex architecture visualization
- ASCII art alternatives
- Multi-level diagrams
Usage Examples
Example 1: New Module Diagram
User: I just created a new payment module. Generate an architecture diagram.
Claude:
1. Analyzes payment/ directory
2. Extracts imports and dependencies
3. Generates mermaid flowchart
4. Suggests where to embed (README.md)
Example 2: Check Staleness
User: Are my diagrams up to date?
Claude:
1. Finds all mermaid diagrams in docs
2. Compares with current codebase
3. Reports stale diagrams
4. Lists missing modules
5. Suggests updates
Example 3: PR Impact
User: Show architecture impact of this PR
Claude:
1. Gets changed files from PR
2. Identifies new/modified/deleted modules
3. Generates impact diagram
4. Highlights dependency changes
Detection Algorithms
Import Analysis
import ast
def extract_imports(file_path):
"""Extract import statements from Python file."""
tree = ast.parse(Path(file_path).read_text())
imports = []
for node in ast.walk(tree):
if isinstance(node, ast.Import):
for alias in node.names:
imports.append(alias.name)
elif isinstance(node, ast.ImportFrom):
i
