codebase-summary
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".
Best use case
codebase-summary is best used when you need a repeatable AI agent workflow instead of a one-off prompt.
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".
Teams using codebase-summary should expect a more consistent output, faster repeated execution, less prompt rewriting.
When to use this skill
- You want a reusable workflow that can be run more than once with consistent structure.
When not to use this skill
- You only need a quick one-off answer and do not need a reusable workflow.
- You cannot install or maintain the underlying files, dependencies, or repository context.
Installation
Claude Code / Cursor / Codex
Manual Installation
- Download SKILL.md from GitHub
- Place it in
.claude/skills/codebase-summary/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How codebase-summary Compares
| Feature / Agent | codebase-summary | Standard Approach |
|---|---|---|
| Platform Support | Not specified | Limited / Varies |
| Context Awareness | High | Baseline |
| Installation Complexity | Unknown | N/A |
Frequently Asked Questions
What does this skill do?
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".
Where can I find the source code?
You can find the source code on GitHub using the link provided at the top of the page.
Related Guides
Best AI Skills for Claude
Explore the best AI skills for Claude and Claude Code across coding, research, workflow automation, documentation, and agent operations.
AI Agents for Coding
Browse AI agent skills for coding, debugging, testing, refactoring, code review, and developer workflows across Claude, Cursor, and Codex.
Cursor vs Codex for AI Workflows
Compare Cursor and Codex for AI coding workflows, repository assistance, debugging, refactoring, and reusable developer skills.
SKILL.md Source
# 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
1. Validate `codebase_path` exists
2. Create `output_dir` if needed
3. 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`:
1. Create file at codebase root (not in output_dir)
2. Use `consolidate_target` as filename
3. 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:
1. What was documented
2. Next steps for using documentation
3. How to add index.md to AI assistant context
4. 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`Related Skills
writing-eval-sloptastic
Quantitative framework for detecting AI-generated "slop" in prose through systematic analysis of structural, lexical, rhetorical, and logical patterns. Use when analyzing text authenticity, evaluating writing quality, detecting AI-generated content, or assessing whether prose has characteristic AI patterns like excessive parallelism, abstraction laddering, chiasmus abuse, platitudes, tautologies, or rhetorical overengineering.
validated-knowledge-synthesis
Transform raw, unorganized information into actionable knowledge through systematic validation. Use when users want to synthesize information from multiple sources (documents, URLs, transcripts, notes) into structured knowledge documents. Supports three document types - curated context (default, optimized for recall), guidance (implementation-focused narrative), and reference (quick lookup). Combines convergent synthesis with tension preservation to maintain productive contradictions. Triggers on requests like "synthesize this information", "create knowledge document from these sources", "transform these notes into actionable guidance", or "help me organize this research".
transcribing-youtube
Download and transcribe YouTube videos into clean, deduplicated Markdown documents with chapter headings. Wraps yt-dlp to fetch subtitles (manual or auto-generated), removes the rolling-text triplication artifacts from auto-subs, inserts chapter markers from video metadata, and produces both a timestamped transcript and a prose-only version. Use when the user wants to: (1) transcribe a YouTube video, (2) get a transcript or subtitles from YouTube, (3) create an InfoNugget from a video, (4) extract text from a YouTube URL or video ID, or (5) mentions yt-dlp, YouTube transcript, or video subtitles.
synthesize-knowledge-graph
Transform source materials into K-DAGs (Knowledge DAGs) — modular, curated domain knowledge structured as directed acyclic graphs with typed edges, mermaid visualization, and prose context. Use when users want to build knowledge graphs from documents, synthesize multiple sources into structured ontologies, intersect existing K-DAGs to discover emergent relationships, or create machine-readable knowledge structures that resist context rot. Triggers on: 'build a knowledge graph', 'create a K-DAG', 'intersect these knowledge sources', 'map the relationships between these documents', 'synthesize an ontology from these sources'.
skill-resiliency
This skill should be used when the user asks to "add resiliency to a skill", "make this skill more robust", "improve error handling", "add validation mechanisms", "create self-correcting behavior", or discusses determinism, robustness, error correction, or homeostatic patterns in Agent Skills. Applies biological resiliency principles from Michael Levin's work to Agent Skill design.
prompt-driven-development
Transform rough ideas into detailed design documents with implementation plans. Use when a user wants to develop an idea into a complete specification, create a design document from a concept, plan a feature implementation, or mentions "PDD", "prompt-driven development", "idea to design", "design doc from idea", or wants to systematically refine requirements before building. Guides through requirements clarification, research, detailed design, and implementation planning.
Skill Development
This skill should be used when the user wants to "create a skill", "add a skill to plugin", "write a new skill", "improve skill description", "organize skill content", or needs guidance on skill structure, progressive disclosure, or skill development best practices for Claude Code plugins.
Plugin Structure
This skill should be used when the user asks to "create a plugin", "scaffold a plugin", "understand plugin structure", "organize plugin components", "set up plugin.json", "use ${CLAUDE_PLUGIN_ROOT}", "add commands/agents/skills/hooks", "configure auto-discovery", or needs guidance on plugin directory layout, manifest configuration, component organization, file naming conventions, or Claude Code plugin architecture best practices.
Plugin Settings
This skill should be used when the user asks about "plugin settings", "store plugin configuration", "user-configurable plugin", ".local.md files", "plugin state files", "read YAML frontmatter", "per-project plugin settings", or wants to make plugin behavior configurable. Documents the .claude/plugin-name.local.md pattern for storing plugin-specific configuration with YAML frontmatter and markdown content.
MCP Integration
This skill should be used when the user asks to "add MCP server", "integrate MCP", "configure MCP in plugin", "use .mcp.json", "set up Model Context Protocol", "connect external service", mentions "${CLAUDE_PLUGIN_ROOT} with MCP", or discusses MCP server types (SSE, stdio, HTTP, WebSocket). Provides comprehensive guidance for integrating Model Context Protocol servers into Claude Code plugins for external tool and service integration.
Hook Development
This skill should be used when the user asks to "create a hook", "add a PreToolUse/PostToolUse/Stop hook", "validate tool use", "implement prompt-based hooks", "use ${CLAUDE_PLUGIN_ROOT}", "set up event-driven automation", "block dangerous commands", or mentions hook events (PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification). Provides comprehensive guidance for creating and implementing Claude Code plugin hooks with focus on advanced prompt-based hooks API.
example-skill
This skill should be used when the user asks to "demonstrate skills", "show skill format", "create a skill template", or discusses skill development patterns. Provides a reference template for creating Claude Code plugin skills.