repo-scout

name	repo-scout
description	Analyze a GitHub repo to understand what it does, extract its best parts, find reusable components, and get actionable usage instructions. Use when the user shares a GitHub URL and wants a practical breakdown.
metadata	{"author":"Big Emotion","version":"2.0.0"}

Repo Scout

Quickly understand a GitHub repo, extract what's valuable — both for .claude/ and for your own projects — and get concrete usage instructions.

When to Activate

• User shares a GitHub repo URL and wants to understand it
• User says "scout this repo", "what does this repo do", "analyze this repo"
• User wants to know what's reusable in a repo
• User asks "what can I steal from this repo"

Input

The skill takes one argument: a GitHub repo URL (e.g., https://github.com/owner/repo). The URL may include extra path segments or query params (e.g. ?tab=readme-ov-file) — strip them and extract owner/repo.

If no URL is provided, ask for one.

Workflow

Step 1: Clone and Explore

1. Extract owner/repo from the URL
2. Clone into /tmp/repo-scout-{repo} using gh repo clone {owner/repo} /tmp/repo-scout-{repo} -- --depth 1
3. If the clone fails (auth, not found), inform the user and stop

Step 2: Read Key Files

Read these files in parallel (skip any that don't exist):

• README.md (or readme.md, README)
• CLAUDE.md
• SKILL.md
• package.json / pyproject.toml / Cargo.toml / go.mod (for metadata + dependencies)
• LICENSE

Then do a structural deep scan:

• ls the root directory
• Glob for **/*.md to find other documentation
• Glob for skill/agent definitions: **/SKILL.md, **/skills/**, **/agents/**, **/.claude/**
• Glob for reusable code: **/components/**, **/utils/**, **/lib/**, **/services/**, **/hooks/**, **/helpers/**, **/middleware/**, **/prompts/**, **/templates/**
• Read key source files that look reusable (utilities, services, core logic) — skim 5-10 files max to understand quality and patterns

Step 3: Analyze and Respond

Produce a structured response with exactly these sections:

## What it does
[2-3 sentence plain-language summary. No marketing fluff. What problem does it solve, for whom.]

## 3 things you need to know
1. **[Thing]** — [concise explanation. Focus on what matters for someone evaluating this repo]
2. **[Thing]** — [architecture, key pattern, or important limitation]
3. **[Thing]** — [maturity, quality, or gotcha worth knowing]

## Reusable parts — what to steal

### For `~/.claude/` (skills, agents, configs)
[List specific files/directories worth copying into .claude/, with exact cp commands.
Focus on: skills, agents, CLAUDE.md snippets, prompts, configurations.
If nothing is worth copying, say "Nothing `.claude/`-specific here." and move on.]

### For your projects (components, utils, patterns)
[List reusable code: components, utilities, services, patterns, middleware, configs.
For each item:]
- **`path/to/file.ts`** — [what it does] — **Why:** [why it's worth reusing over writing your own]

[If the repo has nothing worth extracting, say so honestly. Don't invent value.]

## Use it right now
[One concrete, copy-paste example of using this repo/tool/skill TODAY.
Include the actual command or code. No "you could" — show "do this".
If it's a library: install + minimal usage.
If it's a tool: run command.
If it's a collection of files: exact cp/curl commands.]

## Quick stats
- **Language:** [primary language]
- **License:** [license type — flag if restrictive]
- **Last commit:** [date, from git log --format="%ai" -1]
- **Stars:** [from gh repo view --json stargazerCount]
- **Health:** [Active / Maintained / Stale / Abandoned — based on commit frequency and issue activity]

Step 4: Cleanup

Delete the cloned repo: rm -rf /tmp/repo-scout-{repo}

Rules

1. Be honest. If the repo is abandoned, empty, or low-quality, say so. Don't sugarcoat.
2. Be practical. The user wants to use this today, not read a thesis.
3. Explain "why". For every reusable item, explain why it's worth taking instead of building from scratch.
4. Respect licenses. Flag restrictive licenses (GPL, AGPL) that would limit reuse. Note when MIT/Apache makes copying easy.
5. Read before recommending. Don't recommend a file you haven't actually read. Skim the source to confirm quality.
6. No fluff. Skip filler like "This is an interesting project". Get to the point.
7. Always clean up. Delete the /tmp clone when done.

Examples

/repo-scout https://github.com/anthropics/claude-code-tricks
/repo-scout https://github.com/someuser/awesome-claude-skills
/repo-scout https://github.com/org/some-tool
/repo-scout https://github.com/user/repo?tab=readme-ov-file