ManySkills/plugins/generate-agents-md/skills/generate-agents-md/references/agents-md-reference.md

AGENTS.md reference

Use for creation, substantial audits, scope changes, or ambiguous commands. Small wording edits can stay in the entrypoint.

Evidence and content selection

Keep facts that change decisions and are costly to rediscover. Verify commands against the relevant package manifest, build file, CI, or maintained contributor docs; state their working directory and required environment. A listed script exists is weaker evidence than a successful run. If running a command requires unavailable services or credentials, disclose that limit instead of claiming validation.

Useful content, when supported:

• A surprising service boundary, generated-file rule, data invariant, or environment trap.
• The shortest relevant setup or verification command and its working directory.
• A task-conditioned pointer to maintained architecture, schema, or release documentation.
• A project-specific completion condition or authorization boundary.

Omit obvious directory inventories, generic advice, redundant style rules enforced by tools, and facts that are readily read from code. Unverified facts belong in the handoff, not a fill-in template. AGENTS.md is ordinary Markdown: headings and length are choices, not correctness criteria.

Scope and loading

Choose one root guide for shared instructions. Add a child guide when its directory has distinct commands or constraints; keep only the local differences. State whether commands run from the repository root or the child directory. Do not duplicate the parent's full text.

Codex discovers instructions at startup. Its documented chain includes the global Codex home and project directories from the repository root toward the current working directory. At each level it selects the first applicable file: AGENTS.override.md, AGENTS.md, then configured fallback names. Later, deeper instructions take precedence for conflicts. An override does not concatenate with AGENTS.md in the same directory. Non-empty files form a combined instruction chain subject to a configurable size limit.

This discovery rule does not guarantee that a newly created child guide will be loaded merely because a running agent edits a file there. Check the target working directory, active session, and host behavior when loading matters. After changing instructions, use a fresh session to verify which files it actually receives; use the target host's current documentation for configuration limits.

Do not claim an AGENTS.md can override system or developer instructions. Preserve explicit user requirements and established authorization. Host-specific rules belong in a compatibility note only when the user asks for that host. For Claude, Cursor, or Copilot migration, check that host's current primary documentation before adding loader files, imports, or symlinks; do not rename or duplicate guides by default.

Editing and boundaries

Preserve the user's valid conventions and language. Remove a rule only when it is obsolete, redundant, contradicted by verified facts, or covered by the requested cleanup. Surface conflicts whose intended resolution cannot be established.

Replace unconditional reading lists with conditions: read architecture notes for service-boundary changes, schema notes for schema work, and release notes for a release. Keep a fixed sequence only where deviation breaks correctness or a fragile operation.

Describe concrete effects and authorization boundaries. Do not add an approval checklist for every dependency, API, CI, or schema edit. State safe autonomous actions only when their safety is verified; a fixture being disposable or a command having no production access must come from evidence. Keep genuinely necessary data, credential, and deployment constraints.

Small examples

These illustrate selection, not a mandatory template:

# Project instructions

Run frontend checks from apps/web with pnpm run check.
Database changes use the transaction rules in docs/database.md.
The schema client is generated; edit its source schema instead.

Only use commands and paths that exist in the target project. Link the real document using a path relative to the guide, and add a child guide only if its local rules justify one.

Mechanical validation

The dependency-free helper checks readable inputs, obvious unfinished prose markers, literal paths and Markdown links, and common package-script commands. It has no fixed heading requirements and never runs a documented command.

• --repo: repository boundary.
• --file: guide path, resolved from the process working directory.
• --local: resolve inline paths and commands from the guide's directory instead of the repository root.
• --cwd: override that inline-path and command base; a relative value is resolved from the repository root. Markdown links still resolve from the guide's directory.
• --warnings-as-errors: optional strict exit status. Ordinary warnings are review prompts.

The command check reads only the nearest applicable package.json within the repository, not every package or dependency tree. It recognizes common npm/pnpm/yarn/bun script forms, rtk wrappers, explicit directory flags, and a simple leading cd. Workspace selectors, pipelines, shell expansion, and complex control flow are reported as unverified when recognized; they are not interpreted as a successful check. Run the appropriate project check separately when execution is authorized and useful.

It does not infer a command's directory from surrounding prose. Use the relevant --cwd or an explicit directory flag when checking that command. A root guide describing several package directories may need manual command checks; a warning is not proof that its instructions are wrong. Ambiguous slash-prefixed routes such as /billing are not treated as filesystem references.

The helper cannot establish command safety, runtime behavior, instruction priority, conflicting prose, or whether the guide improves outcomes. Review those separately. A missing-path warning may refer to a generated artifact; confirm its purpose before changing the guide.

When changing the helper, run its regression suite from this skill directory: python -B -m unittest discover -s tests -p 'test_*.py'.

Behavioral acceptance

For a substantial rewrite, try a representative creation or audit task in an isolated repository. Check that it preserves user constraints, chooses the right scope, uses real commands, avoids invented sections, and gives a usable result. Compare old and new behavior only when both runs were actually captured. Text reduction alone is not evidence of faster or better work.

Sources

Reviewed 2026-09-30. These sources inform the guidance; their examples are not universal requirements.

• OpenAI: Rethinking skills and prompts for GPT-6 Astra, 2026-09-11: precise discovery, progressive disclosure, conditional reading, proportional boundaries.
• OpenAI: Custom instructions with AGENTS.md: Codex discovery and precedence; recheck for host-specific loading questions.
• AGENTS.md: plain Markdown, optional sections, scoped instructions.
• Anthropic: Claude Code best practices: concise persistent context and observed behavior; not a Codex loader specification.
• OpenAI: Testing Agent Skills Systematically with Evals, 2026-01-22: observable outcomes and targeted evaluation.