From tdk-utils
Codebase navigation skill (S4 hierarchical 2-tier). Pre-process a repomix pack via deterministic TS Tier 1 parser, then dispatch the tdk-scout-runner agent (Tier 2) to produce a markdown navigation report (file list + descriptions + unresolved questions). Use for understanding unfamiliar codebases, locating task-relevant files, or pre-processing for downstream skills like tdk-sub-workspace-docs.
How this skill is triggered — by the user, by Claude, or both
Slash command
/tdk-utils:tdk-scout [--scope DIR | --from-pack FILE] [--task-hint STR] [--sample-budget N] [--output PATH] [--force-refresh][--scope DIR | --from-pack FILE] [--task-hint STR] [--sample-budget N] [--output PATH] [--force-refresh]The summary Claude sees in its skill listing — used to decide when to auto-load this skill
Self-contained codebase navigation skill. Trade-off: regex-based Tier 1 (no LLM) gives deterministic, cheap structural extraction; Tier 2 (haiku agent) reads ~10 sampled files to compose human-readable descriptions.
Self-contained codebase navigation skill. Trade-off: regex-based Tier 1 (no LLM) gives deterministic, cheap structural extraction; Tier 2 (haiku agent) reads ~10 sampled files to compose human-readable descriptions.
tdk-sub-workspace-docs) needs structured navigation data.repomix installed globally (npm install -g repomix) — only required for --scope mode.bun (or node) available; tdk TS CLI uses bun src/index.ts.| Flag | Notes |
|---|---|
--scope <DIR> | XOR with --from-pack. Run repomix on DIR. |
--from-pack <FILE> | XOR with --scope. Reuse existing pack file. |
--task-hint <STR> | Optional. Bias file scoring. Default: "general codebase navigation". |
--sample-budget <N> | Optional. Max files for Tier 2 to read. Default: 10. Range: 1-50. |
--output <PATH> | Optional. Default: .specify/cache/tdk-scout/<scope>.md. |
--force-refresh | Optional. Re-run Tier 1 even if cache fresh. |
Locate project root. Run Bash: git rev-parse --show-toplevel. cd there. (Tier 1 cache lives under .specify/cache/tdk-scout/ relative to root.)
Validate args locally for fast failure: at least one of --scope/--from-pack, not both. If invalid, surface error and stop.
Run TS resolver. Use Bash:
bun .specify/scripts/ts/src/index.ts scout <flags>
Capture full output. Stdout will end with one JSON line; stderr carries progress.
Parse contract. From stdout, take the LAST line and JSON.parse it:
{
"packPath": "...",
"tier1JsonPath": "...",
"outputPath": "...",
"taskHint": "...",
"sampleBudget": 10,
"cacheHit": false
}
On non-zero exit OR malformed JSON, surface stderr to the user and stop.
Spawn tdk-scout-runner via Task tool. Use subagent_type: tdk-scout-runner and pass the contract verbatim:
Run the tdk-scout-runner agent.
Contract:
- tier1_json_path: <tier1JsonPath>
- pack_path: <packPath>
- output_path: <outputPath>
- task_hint: <taskHint>
- sample_budget: <sampleBudget>
Read the Tier 1 JSON, score files, sample within budget, and Write the markdown report to output_path.
Verify output. After the agent returns, check outputPath exists. Read the first ~30 lines and surface to the user as a preview. Return the absolute outputPath.
# Scout a sub-workspace with a task focus
/tdk-scout --scope apps/frontend --task-hint "find auth flow"
# Reuse a pack already produced by another skill
/tdk-scout --from-pack .specify/cache/tdk-docs/frontend.md \
--output .specify/cache/tdk-scout/frontend-auth.md \
--task-hint "auth"
# Whole repo with default budget
/tdk-scout --scope .
<outputPath> (default: .specify/cache/tdk-scout/<scope>.md)..specify/cache/tdk-scout/<scope>-tier1.json (regenerable; reusable by other skills).| Condition | What happens |
|---|---|
repomix not installed (scope mode) | TS CLI exits non-zero with install hint; surface to user. |
| Pack file missing (from-pack mode) | TS CLI exits non-zero. |
Both --scope and --from-pack set | TS CLI exits non-zero (mutually exclusive). |
| Tier 2 agent malformed output | The runner agent self-writes a 3-line error report at outputPath; surface that to the user. |
--force-refresh to override.description for downstream auto-routing intentionally mentions the 2-tier architecture so peer skills can decide whether they need full tdk-scout or just the Tier 1 JSON.npx claudepluginhub vinhltt/tdk --plugin tdk-utilsGuides creation, editing, and verification of skills for AI coding agents using test-driven development with subagent scenarios. Use when authoring or debugging skills.