codebase-explorer

A Claude Code skill for systematically investigating an existing codebase to extract architectural patterns and implementation details — with findings persisted for long-term reuse.

Built for the workflow of: "I want to build X — let me study how Y does it."

What it does

• Guides Claude through a structured investigation loop: find relevant code → read source → answer concisely → document findings
• Grounds every answer in actual source code with file:line references (no hallucination)
• Persists findings as cross-linked notes for future sessions
• Includes a suggested investigation sequence for AI agent codebases

Output modes

Findings can be saved to three destinations:

Mode	Requires	Best for
obsidian (default)	Obsidian MCP	Personal knowledge bases
notion	Notion MCP	Team wikis
files	Nothing	Any setup, works everywhere

Switch modes at any time during a session: "use Notion", "save to files".

Install

npx skills add https://github.com/marcjaner/codebase-explorer --skill codebase-explorer

Usage

Start an investigation by telling Claude:

Explore this codebase: /path/to/repo
Goal: I'm building an AI agent and want to understand how this project handles memory and tool execution.

Or more casually:

Investigate this repo for me — I want to understand how they handle the agentic loop.

Claude will ask for your output destination, create an investigation index, and begin the topic-by-topic loop.

Suggested investigation topics (AI agent codebases)

1. Agentic loop — how the agent processes a message, calls tools, retries
2. Tool system — how tools are defined, registered, and executed
3. Streaming / feedback — how intermediate results reach the user
4. Short-term memory — session context, compaction, context window management
5. Long-term memory — RAG, vector search, embedding providers
6. Sub-agents / parallelism — spawning, communication, lifecycle
7. Error handling — retry logic, fallbacks, recovery strategies
8. Configuration — how the system is configured and extended

Skill structure

codebase-explorer/
├── SKILL.md                          # Core workflow + output mode selector
├── references/
│   ├── output-obsidian.md            # Obsidian MCP operations
│   ├── output-notion.md              # Notion MCP operations
│   └── output-files.md               # Plain filesystem operations
└── assets/templates/
    ├── index.md                      # Investigation index template
    └── topic-note.md                 # Per-topic deep-dive template

The skill uses progressive disclosure: SKILL.md stays lean, and only the relevant output mode reference is loaded per session.

License

MIT