home / skills / lukeslp / dreamer-skills / scout

scout skill

safe

This skill analyzes a new codebase to generate a concise project overview of tech stack, architecture, health indicators, and entry points to inform onboarding.

npx playbooks add skill lukeslp/dreamer-skills --skill scout

Review the files below or copy the command above to add this skill to your agents.

Files (2)

SKILL.md

3.1 KB

---
name: scout
description: "Quick project reconnaissance and codebase analysis. Use when: first encountering a new codebase, onboarding to a project, generating a project overview, checking project health, identifying tech stack, or understanding architecture before making changes."
---

# Scout

Rapidly analyze a codebase and produce a structured overview covering tech stack, architecture, file statistics, health indicators, and entry points. Designed for the first thing you do when encountering a new project.

## Quick Start

```bash
bash /home/ubuntu/skills/scout/scripts/scout.sh /path/to/project
```

The script auto-detects the project type and produces a report covering languages, frameworks, infrastructure, file counts, line counts, directory structure, entry points, and health indicators.

## What Scout Detects

### Languages
Python, TypeScript, JavaScript, Rust, Go, C#, Java, Ruby, Swift — detected by file extension presence.

### Frameworks
Detected from `package.json`, `requirements.txt`, and `pyproject.toml`:

| Category | Frameworks Detected |
|----------|-------------------|
| Frontend | React, Next.js, Vue, Svelte, Tailwind |
| Backend | Express, Fastify, Django, Flask, FastAPI |
| Build | Vite, Webpack, TypeScript |
| ORM | Prisma, Drizzle |
| ML/AI | PyTorch, TensorFlow, Pandas |

### Infrastructure
Docker, GitHub Actions, GitLab CI, Vercel, Netlify, Terraform — detected from config files.

### Health Indicators

| Indicator | Good | Warning | Missing |
|-----------|------|---------|---------|
| README | 20+ lines | Under 20 lines | No file |
| LICENSE | Present | — | No file |
| Tests | Test files found | — | No test files |
| CI/CD | Workflow configured | — | No CI config |
| .gitignore | Present | — | No file |
| .env files | None in repo | Found in repo | — |
| Git activity | Recent commits | — | Not a git repo |

## Workflow

### 1. Run Scout
Execute the script against the project directory. It completes in seconds.

### 2. Read the Report
The report is printed to stdout in a structured format with labeled sections: LANGUAGES, FRAMEWORKS, INFRA, FILE_TYPES, LINE_COUNTS, ENTRY_POINTS, STRUCTURE, HEALTH.

### 3. Dive Deeper
Based on the scout report, decide what to investigate further. Common next steps:

| Scout Finding | Next Action |
|--------------|-------------|
| No tests | Set up test framework |
| Missing README | Use the `docs` skill to generate one |
| .env files in repo | Add to .gitignore, rotate secrets |
| No CI/CD | Set up GitHub Actions |
| Large file count | Run `quality-audit` for deeper analysis |
| Unfamiliar framework | Research with `swarm` skill |

## Use with Other Skills

Scout is designed as the entry point that feeds into other skills:

**Scout → Docs:** Scout identifies the tech stack and structure, then the `docs` skill generates appropriate documentation.

**Scout → Quality Audit:** Scout provides the overview, then `quality-audit` runs deep analysis tools on the specific areas that need attention.

**Scout → Swarm:** If scout reveals unfamiliar technologies, use `swarm` to research them in parallel.

Overview

This skill rapidly inspects a codebase to produce a concise, structured reconnaissance report. It surfaces languages, frameworks, entry points, file and line counts, infrastructure clues, and basic health indicators so you can understand a project fast. Use it as the first step when onboarding or preparing to make changes.

How this skill works

The skill scans the project folder, auto-detecting files and config manifests (e.g., package.json, requirements.txt, pyproject.toml, Dockerfiles, CI configs). It aggregates language and framework signals, counts files and lines, identifies likely entry points and directory structure, and evaluates health indicators like README, tests, CI, and .env exposure. The output is a labeled, human- and machine-friendly report that guides follow-up actions.

When to use it

First time opening a new repository or branch
Onboarding a teammate to quickly map the codebase
Before planning changes or refactors to understand entry points and dependencies
To generate a high-level project overview for stakeholders
To check basic project health (tests, CI, licenses, secrets)

Best practices

Run the scan from the repository root to ensure full coverage
Use the report to prioritize deeper checks (tests, security, performance) rather than as the only audit
Combine scout output with targeted skills (docs, quality audit, security) for remediation
Treat detected .env files or secrets as urgent: remove, rotate, and add to .gitignore
Keep the repository up to date (README, license, CI) so health indicators remain useful

Example use cases

Onboard to a Claude Code plugins repo and get a one-page summary of stack and structure
Pre-PR checklist: confirm entry points, tests, and CI before opening a change
Triage a forked project: detect missing docs, test coverage, or exposed env files
Plan migration or upgrade by identifying frameworks, build tools, and infra configs
Feed the detected stack and entry points into documentation or audit workflows

FAQ

How long does a typical scan take?

Scans complete in seconds for most projects; very large repos take longer but still run quickly.

Does the scanner modify files?

No. The skill only reads files and prints a structured report; it does not change repository contents.