codebase-analysis

What it does

The skill executes a 3-phase workflow to analyze a codebase: Deep Analysis, Reporting, and Post-Analysis Actions. It accepts an optional analysis-context and uses a deep-analysis workflow to explore and synthesize findings, then presents a structured report with an Architecture Overview, Tech Stack, Critical Files, Patterns & Conventions, Relationship Map, Challenges & Risks, Recommendations, and Analysis Methodology. It can load and use a Mermaid diagram guidance from the technical-diagrams skill for architecture visuals, and it proceeds to Phase 3 actions like saving reports or updating project documentation. Phase 3 also includes an Actionable Insights workflow to extract high/medium/low severity items from the Phase 2 report, delegate fixes to code-architect or code-explorer agents when needed, and summarize results, before concluding the workflow. The skill requires dependencies: deep-analysis and technical-diagrams, and declares tools: claude-code.

How it works

• Phase 1 Deep Analysis: Determines analysis context (defaults to general codebase understanding if not provided). Checks for an exploration cache manifest at .agents/sessions/exploration-cache/manifest.md and validates cache based on codebase_path and timestamp within a 24-hour TTL. If valid, offers Use cached results or Run fresh analysis. If no valid cache, proceeds to Run deep-analysis workflow using the provided analysis context and sets CACHE_TIMESTAMP to null after completion. After deep analysis, records metadata including whether results were cached (CACHE_HIT), cache timestamp (CACHE_TIMESTAMP), and number of explorer agents used.
• Phase 2 Reporting: Loads diagram guidance from technical-diagrams for Mermaid diagrams. Uses the provided report template to structure the presentation with sections: Executive Summary, Architecture Overview, Tech Stack, Critical Files, Patterns & Conventions, Relationship Map, Challenges & Risks, Recommendations, and Analysis Methodology. Proceeds to Phase 3 without waiting for user input.
• Phase 3 Post-Analysis Actions: Allows the user to Save Codebase Analysis Report, Save a Custom Report, Update Project Documentation, or Keep Insights in Memory. Each action has detailed steps for file location prompts, generation, and saving. Includes an Actionable Insights workflow (Steps 3a–3d) to extract and process items from the Phase 2 report, delegating to a code-architect or code-explorer when needed, presenting proposals, awaiting user approval, and summarizing results. Concludes with Step 4 completing the workflow.

When to use it

Use when asked to analyze, explore, understand, map, get an overview, audit, or assess how a codebase is structured. The workflow anticipates typical prompts for codebase analysis and maintains an explicit context and caching strategy to optimize repeated analyses.

What it can touch

The skill references tools: claude-code and relies on the deep-analysis and technical-diagrams capabilities for exploration, synthesis, and Mermaid diagram guidance. It interacts with the project repository paths for creating and saving reports and documentation under internal/docs or project root, generating Markdown files as outputs.

Caveats

• Requires dependencies: deep-analysis and technical-diagrams.
• Uses caching with a default TTL of 24 hours; behavior depends on cache validity.
• Post-Analysis Actions may prompt for file paths and may create or modify files under the project root or internal/docs depending on user choices.
• Actionable Insights processing may delegate to code-architect or code-explorer agents; fallback is direct investigation if delegation fails.