Skip to main content
If your repository already tells coding agents how to work in it, a session follows that. Scaling reads three kinds of file, and nothing else in your repository is treated as an instruction. A README, a code comment or a file the agent opens is information to the agent, whatever it says.

​
What a session reads

Root guidance. AGENTS.md and CLAUDE.md at the root of the repository are the agent’s standing instructions from the first message. The agent follows them without having to open the file. Guidance in a directory. An AGENTS.md or CLAUDE.md in a subdirectory, such as services/billing/AGENTS.md, is added when the agent first reads or edits a file in that directory, and applies only there. Commands the agent runs in that directory do not add it, so an agent that only runs commands there is not given that guidance. Work in another directory is not affected by it. The session shows a line when it joins: “Following services/billing/AGENTS.md for work in services/billing/”. The first change the agent makes to a file in such a directory is held for a moment so that it is made following that guidance. Guidance is read from at most 64 directories; a repository with more has the rest left out, and the session and settings name them. Skills. A skill is a folder with a SKILL.md, in .claude/skills/<name>/ or .agents/skills/<name>/. Its first lines say what it is called and when to use it.
Every skill’s name and description are given to the agent from the first message. The full text of a skill is loaded only when the agent decides the task matches its description, and the session shows a Load skill line when it does. A skill with no name, or no description, is not listed, and neither is one whose name is longer than 64 characters. If two skills share a name, the first one is kept: those in .claude/skills/ come before those in .agents/skills/. At most 50 skills are listed, and a SKILL.md larger than 64 KB is skipped. A description longer than 1,024 characters is cut at that length. Skill names and descriptions together are limited to about 16 KB, and the text of all listed skills to about 512 KB; a skill that would pass either limit is skipped. A skill the reading did not get to open, because it ran out of time or of file reads, is named as not read. A very large repository, or a slow GitHub, can stop a session from seeing every file. When GitHub cuts its list of files short, or reading takes longer than a few seconds, the session and the project’s settings say that some guidance was not read, rather than that none was found. A repository with none of these files behaves exactly as it did before.

​
Imports

A line that holds only @ and a path, such as @AGENTS.md, imports that file. The path is relative to the file that names it, and it must point to a Markdown file inside the repository. The line itself is not shown to the agent; the imported file’s content is included once, even when two files import each other. A CLAUDE.md that holds only @AGENTS.md therefore gives the agent the content of AGENTS.md. Imports are followed up to three files deep. An import of a file that does not exist is not followed, and the project’s settings list it as not found. Two kinds of @ line are not imports, and the agent receives them as written:
  • a line inside a code fence, such as an example of the syntax in a fenced block
  • a line whose path has a space in it, or is longer than 256 characters
A file that is a link to another file, such as a CLAUDE.md linked to AGENTS.md, is listed, but its text is given to the agent once.

​
Only what is committed on the default branch

A session starts from one commit of your default branch, and it reads guidance as committed there. That commit is shown at the start of the session.
  • Guidance that exists only on another branch, or only as an uncommitted change, is not read.
  • A change the agent makes to AGENTS.md, CLAUDE.md or a skill during the session does not change what it follows in that session, including a new AGENTS.md in a directory it then works in.
  • A change you merge while a session is running is followed from the next session you start.

​
What guidance cannot change

Guidance steers how the agent works. It does not change what the agent is allowed to do.
  • The sandbox, and what it can reach, stay as they are. Only the hosts your admins have approved are reachable, and guidance cannot add one.
  • The agent cannot push to your repository, and guidance cannot give it a way to.
  • You decide whether the agent’s work is published as a pull request. Guidance cannot take that decision away.
If guidance asks for one of these, the agent does not attempt it and tells you what the guidance asked, because it is yours to do.

​
The 32 KB limit

A session takes about 32 KB of guidance files in all, counting root and directory files together.
  1. Root files come first, in this order: AGENTS.md, CLAUDE.md, then what they import.
  2. Guidance in directories is added after, nearest the root first, as long as a directory’s files fit whole. A directory that does not fit is left out entirely, and the agent never reads it as guidance in that session. Directories past the first 64 that have guidance are left out too, and so is a directory with a file over 1 MB or one that could not be read.
  3. If the root files do not all fit, the first one that does not fit in what is left is cut short where the limit ends, and every root file after it is not used. Every directory is then left out. A 20 KB AGENTS.md followed by a 20 KB CLAUDE.md therefore gives the agent all of AGENTS.md and about 12 KB of CLAUDE.md, and both the session and settings say CLAUDE.md is cut short, although neither file is over 32 KB.
A root file, or an import, that is over 1 MB or that GitHub did not return is left out and named. It takes nothing from the limit, and the files after it are still used. Skills do not count towards the limit. The session and the project’s settings both name each file that was left out or cut short. Each list they show stops at 200 entries; a repository with more says so.

​
Where to see what was read

At the start of a session, a line lists the commit, each guidance file that was loaded, each skill listed, and anything left out, skipped or not found. In Settings, open the project and find Agent guidance. It shows the same list for the current head of the default branch, with a warning for each file left out, each skill skipped and each import not found. See Project settings. The list for a session and the list in settings are the same when the session started from that commit.