[forgotusername6]

Interesting that they had a 100% read rate of agents.md. In my test repo lower down agents.md files were occasionally missed by vscode copilot. That fact put me off putting too much effort into nesting agents.md files too much within the repo and I've been focusing on agent skills instead.

[lelandbatey]

The 100% read rate is very harness/CLI dependent. The "original" idea for AGENTS.md was: the AGENTS.md file will be included as-is in the system prompt by the harness, so the agent doesn't have any choice in whether it'll be read or not. For example, this is a shortened form of what opencode sends as a system prompt for a new session when interacting with a provider (displayed in YAML for formatting, and edited for formatting):

    model: foo-model
    max_tokens: 32000
    top_p: 1
    messages:
      - role: system
        content: |
          You are opencode, an interactive CLI tool that helps users with software engineering tasks.
          Use the instructions below and the tools available to you
          # ... snip ...
          Here is some useful information about the environment you are running in:
          <env>
            Working directory: /home/user/dir
            Workspace root folder: /
            Is directory a git repo: no
            Platform: linux
            Today's date: Tue Apr 28 2026
          </env>
          Skills provide specialized instructions and workflows for specific tasks.
          Use the skill tool to load a skill when a task matches its description.
          No skills are currently available.
          Instructions from: /home/user/dir/AGENTS.md
          # Overview
          This directory holds the entirety of the code for the <dayjob> company. All code lives in Github
          under the `<dayjob>` organization, and beneath that Organization is a wide-and-flat set of all
          the Git repositories of all source code at <dayjob>. That Github repo structure is replicated in
          this directory via `ghorg`.

My AGENTS.md file contents start at the "# Overview" line.

Notice that the harness is just unceremoniously dumping the AGENTS.md file into the exact same text stream as the system prompt, barely contextualizing that hey, starting now, this text is from AGENTS.md and not from the harness.

If you want AGENTS.md to work (likewise, if you want skills or anything else to work) you have to know how the harness is handling/feeding them to the LLM, because no LLM will reliably look on their own.

[weiliddat]

This is more a harness thing signaling the presence or forcing a read on AGENTS/CLAUDE.md right?

[stavros]

Yes it is, the main feature that differentiates AGENTS.md from other files is that the former is usually loaded into the context automatically.

[qingcharles]

I often start a new session with tagging AGENTS.md in the prompt just to make sure because I've had the same issue happen a couple of times.

[postalcoder]

Try a prompt like this: https://news.ycombinator.com/item?id=46809708#46821569 (first-person, exploratory prompting)

It has worked well for me. I have since put this into my AGENTS.md:

  I will check for the presence of `AGENTS.md` files in the workspace. When working in a subdirectory, I will check whether that subdirectory has its own `AGENTS.md` and follow its narrower instructions.