where-claude

name

where-claude

description

Scan the current repository and recommend which directories deserve their own nested CLAUDE.md file (i.e. where to run /init), as a ranked report with a one-line rationale per directory. Global and project-agnostic. Does NOT generate the files - it tells you where /init is worth running. Trigger when the user says "where should I run /init", "which directories need a CLAUDE.md", "where-claude", "scout claude.md placement", or "find nested CLAUDE.md candidates".

Where to run /init (nested CLAUDE.md placement scout)

Project-agnostic, global skill. It scans the current repo and reports the directories that would most benefit from their own nested CLAUDE.md, ranked, each with a one-line reason. It does not create the files - it removes the guesswork of deciding where /init is worth running.

It pairs with /init: /init writes a CLAUDE.md for a directory; this skill decides which directories are worth that cost.

Why nesting matters (the model that drives every decision)

Claude Code auto-loads the CLAUDE.md in the cwd and its parent directories, and pulls in a nested CLAUDE.md on demand only when work happens inside that subtree. So a nested file is cheap (loaded only when relevant) but only earns its keep when the subtree has local context a parent file does not already supply. Two failure modes to avoid:

• Over-placement: a CLAUDE.md in every folder = duplicated/contradictory context and maintenance burden. Most directories should NOT get one.
• Redundant placement: recommending a child when its parent already covers it.

Bias to restraint: a few high-value placements beat a long list.

Scoring heuristic (what makes a directory a candidate)

Score each directory on these signals; recommend only those that clearly clear the bar.

Positive signals (raise the score):

• Module boundary - has its own manifest: package.json, pyproject.toml, setup.py, go.mod, Cargo.toml, *.csproj, pom.xml, build.gradle, etc.
• Distinct stack / conventions - different language, framework, build tool, or test runner than the repo root (e.g. a frontend/ in TS under a Python root).
• Local config - its own lint/format/test/CI config, codegen, or fixtures that imply rules specific to this subtree.
• Size / depth - enough source files that context would otherwise be re-derived on each visit (rough floor: ~15+ source files, or a clearly self-contained component).
• Architectural seam - a top-level services/<x>, packages/<x>, apps/<x>, cmd/<x> in a monorepo; a bounded domain module.

Negative signals (disqualify or skip):

• Generated / vendored / dependency dirs: node_modules, dist, build, out, vendor, .venv, target, __pycache__, .next, coverage, anything git-ignored.
• Tiny leaf dirs, asset-only dirs, or dirs already fully covered by a parent CLAUDE.md.
• The repo root itself if it has no CLAUDE.md - note that as a prerequisite, but the root is /init's normal job, not a "nested" recommendation.

Procedure

1. Orient

• Find existing CLAUDE.md files (find . -name CLAUDE.md -not -path '*/node_modules/*') so you never recommend one that already exists or is covered by a parent.
• Read the root CLAUDE.md/README* to learn what the root file already documents - a subtree only needs its own file for what the root does NOT cover.
• Map the directory tree (respecting .gitignore) and locate manifests/config files that mark module boundaries.

2. Score

• Apply the heuristic above to each candidate directory.
• Collapse redundancy: if a parent and child both qualify, prefer the parent unless the child has genuinely distinct local context (then both, noting the relationship).
• For a large or unfamiliar repo, delegate the directory sweep to the Explore agent and score from its summary, to keep context clean.

3. Report (do NOT create files)

Present a SHORT ranked list - the highest-value placements first. For each:

• the directory path;
• a one-line rationale (which signals fired);
• a copy-pasteable command, e.g. cd <dir> && claude then /init, or just note the /init target. Then a "Skipped / not worth it" section naming notable directories you deliberately left out and why (generated, covered by parent, too small). If the root lacks a CLAUDE.md, flag that first as the prerequisite.

4. Hand off

• Let the user pick which directories to act on; /init must be run per-directory by the user (it documents the cwd it runs in). Do not auto-run /init or write any CLAUDE.md yourself.

Guardrails

• Report only; never create, edit, or auto-/init any CLAUDE.md.
• Never recommend a directory already covered by an existing or parent CLAUDE.md.
• Respect .gitignore and always exclude generated/vendored/dependency directories.
• Keep recommendations few and honest; push borderline dirs into "Skipped" rather than padding the list.
• Never fabricate repo facts - base every rationale on files you actually observed.