# Code Explanation

Generate a complete, beginner-friendly explanation of an entire code repository as a...

- Repository: https://github.com/Leanmcp/gateway-skills (2122 stars)
- Category: Engineering
- License: MIT
- Last updated: 2026-10-07
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add Leanmcp/gateway-skills --skill code-explanation -g -a claude-code -y`
Codex: `npx skills add Leanmcp/gateway-skills --skill code-explanation -g -a codex -y`
Cursor: `npx skills add Leanmcp/gateway-skills --skill code-explanation -g -a cursor -y`
Gemini CLI: `npx skills add Leanmcp/gateway-skills --skill code-explanation -g -a gemini-cli -y`

## Description

Generate a complete, beginner-friendly explanation of an entire code repository as a set of markdown files. Maps the repo structure with `treecap` (installing it if missing), studies the actual source, then writes a `CODE_EXPLANATION/` folder containing an `OVERVIEW.md` plus numbered deep-dive files (01_architecture.md, 02_models.md, ...) that explain how the code is built, what it does, and how the pieces fit together, illustrated with real code excerpts. Use this skill whenever the user wants to understand, document, onboard onto, or get a walkthrough of a codebase: phrases like "explain this repo", "explain the code", "code explanation", "walk me through this codebase", "help me understand how this is built", "document the architecture", or "what does this project do", even if they don't say the word "skill". Prefer this over ad-hoc summaries whenever the goal is a durable, written explanation of a whole repo.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Code Explanation

Produce a thorough written explanation of an entire repository so someone new
can understand **what it does, how it is built, and how the pieces fit
together**. The output is a `CODE_EXPLANATION/` folder of markdown files: one
`OVERVIEW.md` and a series of numbered deep-dive documents.

The goal is genuine understanding, not a file inventory. A good explanation
reads like a knowledgeable engineer walking a new teammate through the codebase:
it names the important abstractions, shows real code, and explains *why* things
are shaped the way they are.

## Workflow

### 1. Establish the structural map with `treecap`

Before reading any code, get a bird's-eye view of the repo layout. Use
`treecap`, a tree viewer that caps how many entries it shows per folder so large
repos stay readable.

Resolve the tool in this order:

1. **`treecap`**, preferred. Check with `which treecap`.
2. If it is missing, **install it**: `pip install treecap` (it is a PyPI
   package: https://pypi.org/project/treecap/). If `pip` isn't available, try
   `pip3 install treecap` or `python -m pip install treecap`.
3. If installation fails or is declined, **fall back to `tree`**
   (`which tree`).
4. If neither exists, fall back to a manual listing (e.g. `find . -type f`
   filtered sensibly), but prefer the real tools.

Run it on the target repo. Sensible defaults:

```bash
treecap -W 0 -L 3        # full width (all entries), 3 levels deep
```

`-W` caps entries shown per directory (`0` = unlimited; the default is 5).
`-L` caps display depth. Start broad, then re-run deeper or with a higher width
on the directories that turn out to matter (e.g. `treecap src -W 0`). `treecap`
skips `.git`, `node_modules`, `__pycache__`, and `.venv` by default, which is
usually what you want.

Capture this tree, you'll embed a trimmed version of it in `OVERVIEW.md`.

### 2. Read the code and build a mental model

The rest: https://github.com/Leanmcp/gateway-skills/blob/HEAD/skills/code-explanation/SKILL.md