vc-scout

Searches codebases with shell tools and parallel agents to locate relevant files.

2|Updated Sep 15, 2025
One-click install
npx skills add https://github.com/marsley01/Marsley-Portfolio-Web --skill vc-scout-marsley01
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: vc-scout
Source: https://github.com/marsley01/Marsley-Portfolio-Web/tree/main/.agents/skills/vc-scout
Command: npx skills add https://github.com/marsley01/Marsley-Portfolio-Web --skill vc-scout-marsley01

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Finding the right files in a large codebase is slow and token-expensive when done manually. This Skill performs fast, scoped codebase scouting using shell search and optional parallel research agents, returning a concise report of relevant files. ## Core Features & Use Cases - Local Shell Scouting: Uses Grep, Glob, and ripgrep patterns to discover files and estimate codebase scale before deeper work begins. - Parallel Agent Delegation: Splits directories across multiple research agents or external Gemini/OpenCode CLI workers when the search space is large. - Structured Scout Reports: Aggregates findings into a deduplicated report listing relevant files with descriptions plus unresolved questions. - Use Case: Before modifying authentication logic spread across src/, api/, and tests/, run a scout to map every auth-related file and its role in under three minutes. ## Quick Start Ask the assistant to scout the codebase and find all files related to authentication, then review the generated scout report.

Frequently Asked Questions about vc-scout

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I find files related to a feature across a large codebase?

Run a scout that parses your prompt for search targets, applies wide Grep and Glob patterns, and optionally splits directories across parallel research agents. Results are aggregated into a report listing relevant files with brief descriptions.

When should I use Gemini CLI instead of internal shell search for code search?

Use Gemini CLI when the scale is 3 or fewer agents and you need large context windows for broad searches. For scale 4-5 use OpenCode CLI, and for scale 6 or more fall back to internal shell scouting with parallel agents.

Can I search a codebase without installing external CLI tools?

Yes, internal scouting is the default mode and relies only on local shell tools like ripgrep, Glob, and Grep. External Gemini or OpenCode tools are optional and only used when installed and explicitly requested.

What happens when a parallel scout agent times out?

Each agent has a 3-minute timeout. Timed-out agents are skipped without restart, logged in the final report's unresolved questions section, and remaining agent results are still aggregated.

How are large files read without exceeding context limits?

Files are chunked at roughly 500 lines per chunk using sed line ranges, keeping reads under a 150K token safe zone. Small files are read directly, while files over 1500 lines are split into multiple parallel chunks.