AGENTS.md: the file every AI agent reads first

Every time you start a conversation with an AI, you’re starting from zero. The AI doesn’t remember you. You have to re-explain yourself, your context, your preferences.

AGENTS.md fixes this. It’s a single file that every AI agent reads automatically, before doing anything else. You write it once. Every tool that supports it loads your context instantly, without you pasting or explaining.

Think of it as the brief you’d give a new assistant on day one: “Here’s who I am, here’s how I work, here’s what I expect.”

What goes in AGENTS.md

Your identity and role:

• Who you are (founder, engineer, writer, consultant)
• What you’re building or working on right now
• Your core values and principles

How you prefer to work:

• Your timezone, language, communication style
• What format you prefer (lists vs. prose, concise vs. detailed)
• How you like decisions made (ask first vs. decide for me)
• What tools or platforms you use

Rules and boundaries:

• What to always do (commit and push code, link sources, write summaries)
• What to never do (share API keys, assume you know customer data, make financial trades)
• What requires explicit approval (publishing, sending messages, making decisions)

Links to context:

• Point to your Second Brain (“See my vault at ~/obsidian-vault”)
• Reference your SOPs or documentation
• Link to your [[AGENTS.md|example AGENTS.md file]] so your agent can read how you actually work

Example structure

# AGENTS.md for [Your Name]

## Who I am
I'm [role]. I'm building [what]. My core values: [list].

## How I work
- Time zone: [timezone]
- Language: [language]
- I prefer: [concise/detailed], [lists/prose], [ask me first/decide for me]
- I use: [tools]

## What to always do
- Commit and push code after changes
- Include sources and citations
- Write summaries at the end
- Ask before making irreversible changes

## What to never do
- Use my API keys in files
- Assume you know my customer data
- Make financial or legal decisions
- Publish without my approval

## Context
- My Second Brain: ~/obsidian-vault
- My SOPs: see /docs/SOPs.md
- Current projects: see Projects note in vault

How AI agents use it

When you open Claude Code or any AI agent that supports AGENTS.md, it automatically:

1. Finds the file in your home directory or project folder
2. Reads it before processing your first message
3. Uses it to shape every response
4. Refers back to it throughout the session

You never have to paste it. You never have to repeat yourself. The agent already knows you.

Single source, multiple tools

Different tools look for different filenames:

• Claude Code reads CLAUDE.md
• Codex reads AGENTS.md
• Some custom agents look for .agentrc or similar

Instead of maintaining copies (which drift), create one real file and use symlinks (file pointers) so they all point to the same source.

On Mac/Linux:

ln -s ~/AGENTS.md ~/CLAUDE.md

Now both names point to the same file. Update it once, and both tools see the change.

Common mistakes

Making it too detailed. You write 5 pages because you want to be thorough. But every extra line dilutes the important rules. Keep it to one page. Detailed context goes in your Second Brain.

Not updating it. You write it once in 2025 and forget it exists. Your goals change. Your tools change. Update it when your work changes, so agents see current context.

Mixing personal and professional. If you have deeply personal notes you don’t want AI to read, keep those in a separate private vault. Your AGENTS.md should be professional and shareable.

Not using it everywhere. You set up AGENTS.md but still paste system prompts into ChatGPT. The point is avoiding the paste. Use tools that read AGENTS.md.

Next steps

Write your AGENTS.md today. Start with the template above. Keep it short. Update it when your work changes.

Then, see [[Second Brain in Obsidian]] — your AGENTS.md should point to your Second Brain so agents can access your full context.

Also read [[why SOPs matter before automation]] — good SOPs make your AGENTS.md more effective.