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.