# Repo Tour

> Give a structured tour of a GitHub repository — README, entry points, key directories, and recent activity. Use whenever the user asks to "explore", "tour", "summarize", or "understand" a GitHub repo.

- Skill: `subconscious-systems/repo-tour` (Agent Skill)
- Install (CLI): `npx skillmds@latest add subconscious-systems/repo-tour`
- Raw SKILL.md: https://api.skillmd.com/api/skills/subconscious-systems/repo-tour/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Research & Search
- License: Apache-2.0
- Author: subconscious-systems (https://skillmd.com/u/subconscious-systems)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/subconscious-systems/repo-tour

---


# Repo Tour

A guided walkthrough of an unfamiliar GitHub repo. Output a 5-section markdown
report so the reader can decide *what it does*, *how it's built*, *where to start
reading*, *what's active right now*, and *what to watch out for*.

## Steps

1. **Identify the repo.** Parse `owner/name` from the user query. If the user gave
   only a name, ask once for the owner. If they gave a URL, strip to `owner/name`.

2. **Read the README.** Call the GitHub MCP tool to fetch `README.md` from the
   default branch. This is the single highest-value read — do it first.

3. **Map the top-level structure.** List the contents of the root directory.
   Note presence of: `src/`, `lib/`, `app/`, `pkg/`, `cmd/`, `internal/`,
   `tests/`, `docs/`, `examples/`, `scripts/`. Their absence is also a signal.

4. **Read the build/config manifest.** Whichever exists, pick the most authoritative:
   - `pyproject.toml` / `setup.py` / `requirements.txt` (Python)
   - `package.json` (JS/TS)
   - `Cargo.toml` (Rust)
   - `go.mod` (Go)
   - `Gemfile` (Ruby)
   - `pom.xml` / `build.gradle` (JVM)

   Extract: name, version, declared dependencies (top 5–10 only), entry points / scripts.

5. **Find entry points.** Look for `main.*`, `index.*`, `cli.*`, `__main__.py`,
   files referenced under `[project.scripts]` / `"bin"` / `"main"` in the
   manifest. Read one entry-point file end-to-end.

6. **Sample recent activity.** Fetch:
   - The 5 most recent merged pull requests.
   - The 5 most recent open issues.

   Skim titles and short bodies. Look for themes (refactor in progress, breaking
   change brewing, frequently reported bug, large unmerged PR).

7. **Synthesize the report.** Output exactly five sections in markdown:

   ```
   ## What it does
   2–3 sentences. Plain language. No marketing copy.

   ## How it's built
   Language, frameworks, top dependencies, notable architecture choices.

   ## Where to start reading
   1–3 file paths a new contributor should open first, with one sentence each.

   ## What's active
   Themes from recent PRs and open issues. Surface anything unusual.

   ## What to watch
   Risks, gotchas, deprecated paths, pinned issues, unfinished refactors.
   ```

## Stopping rules

- If the README alone answers the user's question, stop after step 2 and report.
- Don't recursively read every file. Sample, don't crawl.
- Hard ceiling: at most ~10 GitHub MCP tool calls per tour. Quality over coverage.

## Tips

- If a directory listing is huge (>50 entries), only read the first page.
- If a file is huge (>1k lines), read just the first ~100 lines.
- Prefer `search_code` over deep traversal when looking for a specific symbol.