What a good Agents.md should teach an agent on day one The Agentic AI Foundation, hosted by the Linux Foundation, has standardized AGENTS.md as a plain Markdown file for instructing coding agents in repositories. A developer's experience highlights that effective agent behavior comes from a structured stack of durable instructions, including root AGENTS.md, SOUL.md, USER.md, and TOOLS.md, which define boot order, working posture, and red lines. The key is separating judgment rules from repo-specific mechanics to avoid a 'junk drawer' effect. I hit this last week while working inside my own OpenClaw workspace: the agent had access to the right files, the right tools, and the right project context, but the useful behavior didn't come from any one magic prompt. It came from a small stack of durable instructions. The root AGENTS.md said what to read first. SOUL.md defined the assistant's operating posture. USER.md gave personal context. TOOLS.md separated reusable tool behavior from local machine details. Skill docs explained when to load specialized workflows. That structure has proven useful for me time and time again. AGENTS.md, now part of the Agentic AI Foundation https://aaif.io ecosystem hosted by the Linux Foundation, gives developers a plain Markdown place to tell coding agents how to work in a repo. The format is intentionally simple. The hard part isn't the file. The hard part is deciding what deserves to live in it. A good AGENTS.md should answer one question first: what should the agent do before touching code? In my workspace, the startup path is explicit: SOUL.md USER.md MEMORY.md That gives the agent a boot order. It doesn't need to guess which file matters, whether memory is allowed, or whether private context belongs in a shared chat. Most repo instructions skip this. They say "follow project conventions" and then bury the conventions across a README, package scripts, CI config, old PRs, and comments. An agent can search, but search isn't the same as orientation. Give it a first route through the repo. Your repo probably doesn't need a SOUL.md , but the pattern is useful. One file can define working posture, while AGENTS.md defines project behavior. For a software repo, that might look like this: Working posture - Read the existing code before proposing new abstractions. - Prefer local helpers over new dependencies. - Keep changes scoped to the user request. - Run the narrowest useful test first, then broaden if the change touches shared behavior. Those are judgment rules. They belong near the top because they shape every later decision. Then put repo-specific mechanics somewhere else: Commands - Install dependencies: pnpm install - Run unit tests: pnpm test - Run type checks: pnpm typecheck Why split them? Because commands change faster than principles. If you mix everything together, the file turns into a junk drawer. Agents will still read it, but you won't know which instruction is steering behavior. The best line in my workspace AGENTS.md is short: trash rm . That teaches a local safety rule in three tokens. It says destructive deletion should be recoverable. It doesn't explain Unix philosophy. It doesn't lecture. It gives the agent a rule it can apply while acting. Your AGENTS.md should include boundaries like that: Red lines - Don't edit generated files directly. - Don't change public API behavior without updating tests. - Don't run migrations against shared databases. - Use trash instead of rm when deleting local files. Notice the shape: concrete verbs, concrete objects, concrete limits. "Be careful with data" is too vague. "Don't run migrations against shared databases" gives the agent something it can obey. Agents often fail by reading too little or too much. Repo instructions can fix both. In my workspace, MEMORY.md is only loaded in main sessions, not shared contexts. That's a privacy rule and a context rule at the same time. Daily notes are raw logs. Long-term memory is curated. TOOLS.md is for environment-specific notes, while skills are reusable. That structure avoids a common problem: durable instructions become a dumping ground for every fact anyone might need someday. For a team repo, you can use the same split: Context files - README.md : human setup and project overview. - AGENTS.md : agent workflow and repo norms. - docs/architecture.md : current service boundaries. - docs/runbooks/ : production procedures. Read only when the task touches operations. - .env.example : allowed environment variable names. Never read real .env files unless asked. That last sentence matters. It tells the agent where the map ends. TOOLS.md in my workspace makes a clean distinction: skills define how tools work, and TOOLS.md stores local specifics like camera names, SSH aliases, speakers, or preferred voices. That maps well to engineering teams. A reusable instruction might say: When debugging CI, inspect the failing job logs before changing code. A local instruction might say: The staging dashboard is at