# Hs:scout

> Fast codebase scouting using parallel agents. Use for file discovery, task context gathering, quick searches across directories. Supports internal (Explore) agents by default, with an opt-in external Gemini CLI path (consent-gated, off by default).

- Skill: `danielleit241/hs-scout` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add danielleit241/hs-scout`
- Raw SKILL.md: https://api.skillmd.com/api/skills/danielleit241/hs-scout/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: danielleit241 (https://skillmd.com/u/danielleit241)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/danielleit241/hs-scout

---


# 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 when delegation is permitted (`./references/internal-scouting.md`)
- `ext`: Scout using the external Gemini CLI (consent-gated, off by default — see `./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 `search_files` patterns to find relevant files and estimate scale of the codebase
3. Spawn parallel agents with divided directories only when the active runtime permits delegate_agent usage
4. Collect results into concise report

## Runtime Tooling

Use portable capabilities first:

- `search_files` for local discovery.
- `read_file` for scoped file reads.
- `run_shell` for local commands such as `rg`, `wc`, or `sed`.
- `manage_plan` for progress tracking when useful.
- `delegate_agent` for Explore subagents only when user request and runtime policy allow delegation.

Do not spawn subagents only because this skill mentions Explore. Some runtimes,
including Codex Desktop, require the actual user request to explicitly ask for
subagents, delegation, or parallel agent work. If that explicit request is
absent, scout in the main agent with `search_files` and `read_file`.

Runtime mapping for `delegate_agent`:

- Claude Code: use the native delegate call with `subagent_type: "Explore"`.
- Codex Desktop: Explore is a deferred multi-agent role. If `multi_agent_v1`
  is not visible, call `tool_search` for multi-agent spawn tools first, then use
  `multi_agent_v1.spawn_agent` with `agent_type: "Explore"`. Do not set a model
  override; the Explore role owns its runtime model configuration.

## Prerequisites & Environment

Read from `.hs.json`:

| Name | Purpose | Required? |
| --- | --- | --- |
| `skills.scout.useGemini` | Enables the external Gemini CLI path (default: `false`, consent-gated) | Optional — off by default |
| `gemini.model` | Gemini model to use when the external path is enabled (default: `gemini-3-flash-preview`) | Optional |
| `gemini` CLI installed + authenticated | Runs the external scouting path once the consent gate is enabled | Optional — only needed if `useGemini` is `true` |

The kit ships no configuration-value file for this skill — no API keys, no auth tokens. Internal (Explore agent) scouting is the default and needs none of this; users who want the external Gemini path supply their own `gemini` CLI install/auth through their own local setup. See `references/external-scouting.md` and `../_shared/gemini-fallback.md`.

## 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. Register Scout Tasks

- **Skip if:** Agent count ≤ 2 (overhead exceeds benefit)
- **Skip if:** plan/task tracking tools are unavailable — use the local `manage_plan` fallback instead
- `manage_plan capability` first — check for existing scout tasks in session
- If not found, `manage_plan capability` per agent with scope metadata
- Keep task metadata concise: scope, assigned directories, current status, and timeout.

### 4. Spawn Parallel Agents

Load appropriate reference based on decision tree:

- **Internal (Default):** `references/internal-scouting.md` (Explore subagents)
- **External (opt-in, `skills.scout.useGemini: true`):** `references/external-scouting.md` (Gemini CLI)

**Notes:**

- `manage_plan capability` each task to `in_progress` before spawning its agent (skip if plan/task tracking is unavailable)
- 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
- In Codex Desktop, first expose deferred multi-agent tools through `tool_search` if they are not already visible.
- If runtime policy blocks subagents because the user did not explicitly request delegation, continue with main-agent scouting instead of forcing a spawn.

### 5. Collect Results

**IMPORTANT:** Invoke the `hs:project-organization` skill to organize the outputs.

- Timeout: 3 minutes per agent (skip non-responders)
- `manage_plan capability` completed tasks; log timed-out agents in report (skip if plan/task tracking is unavailable)
- 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 the Gemini CLI (consent-gated, off by default)

## Workflow Position

**Typically precedes:** `hs:fix` (debug after scouting), `/hs:fix` (fix after locating code), `hs:code-review` (scout edge cases before review)
**Related:** `hs:fix` (investigate after scouting), `/hs:brainstorm` (explore after scouting)