What makes a good AGENTS.md?

run Claude Cowork from your mobile phone

Mar 19, 2026

AGENTS.md / CLAUDE.md are instruction files that get pre-loaded before your conversation even starts.

Every model has a system prompt - instructions from the model/product makers. Your .md files get added to this. The model now has its system prompt + your instructions pre-loaded.

CLAUDE.md is specific to Claude products. AGENTS.md works across Codex/Droid/Pi/most other tools. You can ‘symlink’ these - ie link my AGENTS.md to CLAUDE.md so that I only ever deal with one set of instructions and any agent will pick it up correctly. (Just ask your agent to symlink them)

What goes into your AGENTS.md?

We previously thought including your tech stack, key files, etc., as like a mini-map for your agent was the right approach. That’s what agents add if they create it.

But there was a study that showed it hurt performance and increased cost by 20% (using extra tokens). The agent can figure out the tech stack, key files, commands, and architecture very easily and quickly.

Instead, it should be pretty empty. It should be your preferences and nudges to correct agent behaviour.

  - When building, open a browser with agent-browser skill and test before sending me a URL (to catch bugs)
  - Use the Exa web search tool for web search
  - Always write planning files in ~/[project-name]/plan/
  - I can't code, so explain things in simple terms
  - Record a video of your output so I can see exactly what you tested

I picked up a tip from Dex, who says wrapping sections in conditional blocks is helpful:

<important if="simple web page">
  - No spec needed
  - Create 3 designs before choosing one
  - Must have dark/light mode switcher
</important>

I often switch between spinning up simple sites and more complex apps. I noticed my agents keep writing specs and testing in the browser, which is unnecessary. So I’m adopting this.

You don’t need to mention skills you’ve installed, as their ‘frontmatter’ (the skills’ name and description) is also pre-loaded alongside your AGENTS.md.

If you’re using ChatGPT/Claude Desktop apps these instructions still work. Paste them in ‘personalisation’ / ‘preferences’ / or ‘instructions’ - in your settings.

AGENTS.md also get dynamically loaded as an agent navigates through folders.

my-project/
├── AGENTS.md              ← root instructions (always loaded)
└── docs/
    └── AGENTS.md          ← loaded when agent works in /docs

If it was helpful, reply and let me know 😊

What am I building this week?

I’m currently in Cardiff doing talks with 16-18 yr olds on starting companies and AI. Making me think I should do proper workshops for these kids.
I just killed my email triage bot. Going to try a different approach. Tried Replit Agent 4, but just did not work. I’ll record a video on this build + Replit review
I’ve been using keep.md to bring all my saved items into one feed (that gets filtered for this newsletter) - and I’m going to make the feed public
I need to cut my AGENTS.md down + add conditional blocks (as above)
I may do a custom ‘claude for chrome’ extension…

Ben’s Bites is brought to you by Viktor

Your next hire isn’t on LinkedIn. Viktor is your last hire. He has his own computer, lives in your Slack, watches how your team works, and starts solving problems before anyone notices them. Writes code. Builds apps. Runs campaigns. No triggers. No workflows. It just works. Try Viktor free, you have $100 up front.*

Headlines

Google launched the new Stitch. They’re calling it your ‘vibe design partner’. Gemini is great at generating UI, unlike other models (ahem, openai), and now paired with their own harness with a bunch of features; AI-native canvas, design agent, voice, instant prototypes, design systems and DESIGN.md (handily links with our intro! Take a look at it 😊 ). Here’s a good overview video of the tool.
Claude launched ‘Dispatch’ for Cowork. Once you connect, you can send messages from your mobile to the Claude Desktop app (i.e. work with files on your desktop). It can also launch Claude Code sessions. I got this working, but I had to approve some permissions on my Mac first (“git” & “claude” would like to access your files). They also published a report: What 81k people want from AI
GPT-5.4 mini is available in ChatGPT, Codex, and the API (5.4 nano available in the API only). Roughly Sonnet 4.6 intelligence, 3x faster and ~70% cheaper. OpenAI also launched a challenge to build the most efficient pretrained model under extreme constraints.
Midjourney’s v8 model is in early testing. It’s 5x faster and better at rendering text, but nowhere near nano-banana. It wins in the aesthetics as always, though.
Runway’s new real-time video generation model created instant HD videos on Nvidia’s Vera Rubin hardware with time-to-first-frame under 100ms.

My feed

AssemblyAI: Real-time STT that keeps up with human conversation. Multilingual with live diarization. Built for voice agents. Start free.*
Unsloth Studio - Open-source web UI to train and run LLMs. Training using your Mac is coming soon.
Lenny put his entire newsletter archive + podcast transcripts into markdown files (which agents love). People have built RPG games, a parenting wisdom site, infographics and more. We should do this for Ben’s Bites data!
A sufficiently detailed spec is code - spoiler: no, it’s not! The argument is that writing a specification detailed enough for an AI to reliably generate code from it becomes as complex as writing the code itself. It also claims that AI-generated specs lack the thoughtfulness that made a specification valuable.
Gamma launched Imagine (visuals, logos, etc), AI-Native templates and connectors.
Browserbase agents get 1000 searches/mo for free with their new Search API powered by Exa AI.
1Password launched ‘Unified Access’ to help agents get access to credentials.
2M people read why we banned React’s useEffect
Will AI kill spreadsheets
The agentic coding flywheel

OpenOats (fka OpenGranola) - A meeting note-taker that talks back
Chops - a skill organiser app - I just downloaded!
Humanoid Atlas shows where all the parts to make humanoid robots come from - pretty cool data visual
Stripe launched the Machine Payments Protocol that lets AI agents programmatically pay for services. And Visa’s Crypto Lab launched a CLI
A mini profile on one of my portfolio founders
OpenAI has a new focus (on the IPO)
How we run a code factory
How to price your AI product