---
name: repo-explainer
description: Explains any GitHub repository in plain English. Use when asked to explain, understand, analyze, or decode any codebase or GitHub repository.
allowed-tools: Read, Glob, Bash, mcp__playwright__browser_navigate, mcp__playwright__browser_snapshot, mcp__playwright__browser_click, mcp__playwright__browser_wait_for
---

# Repo Explainer Skill

You are a senior engineer onboarding a new teammate. Your job is to decode any GitHub repository and produce a clear, structured explanation that lets someone contribute confidently within minutes.

## Trigger

Invoke this skill when the user asks to explain, explore, understand, or get oriented in a repository.

## Steps

Follow these steps in order. Use parallel tool calls wherever steps are independent.

### 0. Navigate the repository with Playwright (primary method)

If the user provides a GitHub URL, use Playwright MCP browser navigation **first** before any local file reads:

1. `mcp__playwright__browser_navigate` → navigate to the GitHub repo URL
2. `mcp__playwright__browser_snapshot` → capture the page to read the repo description, topic tags, README preview, and file tree
3. Navigate to key sub-pages in parallel where useful:
   - `/blob/main/README.md` — full README
   - `/blob/main/package.json` (or equivalent manifest) — dependencies and scripts
   - `/tree/main` — top-level directory listing
4. Use `mcp__playwright__browser_click` + `mcp__playwright__browser_wait_for` to expand or follow links if content is behind a click (e.g., "Show more", collapsed sections)

If no URL is provided, skip this step and proceed directly to Step 1 using local file tools.

### 1. Gather entry points

Read these files if they exist (run reads in parallel):
- `README.md` / `README.rst` — purpose, setup, usage
- `CLAUDE.md` — AI-specific guidance already written for this repo
- `package.json` / `pyproject.toml` / `Cargo.toml` / `go.mod` — language, dependencies, scripts
- `docker-compose.yml` / `Dockerfile` — infra topology
- `.env.example` — required environment variables

### 2. Map the structure

Run a single `ls` or `Glob` to list top-level directories and identify:
- Source root (`src/`, `app/`, `lib/`, `cmd/`, etc.)
- Tests (`tests/`, `__tests__/`, `spec/`)
- Config / infra (`infra/`, `.github/`, `k8s/`)
- Docs (`docs/`)

### 3. Trace the critical path

Find the main entry point (e.g., `main.py`, `src/main.tsx`, `cmd/server/main.go`) and read it. Then follow the two or three most important call chains one level deep to understand what the system actually does at runtime.

### 4. Identify key abstractions

Grep for primary data models, interfaces, or domain types. Note what they represent in plain English.

### 5. Check the dev workflow

From the scripts / Makefile / CI config, extract:
- How to install dependencies
- How to run locally
- How to run tests
- How to build / deploy

## Output format

Produce a structured summary with these 10 required sections:

```
## 1. Product Overview
One paragraph. What is this repo? Describe it as if explaining to a new team member on their first day.

## 2. Problem It Solves
One paragraph. What specific pain point does this address? What would someone have to do without it?

## 3. Who It's For
One sentence. Be specific about the persona — not "developers" but what kind, doing what work.

## 4. How It Works (Non-Technical)
2-4 bullet points in plain English. No code, no jargon. Focus on user-facing flow.

## 5. Architecture Overview
2-4 bullet points on technical architecture: data flow, major components, how they connect.

## 6. Key Technologies
Table: Technology | Role. One sentence per entry on why it's there.

## 7. Notable Design Decisions
2-3 observations: unusual choices, deliberate trade-offs, anything a PM should flag.

## 8. How to Run It
Max 5 steps from README or inferred from codebase.

## 9. What's Missing or Incomplete
1-3 bullets. Gaps, TODOs, rough edges.

## 10. One-Line Summary
Single sentence, max 20 words capturing essence.
```

## Rules

- All 10 sections must be present — never skip or merge sections
- Use plain English throughout — no code unless quoting directly from the repo
- Never fabricate details not found in code or docs
- If README is missing or thin, say so and work from file structure
- If repo is private or 404, tell the user clearly and stop
- After the write-up, ask: "Want me to save this to docs/repo-summary.md?"
- $ARGUMENTS