| 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.
