Where Agents Md

---
name: where-agents-md
description: Scan the current repository and recommend which directories deserve their own scoped Codex AGENTS.md or AGENTS.override.md instruction file, as a ranked report with one-line rationales. Does not generate files. Trigger when the user says "where should AGENTS.md go", "which directories need AGENTS.md", "where-agents-md", "scout AGENTS.md placement", "find nested AGENTS.md candidates", or "where should Codex instructions live".
---

# Where To Place AGENTS.md

Recommend high-value locations for scoped Codex instruction files. This skill reports
only; it does not create or edit files.

## Placement Model

Codex reads `AGENTS.md` instruction files as project guidance. Nested files should be
used only when a subtree has meaningful local conventions that the parent file should
not carry.

Use `AGENTS.md` for shared project guidance. Use `AGENTS.override.md` only when the user
explicitly wants a local override pattern and the repo already uses that convention.

## Scoring Heuristic

Recommend a directory only when it clearly clears the bar.

Positive signals:

- Module boundary: its own `package.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`,
  `*.csproj`, `pom.xml`, `build.gradle`, or similar manifest.
- Distinct stack or conventions: different language, framework, build tool, formatter,
  test runner, deployment target, or safety constraint from the parent.
- Local config: its own lint, format, test, CI, codegen, fixtures, or tooling rules.
- Size/depth: enough source files that context is repeatedly re-derived.
- Architectural boundary: `apps/<x>`, `packages/<x>`, `services/<x>`, `cmd/<x>`, or a
  bounded domain module in a monorepo.

Negative signals:

- Generated, vendored, dependency, virtualenv, cache, coverage, or git-ignored dirs.
- Tiny leaf dirs, asset-only dirs, fixtures-only dirs, or directories already covered by
  a parent instruction file.
- The repo root when it lacks `AGENTS.md`; report that as a prerequisite, not a nested
  recommendation.

## Procedure

### 1. Orient

- Find existing instruction files:
  `find . \( -name AGENTS.md -o -name AGENTS.override.md \) -not -path '*/node_modules/*'`
- Read root `AGENTS.md`, `CLAUDE.md` if present, and `README*` to understand what is
  already documented.
- Map manifests/configs and respect `.gitignore`.

### 2. Score

- Apply the heuristic to each candidate directory.
- Collapse redundancy: prefer the parent unless the child has genuinely distinct local
  context.
- For a large repo, delegate broad directory exploration to a read-only subagent when
  available and score from its summary.

### 3. Report

Return a short ranked list. For each recommendation include:

- directory path;
- recommended file name, usually `AGENTS.md`;
- one-line rationale naming the strongest signals;
- whether it should supplement or replace parent guidance.

Add a "Skipped / not worth it" section for notable directories you intentionally left
out and why.

## Guardrails

- Report only; never create, edit, or auto-generate instruction files.
- Never recommend a directory already covered well by an existing or parent
  `AGENTS.md`.
- Respect `.gitignore` and exclude generated/vendor/dependency directories.
- Keep recommendations few and evidence-based.