AGENTS.md Generator (Root + Nested, Portable)
Goal
Maintain small, high-signal AGENTS.md files:
-
Root AGENTS.md — purpose of repository, navigation, universal toolchain, canonical commands, links to docs and skills.
-
Nested AGENTS.md — module/package purpose, local commands, module references.
Use progressive disclosure: keep AGENTS.md concise; push details to docs or skills.
Skill location (agent-specific)
-
Do NOT assume .agents/ or any fixed directory exists.
-
Skills may live:
-
inside the repository (embedded),
-
or in an external/global skill library (external).
-
If referencing local skills, first detect an existing skill root already used by the project.
-
If no local skill directory exists — reference skills by name only (external).
-
Never create hidden agent directories just to store skills.
When to run
Run this skill when:
-
AGENTS.md is missing, bloated, contradictory, or outdated.
-
A new package/service/module appears.
-
Repository structure changes (monorepo growth or split).
-
Teams want consistent agent context across diverse stacks.
Workflow (Deterministic)
- Discover repository shape
-
Identify repository root (git root if available).
-
Detect language/tool markers:
-
package.json , pnpm-workspace.yaml
-
go.mod , go.work
-
pyproject.toml
-
Cargo.toml
-
pubspec.yaml
-
pom.xml , build.gradle
-
Locate docs/ , README.md , existing AGENTS.md .
- Detect module boundaries
Create nested AGENTS.md if directory:
-
Contains independent build/package manifest
-
OR represents deployable/service unit (apps/ , services/ , packages/ )
-
AND differs in stack/toolchain from parent scope
- Generate/Update Root AGENTS.md
Constraints:
-
Ideal size: ≤ 60 lines
-
Must include:
-
One-sentence repository purpose
-
Primary toolchain/package manager
-
Canonical commands (if non-standard)
-
Links to docs
-
Instruction to read nested AGENTS.md when inside modules
-
Optional skill references (adaptive: local or external)
- Generate/Update Nested AGENTS.md
Constraints:
-
Ideal size: ≤ 40 lines
-
Must include:
-
One-sentence module purpose
-
Module-specific commands
-
Local documentation references
-
Optional skill references (adaptive)
- Progressive Disclosure Rules
-
Do not embed style guides, CI policies, or architecture details.
-
Prefer links to:
-
docs/STYLE_GUIDE.md
-
docs/ARCHITECTURE.md
-
external or local skills
-
Avoid “always/never” rules unless critical for correctness/security.
- Safety / Correctness Gates
-
Never invent commands.
-
Infer commands from:
-
package scripts
-
Makefile
-
CI configuration
-
README
-
If uncertain → write: “Known commands: see ”
-
Preserve critical warnings (security, secrets, deployment).
Output Contract
Create or update only:
-
<repo_root>/AGENTS.md
-
<module_dir>/AGENTS.md
Do not create agent configuration folders.
Skill Referencing Strategy
When adding skill references inside AGENTS.md:
If local skill directory detected
See: <detected-skill-root>/<skill-name>/SKILL.md
If no local directory exists
Skill: agents-md-generator (external)
Never assume filesystem paths.