Agent skill

codebase-map

Generate a structural overview and dependency diagram of the codebase. Use when the user wants to understand codebase structure, visualise architecture, or says "/codebase-map".

View SKILL.md on GitHub Repository
Stars 0
Forks 0

Install this agent skill to your Project

npx add-skill https://github.com/josh-gree/my-claude-skills/tree/main/skills/codebase-map

SKILL.md

Codebase Map

Generate a structural overview and dependency diagram of the current codebase.

Purpose

This skill produces a clear visual and textual representation of codebase structure, helping developers understand:

  • How directories and modules are organised
  • What each major component does
  • How modules relate to and depend on each other

Prerequisites

  • Git remote must exist (maps should be for projects with remotes)
  • No requirement for clean working tree (read-only operation)

When to Use

Use this skill when you want to:

  • Understand an unfamiliar codebase
  • Document project architecture
  • Onboard new team members
  • Visualise module dependencies
  • Get a high-level overview before diving into code

Workflow

Step 1: Verify Environment

Check we have a GitHub remote:

bash
git remote -v

STOP if:

  • No remote exists → "This skill requires a GitHub remote. Codebase maps are intended for projects with remotes."

Step 2: Explore the Codebase

Use the Task tool with subagent_type: "Explore" for thorough codebase exploration:

Tool: Task
Parameters:
  subagent_type: "Explore"
  description: "Explore codebase structure for mapping"
  prompt: |
    Explore this codebase to understand its structure and organisation.

    Identify:
    - Top-level directory structure and purpose of each directory
    - Entry points (main files, CLI entry points, server start files)
    - Key modules/packages and their responsibilities
    - Import relationships between modules
    - Configuration files and their purposes
    - Test structure and organisation
    - Build/deployment files

    For each significant directory:
    - What it contains
    - What purpose it serves
    - What depends on it / what it depends on

    Use thoroughness level: "very thorough"

    Return:
    1. Complete directory tree with annotations
    2. List of entry points
    3. Module dependency relationships
    4. Key configuration files

Step 3: Generate Structure Overview

Produce a hierarchical markdown overview of the codebase structure.

Format:

## Structure Overview

project-root/
├── src/                    # Main source code
│   ├── components/         # UI components
│   ├── services/           # Business logic and API calls
│   └── utils/              # Shared utilities
├── tests/                  # Test files mirroring src structure
├── config/                 # Configuration files
└── scripts/                # Build and deployment scripts

Guidelines for annotations:

  • Keep descriptions short (3-8 words)
  • Focus on purpose, not contents
  • Only annotate significant directories
  • Use consistent terminology

Step 4: Identify Key Files

List the most important files in the codebase with brief descriptions:

Format:

## Key Files

| File | Purpose |
|------|---------|
| `src/index.ts` | Application entry point |
| `src/config.ts` | Configuration loading and validation |
| `package.json` | Dependencies and scripts |

Include:

  • Entry points
  • Main configuration files
  • Core modules that others depend on
  • Files that define key abstractions

Step 5: Generate Dependency Diagram

Create a mermaid diagram showing module relationships.

Format:

mermaid
graph TD
    A[Entry Point] --> B[Core Module]
    A --> C[Config]
    B --> D[Utils]
    B --> E[Services]
    E --> F[External APIs]

Guidelines:

  • Show major modules, not individual files
  • Group related functionality
  • Indicate direction of dependency (arrow points from dependent to dependency)
  • Keep diagram readable (10-20 nodes maximum)
  • Use clear, short labels

Diagram types by project:

  • Simple projects: Single graph TD showing module relationships
  • Layered architectures: Show layers with subgraphs
  • Microservices: Show service boundaries and communication

Step 6: Add Project-Specific Context

Include relevant context based on project type:

Python projects:

  • Package structure (__init__.py locations)
  • Virtual environment setup
  • Entry points from pyproject.toml or setup.py

JavaScript/TypeScript projects:

  • Module system (CommonJS vs ESM)
  • Build output locations
  • Package manager (npm, yarn, pnpm)

Multi-language projects:

  • Language boundaries
  • Inter-language communication
  • Build coordination

Step 7: Compile Final Output

Combine all sections into the final output.

Output Format

# Codebase Map: [project-name]

## Summary

[2-3 sentences describing what this project is and its primary purpose]

## Structure Overview

[Hierarchical directory tree with annotations]

## Key Files

| File | Purpose |
|------|---------|
| ... | ... |

## Module Dependencies

[Mermaid diagram]

## Entry Points

- **Main**: `path/to/main` - Description
- **CLI**: `path/to/cli` - Description
- **Tests**: `path/to/tests` - Description

## Notes

[Any additional context: conventions, patterns, gotchas]

Guidelines

DO:

  • Focus on structure and relationships, not implementation details
  • Use consistent terminology throughout
  • Keep annotations brief and informative
  • Show what matters most (entry points, core modules)
  • Tailor output to the project type
  • Make the diagram readable (simplify if needed)

DON'T:

  • List every single file
  • Include generated or build output directories
  • Add implementation details to annotations
  • Create overly complex diagrams
  • Speculate about purpose when unclear

Handling Different Project Types

Python Package

mypackage/
├── src/mypackage/      # Package source
│   ├── __init__.py     # Package initialisation
│   ├── core.py         # Core functionality
│   └── cli.py          # Command-line interface
├── tests/              # Test suite
├── pyproject.toml      # Project metadata and dependencies
└── README.md           # Documentation

JavaScript/Node.js

myproject/
├── src/                # Source files
│   ├── index.js        # Entry point
│   └── lib/            # Library code
├── dist/               # Build output (generated)
├── test/               # Tests
├── package.json        # Dependencies and scripts
└── tsconfig.json       # TypeScript config (if applicable)

Django Project

myproject/
├── myproject/          # Project settings
│   ├── settings.py     # Django settings
│   ├── urls.py         # URL routing
│   └── wsgi.py         # WSGI entry point
├── apps/               # Django applications
│   ├── users/          # User management
│   └── api/            # API endpoints
├── manage.py           # Django management script
└── requirements.txt    # Dependencies

Example Output

# Codebase Map: my-claude-skills

## Summary

A collection of Claude Code skills for automating development workflows. Skills handle tasks like ticket management, code review, and project setup.

## Structure Overview

my-claude-skills/
├── skills/                 # Individual skill definitions
│   ├── create-ticket/      # GitHub issue creation
│   ├── plan-ticket/        # Implementation planning
│   ├── implement-ticket/   # Ticket implementation
│   ├── review-pr/          # Pull request review
│   └── ...                 # Other skills
└── README.md               # Project documentation

## Key Files

| File | Purpose |
|------|---------|
| `skills/*/SKILL.md` | Skill definition and instructions |
| `README.md` | Usage documentation |

## Module Dependencies

```mermaid
graph TD
    CT[create-ticket] --> PT[plan-ticket]
    PT --> IT[implement-ticket]
    IT --> RP[review-pr]
    IT --> W[worktree]

Entry Points

  • Skills: Individual SKILL.md files invoked via /skill-name

Notes

  • Skills are symlinked to ~/.claude/skills/ for activation
  • Each skill follows a standard YAML frontmatter format
  • Skills can reference other skills in their workflows

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

josh-gree/my-claude-skills

implement-ticket

Implements a planned GitHub issue by following the implementation plan. Takes a GitHub issue number. Use when the user wants to implement a ticket, work on an issue, or says "implement ticket X" or "do issue

0 0
Explore
josh-gree/my-claude-skills

address-pr-comments

Addresses PR review comments by making code changes and posting replies. Takes a PR number or auto-detects from current branch. Use when the user wants to address review feedback, respond to PR comments, fix PR feedback, or says "address comments on PR X".

0 0
Explore
josh-gree/my-claude-skills

create-ticket

Creates GitHub issues to capture work that needs to be done. Records intent with context about the codebase, not implementation plans. Use when the user wants to track work, create a ticket, log a task, or says "we want to do X" or "we need to X".

0 0
Explore
josh-gree/my-claude-skills

review

Review code using Google's code review principles. Use for ad-hoc file review or as the foundation for PR and codebase reviews.

0 0
Explore
josh-gree/my-claude-skills

setup-python-lib

Sets up a new Python library project using uv in the current directory. Creates project structure, installs dev dependencies, and optionally configures git remote. Use when the user wants to initialise a Python library, package, or project with uv.

0 0
Explore
josh-gree/my-claude-skills

refine-plan

Refines an existing implementation plan through discussion with the user. Takes a GitHub issue number. Use when the user wants to refine a plan, discuss a plan, change a plan, or says "refine plan X" or "let's discuss the plan for issue

0 0
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results