explain-codebase

🗺️ Explain Codebase

Compatible with Claude Code, Codex CLI, Cursor, Windsurf, and any SKILL.md-compatible agent.

Drop into any unfamiliar repository and generate a complete architectural overview in minutes. Maps directory structure, identifies entry points and frameworks, explains dependencies, and produces a contributor-ready "start here" guide.

---

Triggers

Activate this skill when:

• User drops into an unfamiliar repo and asks what it does
• "explain this codebase", "give me an overview", "what does this project do"
• "architecture overview", "how is this structured", "where do I start"
• "onboarding guide", "explain the code", "map this repo"
• Starting work on a new project or PR
• Before a refactor that needs full system understanding

---

How It Works

Run these exploration commands first, then synthesize into a structured overview.

Phase 1: Recon (run these commands)

# 1. Top-level structure
ls -la

# 2. Directory tree (exclude noise)
find . -type d \
  ! -path './.git/*' \
  ! -path './node_modules/*' \
  ! -path './.venv/*' \
  ! -path './venv/*' \
  ! -path './__pycache__/*' \
  ! -path './dist/*' \
  ! -path './build/*' \
  ! -path './.next/*' \
  | sort | head -80

# 3. Key config files (reveal framework & toolchain)
ls -la *.json *.toml *.yaml *.yml *.lock *.cfg *.ini 2>/dev/null | head -30

# 4. Dependency file contents
cat package.json 2>/dev/null || cat pyproject.toml 2>/dev/null || cat Cargo.toml 2>/dev/null || cat go.mod 2>/dev/null || cat pom.xml 2>/dev/null

# 5. Entrypoints — where does execution start?
grep -r "if __name__.*__main__" --include="*.py" -l 2>/dev/null | head -10
ls -la main.* index.* app.* server.* cmd.* 2>/dev/null

# 6. README and docs
cat README.md 2>/dev/null || cat README.rst 2>/dev/null | head -100

# 7. Docker / deployment clues
cat Dockerfile 2>/dev/null | head -40
cat docker-compose.yml 2>/dev/null | head -40

# 8. CI/CD
ls .github/workflows/ 2>/dev/null
ls .gitlab-ci.yml .circleci/ .travis.yml 2>/dev/null

# 9. Test structure
find . -name "test_*.py" -o -name "*.test.ts" -o -name "*.spec.js" 2>/dev/null | head -20

# 10. Size overview — what's actually big?
find . -type f \
  ! -path './.git/*' \
  ! -path './node_modules/*' \
  ! -path './.venv/*' \
  | xargs wc -l 2>/dev/null | sort -rn | head -20