Skip to main content
A README (or index) file is a short note at the top of a folder that explains what the folder is for and where things live. CLAUDE.md and AGENTS.md can instruct supported agents across the workspace; a folder README is a reference for one folder. README.md is not a universal agent-instruction filename. Link important READMEs from CLAUDE.md or AGENTS.md, or point the agent to the relevant file in your prompt.

Why folder READMEs help

  • Agents can use the relevant README when you link or point them to it, so you need less explaining.
  • New teammates get oriented without asking.
  • The folder documents itself, so it stays useful as it grows.

What to put in a folder README

  • What this folder is for, in a sentence.
  • What lives here and how it is organized.
  • Any conventions specific to this folder.
  • Where to go next.

Example

Add READMEs where a folder needs explanation. Here is a slice of a go-to-market workspace in which parent READMEs point to what is below them.
A folder README can list its sub-folders, so an agent or a teammate finds the right one fast:

Set it up across your workspace

You do not have to write these by hand. Give your agent a prompt like this, and it will do the whole tree in one pass while you review before it saves.
To cover folders outside this workspace, add them as references first, then name them in the prompt.

Keeping them current

Ask your agent to update the README when the folder changes, the same way you keep CLAUDE.md and AGENTS.md sharp.