codebase-summary

Original：🇺🇸 English

Translated

2 scriptsChecked / no sensitive code detected

Analyze a codebase and generate comprehensive documentation including architecture, components, interfaces, workflows, and dependencies. Creates an AI-optimized knowledge base (index.md) and can consolidate into AGENTS.md, README.md, or CONTRIBUTING.md. Use when the user wants to document a codebase, create AGENTS.md, understand system architecture, generate developer documentation, or asks to "summarize the codebase".

1installs

Sourcem31uk3/ai-skills

Added on2026-02-08

NPX Install

npx skill4agent add m31uk3/ai-skills codebase-summary

SKILL.md Content

View Translation Comparison →

Codebase Summary

Generate comprehensive codebase documentation optimized for AI assistants and developers.

Parameters

Gather all parameters upfront in a single prompt:

Parameter	Default	Description
`codebase_path`	Current directory	Path to analyze
`output_dir`	`.sop/summary`	Documentation output directory
`consolidate`	`false`	Create consolidated file at codebase root
`consolidate_target`	`AGENTS.md`	Target: AGENTS.md, README.md, or CONTRIBUTING.md
`check_consistency`	`true`	Check for cross-document inconsistencies
`check_completeness`	`true`	Identify documentation gaps
`update_mode`	`false`	Update existing docs based on git changes

Workflow

Step 1: Setup

Validate
```
codebase_path
```
exists
Create
```
output_dir
```
if needed
If
```
update_mode
```
and
```
index.md
```
exists:
- Run
```
git log --oneline -20
```
  to identify recent changes
- Focus analysis on modified components

Step 2: Analyze Structure

Run the structure analyzer:

bash

python {baseDir}/scripts/analyze_structure.py "{codebase_path}" --depth 4 --output "{output_dir}/codebase_info.md"

Run the dependency extractor:

bash

python {baseDir}/scripts/extract_dependencies.py "{codebase_path}" --output "{output_dir}/dependencies.md"

Then manually analyze:

Identify packages, modules, major components
Map architectural patterns (MVC, microservices, etc.)
Find key interfaces, APIs, entry points

Step 3: Generate Documentation

Create these files in

{output_dir}/

:

index.md - Primary AI context file:

AI instructions for using the documentation
Quick reference table mapping questions to files
Table of contents with summaries for each file
Brief codebase overview

architecture.md:

System architecture with Mermaid
```
graph
```
diagram
Layer descriptions
Design patterns used
Key design decisions with rationale

components.md:

Component overview with Mermaid
```
classDiagram
```
Per-component: purpose, location, key files, dependencies, interface

interfaces.md:

API endpoints with request/response formats
Internal interfaces and implementations
Error codes and handling

data_models.md:

ER diagram with Mermaid
```
erDiagram
```
Per-model: table, fields, indexes, relationships

workflows.md:

Key processes with Mermaid
```
sequenceDiagram
```
Step-by-step breakdowns
Error handling

See

{baseDir}/references/documentation-templates.md

for templates.

Step 4: Review

If

check_consistency

:

Verify terminology consistency across documents
Check cross-references are valid

If

check_completeness

:

Identify undocumented components
Note gaps from language/framework limitations

Save findings to

{output_dir}/review_notes.md

.

Step 5: Consolidate (if enabled)

If

consolidate

is

true

:

Create file at codebase root (not in output_dir)
Use
```
consolidate_target
```
as filename
Tailor content to target:

Target	Focus
AGENTS.md	AI context, directory structure, coding patterns, testing
README.md	Project overview, installation, usage, getting started
CONTRIBUTING.md	Dev setup, coding standards, contribution workflow

Default AGENTS.md prompt: Focus on information NOT in README.md or CONTRIBUTING.md—file purposes, directory structure, coding patterns, testing instructions, package guidance.

Step 6: Summary

Report:

What was documented
Next steps for using documentation
How to add index.md to AI assistant context
If
```
update_mode
```
: summarize detected changes

Output Structure

{consolidate_target}           # At codebase root if consolidate=true
{output_dir}/
├── index.md                   # Primary AI context (read this first)
├── codebase_info.md          # Structure analysis output
├── architecture.md           # System architecture
├── components.md             # Component details
├── interfaces.md             # APIs and interfaces
├── data_models.md            # Data models
├── workflows.md              # Key workflows
├── dependencies.md           # Dependencies output
└── review_notes.md           # Review findings

Progress Indicators

Provide updates:

Setting up...
✅ Created {output_dir}

Analyzing structure...
✅ Found X packages across Y languages
✅ Identified Z components

Generating documentation...
✅ Created index.md
✅ Generated architecture.md, components.md...

Reviewing...
✅ Consistency check complete
✅ Found N gaps documented in review_notes.md

Done!
✅ Documentation at {output_dir}
✅ Primary context file: {output_dir}/index.md

Resources

Scripts:

{baseDir}/scripts/analyze_structure.py

,

{baseDir}/scripts/extract_dependencies.py

Templates:

{baseDir}/references/documentation-templates.md