playbooks

home / skills / jjuidev / jss / scout

scout skill

/.claude/skills/scout

This skill helps you quickly scout large codebases by orchestrating parallel agents to discover files, gather context, and summarize findings.

npx playbooks add skill jjuidev/jss --skill scout

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

Files (3)
SKILL.md
2.6 KB
---
name: scout
description: Fast codebase scouting using parallel agents. Use for file discovery, task context gathering, quick searches across directories. Supports internal (Explore) and external (Gemini/OpenCode) agents.
version: 1.0.0
---

# Scout

Fast, token-efficient codebase scouting using parallel agents to find files needed for tasks.

## Arguments
- Default: Scout using built-in Explore subagents in parallel (`./references/internal-scouting.md`)
- `ext`: Scout using external Gemini/OpenCode CLI tools in parallel (`./references/external-scouting.md`)

## When to Use

- Beginning work on feature spanning multiple directories
- User mentions needing to "find", "locate", or "search for" files
- Starting debugging session requiring file relationships understanding
- User asks about project structure or where functionality lives
- Before changes that might affect multiple codebase parts

## Quick Start

1. Analyze user prompt to identify search targets
2. Use a wide range of Grep and Glob patterns to find relevant files and estimate scale of the codebase
3. Spawn parallel agents with divided directories
4. Collect results into concise report

## Configuration

Read from `.claude/.ck.json`:
- `gemini.model` - Gemini model (default: `gemini-3.0-flash`)

## Workflow

### 1. Analyze Task
- Parse user prompt for search targets
- Identify key directories, patterns, file types, lines of code
- Determine optimal SCALE value of subagents to spawn

### 2. Divide and Conquer
- Split codebase into logical segments per agent
- Assign each agent specific directories or patterns
- Ensure no overlap, maximize coverage

### 3. Spawn Parallel Agents
Load appropriate reference based on decision tree:
- **Internal (Default):** `references/internal-scouting.md` (Explore subagents)
- **External:** `references/external-scouting.md` (Gemini/OpenCode)

**Notes:**
- Prompt detailed instructions for each subagent with exact directories or files it should read
- Remember that each subagent has less than 200K tokens of context window
- Amount of subagents to-be-spawned depends on the current system resources available and amount of files to be scanned
- Each subagent must return a detailed summary report to a main agent

### 4. Collect Results
- Timeout: 3 minutes per agent (skip non-responders)
- Aggregate findings into single report
- List unresolved questions at end

## Report Format

```markdown
# Scout Report

## Relevant Files
- `path/to/file.ts` - Brief description
- ...

## Unresolved Questions
- Any gaps in findings
```

## References

- `references/internal-scouting.md` - Using Explore subagents
- `references/external-scouting.md` - Using Gemini/OpenCode CLI

Overview

This skill performs fast, token-efficient codebase scouting using parallel agents to discover files and gather task context. It targets quick file discovery, structure mapping, and concise reporting so you can decide next steps or start work with a clear view of relevant code.

How this skill works

The skill parses the user prompt to extract search targets and builds Grep/Glob patterns to locate candidate files. It splits the repository into segments, spawns parallel subagents (internal Explore agents by default or external Gemini/OpenCode agents when requested), collects timed summaries from each, and aggregates results into a compact Scout Report.

When to use it

  • When starting a feature that spans multiple directories and you need an orientation
  • If a user asks to find, locate, or search for specific files or functionality
  • At the start of a debugging session to map file relationships and likely hotspots
  • When you need a quick estimate of code scale and areas impacted by a change
  • Before making changes that may touch multiple parts of the codebase

Best practices

  • Provide concrete search targets or example identifiers in the prompt to reduce noise
  • Prefer short, specific patterns (filenames, types, symbols) for faster, more accurate scouting
  • Use the default internal Explore agents for low-latency, token-efficient results; switch to external agents only when needed
  • Limit scope per run for very large repos and increase SCALE progressively
  • Review unresolved questions in the report and follow up with targeted searches

Example use cases

  • Locate all usages of an API endpoint across microservices before refactoring
  • Quickly identify files related to a failing test to narrow debugging scope
  • Map where authentication or config code lives when onboarding a new contributor
  • Estimate how many files and lines will be affected by a cross-cutting change
  • Find implementation and interface files tied to a specific feature name or symbol

FAQ

What agent types are available and when should I switch?

Internal Explore subagents are the default for fast, token-efficient scans; switch to external Gemini/OpenCode when you need specific external tooling or model behavior.

How long does a scout run take?

Each subagent has a 3-minute timeout; overall duration depends on number of subagents and system resources but is optimized for quick returns.