code-to-diagram — Claude Code skill: what it does, how to install
This skill maps imports in a codebase and produces architecture diagrams, flowcharts, and file hierarchies. Use it before review, documentation, or refactoring.
npx skills add zebbern/claude-code-guide --skill code-to-diagram -a claude-codeWhat code-to-diagram does
code-to-diagram walks through a project and resolves imports that point to files inside it. Python code is read with the ast module; JavaScript, TypeScript, Go, and Java imports are matched with regular expressions. The skill can produce a module-level architecture view, a file import flowchart, and a directory or file hierarchy.
The bundled entry point is scripts/analyze_codebase.py. It writes Mermaid definitions as .mmd, can return the analysis as JSON, and accepts a destination directory. Flags control the diagram kind, output format, scan limit, and hierarchy depth through options such as --type, --format, --max-files, and --max-depth.
Python 3.7+ is required, using its standard library. SVG rendering depends on @mermaid-js/mermaid-cli being installed, since the skill calls mmdc. The analysis covers static import relationships only, so runtime-generated imports are left out. Large graphs may also be difficult to render as one diagram.
What it helps with
- map module dependencies in an unfamiliar project
- turn file imports into a flowchart
- create Mermaid diagrams for technical documentation
- spot circular dependencies before refactoring
- limit a scan by file count or directory depth
Example prompts for the agent
- Analyze this project and create a Mermaid architecture diagram.
- Turn the imports under
srcinto a flowchart. - Analyze the codebase and write SVG diagrams to
/tmp/diagrams.
How to install code-to-diagram
1Skills CLI (Vercel)
npx skills add zebbern/claude-code-guide --skill code-to-diagram -a claude-code2Manually: put the files in place
~/.claude/skills/code-to-diagram/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/code-to-diagram/
1Skills CLI (Vercel)
npx skills add zebbern/claude-code-guide --skill code-to-diagram -a codex2Manually: put the files in place
.agents/skills/code-to-diagram/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add zebbern/claude-code-guide --skill code-to-diagram -a cursor2Manually: put the files in place
.cursor/skills/code-to-diagram/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install zebbern/claude-code-guide code-to-diagram2Manually: put the files in place
.github/skills/code-to-diagram/SKILL.md1Skills CLI (Vercel)
npx skills add zebbern/claude-code-guide --skill code-to-diagram -a gemini-cli2Platform CLI
gemini skills install https://github.com/zebbern/claude-code-guide --path skills/code-to-diagramManually: put the files in place
.devin/skills/code-to-diagram/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add zebbern/claude-code-guide --skill code-to-diagram -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about code-to-diagram
How do I install code-to-diagram in Claude Code?
Run npx skills add zebbern/claude-code-guide --skill code-to-diagram -a claude-code, then check ~/.claude/skills/code-to-diagram/SKILL.md.
What does code-to-diagram do?
It extracts static import relationships and turns them into an architecture diagram, an import flowchart, or a file hierarchy. Results can be written as Mermaid, SVG, or JSON.
What is required for SVG output, and which imports are tracked?
SVG output requires @mermaid-js/mermaid-cli, which provides mmdc. The skill follows static imports; dynamically created imports are not tracked.
Source text
SKILL.md · MIT
--- name: code-to-diagram description: "Analyze codebases and automatically generate architecture diagrams, flowcharts, and org charts. Uses AST parsing to map import dependencies for Python, JS/TS, Go, and Java, outputting Mermaid or SVG files. Triggered when users ask to visualize code architecture, understand dependencies, draw a flowchart, or create a module diagram from source code." license: MIT type: tool tags: ["visualization", "architecture", "mermaid", "ast", "diagram"] --- # Code to Diagram Extract import and dependency relationships from a codebase via AST parsing, and automatically generate three types of diagrams: 1. **Architecture Diagram** — Module/directory-level dependency relationships 2. **Flowchart** — File-level import call chains 3. **Org Chart** — Directory/file hierarchy structure Supported languages: Python, JavaScript, TypeScript, Go, Java Output formats: Mermaid text (`.mmd`) or SVG images (requires `mmdc` installed on the system) ## Usage ### Basic: Analyze an Entire Project ```bash python3 scripts/analyze_codebase.py /path/to/project ``` Outputs three Mermaid diagrams to stdout and writes `.mmd` files to the current directory. ### Specify Diagram Type ```bash # Architecture diagram only python3 scripts/analyze_codebase.py /path/to/project --type architecture # Flowchart only python3 scripts/analyze_codebase.py /path/to/project --type flowchart # Org chart only python3 scripts/analyze_codebase.py /path/to/project --type org ``` ### Specify Output Directory and Format ```bash # Output to a specific directory python3 scripts/analyze_codebase.py /path/to/project --output /tmp/diagrams # Output as SVG (requires mmdc) python3 scripts/analyze_codebase.py /path/to/project --format svg # Output both Mermaid and SVG python3 scripts/analyze_codebase.py /path/to/project --format both ``` ### Output JSON Analysis Results ```bash python3 scripts/analyze_codebase.py /path/to/project --json ``` ### Parameters | Parameter | Description | |-----------|-------------| | `directory` | Code directory to analyze (required) | | `--type, -t` | Diagram type: `architecture`, `flowchart`, `org`, `all` (default: `all`) | | `--output, -o` | Output directory (default: current directory) | | `--format, -f` | Output format: `mermaid`, `svg`, `both` (default: `mermaid`) | | `--max-files` | Maximum number of files to scan (default: 500) | | `--max-depth` | Maximum depth for org chart (default: 4) | | `--json` | Output analysis results in JSON format | ## How It Works 1. **Scan phase**: Recursively traverse the directory, skipping `node_modules`, `.git`, `__pycache__`, etc. 2. **Parse phase**: - Python files: uses the `ast` module to parse `import` and `from ... import` statements - JS/TS files: uses regex to match `import`, `require`, and `export from` - Go files: uses regex to match `import` statements - Java files: uses regex to match `import` statements 3. **Resolve internal dependencies**: Maps import paths to actual files within the project 4. **Generate diagrams**: Converts dependency relationships into Mermaid diagram syntax 5. **Render (optional)**: Calls `mmdc` (Mermaid CLI) to render `.mmd` files as SVG ## Use Cases - Quickly understand the module structure of an unfamiliar project - Visualize dependencies during code review - Create architecture diagrams for technical documentation - Detect circular dependencies or excessive coupling - Analyze project structure before refactoring ## Dependencies - Python 3.7+ (standard library only, no extra packages needed) - SVG output requires `@mermaid-js/mermaid-cli` (optional) ## Notes - Only analyzes static import relationships; dynamic imports are not tracked - For large projects, use `--max-files` to limit the scan scope - Mermaid diagrams with too many nodes may be hard to render; use `--type` to generate diagrams separately
© zebbern · MIT · zebbern/claude-code-guide
