nested-agents-md-author
Generate scoped nested AGENTS.md files at meaningful repo boundaries. Use after scaffold or harness setup when apps, packages, docs, or service directories need local agent instructions without duplic
SKILL.mdskills/nested-agents-md-author/SKILL.md
GitHubNested AGENTS.md Author
Purpose
Add local agent instructions only where directory-specific rules materially improve agent behavior.
Inspect First
- root
AGENTS.md, docs index, architecture boundaries, workspace layout, apps, packages, services, docs, scripts, and existing nestedAGENTS.mdfiles - package manifests, local commands, generated-code areas, ownership rules, and testing conventions
Procedure
Identify meaningful boundaries.
- Use
scripts/suggest_nested_agents.pywhen available. - Prefer boundaries such as
apps/web,apps/server,packages/api,packages/db,packages/ui,services/*, anddocs. - Treat suggestions as scored candidates, not mandatory output. Support packages such as config, env, auth, shared, types, or utils need nested files only when they have local commands, hazards, docs, or existing scoped policy.
- Do not create
AGENTS.mdin every folder.
- Use
Write scoped files.
- Use
assets/templates/nested-AGENTS.md.tmpl. - Link to parent/root
AGENTS.md. - Include only local purpose, read-first docs, local rules, local commands, generated-file warnings, and validation notes.
- Keep detailed architecture/testing/product content in
docs/. - Link local feature, progress, startup, termination, or handoff docs only when that directory owns those artifacts.
- Use
Preserve existing policy.
- If a nested file already exists, inspect and update rather than overwrite.
- Do not contradict root instructions.
- Move broadly applicable rules back to the root
AGENTS.mdor docs.
Add validation.
- Create or update target repo
scripts/check-nested-agents. - Use
scripts/check_nested_agents.pyto detect missing root links, excessive files, and missing local purpose sections. - Use or recommend
check_instruction_snr.pywhen nested files duplicate root rules. - Use
project-local-skill-generatorfor repo-local workflows that are better expressed as triggerable.codex/skillsthan nested directory instructions.
- Create or update target repo
Validation
- Run
./scripts/check-nested-agentswhen present. - Confirm each nested file links upward and has directory-specific value.
- Confirm nested files do not duplicate root command lists or long docs.
Completion Criteria
- Scoped agent instructions exist only at useful boundaries.
- Root
AGENTS.mdremains the repo map. - Nested files are concise, linked, and validation-clean.