AGENTS.md, memory & skills for Claude

Your agent's rules have sprawled across CLAUDE.md, .cursorrules and walls of text in chat, and a new session still starts "from scratch". The fix isn't one more file - it's a system of 4 layers. 🧩

What it is

The "4-file system" is a setup formula for Claude Code that's popular in videos: split all of the agent's context into 4 roles, each with its own place and its own fate inside the model's window:

• rules - what's always true (in the window every session);
• reference (context) - long docs pulled in by reference;
• memory - what the agent remembered on its own between sessions;
• skills - procedures loaded only on demand.

Below is what this actually looks like officially for Claude (the videos simplify a couple of things).

What the system is made of (4 layers)

1. Rules - CLAUDE.md (and AGENTS.md). Claude Code natively reads CLAUDE.md, not AGENTS.md. If your repo already has an AGENTS.md for other agents - don't duplicate it: import it with the line @AGENTS.md inside CLAUDE.md (or symlink it: ln -s AGENTS.md CLAUDE.md). Keep the file short - aim for < 200 lines, only always-true things. Proof: the official docs.
2. Reference - a context/ folder (a convention, not an official folder). Claude Code has no dedicated context/ folder. Long reference material is moved out of the rules and wired in either through @ imports of the md files you need (up to 4 levels of nesting) or through .claude/rules/ (a rule can be scoped to file paths). "context/" is just a convenient name for a folder you @-import yourself.
3. Memory - MEMORY.md (maintained by the agent itself). Claude Code's auto-memory lives in ~/.claude/projects/<project>/memory/MEMORY.md: the first 200 lines load every session, the details on demand. It's written by Claude, not by you (unlike CLAUDE.md); to view and clean it, use the /memory command.
4. Skills - the .claude/skills/ folder. Each skill is a folder with a SKILL.md (+ scripts, templates); it loads only when needed and is invoked with /skill-name or picked up automatically from its description. The format is the open Agent Skills standard.

How to set it up in 10 minutes

1. Run /init - Claude will assemble a starter CLAUDE.md from your repo (if there's an AGENTS.md next to it, it'll pull that in).
2. Keep only always-true things in CLAUDE.md: build/test commands, conventions, red lines. Move long docs into .claude/rules/ or separate md files and wire them in with @.
3. Noticed you keep repeating the same procedure to the agent? Turn it into a skill: .claude/skills/<name>/SKILL.md.
4. Leave auto-memory on, but open /memory once a week and clear out anything stale.

Why it works

• Context budget by layer: rules are always in the window, while reference, skills and detailed memory come on demand (progressive disclosure). Less "context rot" and fewer burned tokens.
• Portability: AGENTS.md and Agent Skills are open standards (AGENTS.md is used by 60k+ projects, and the format is stewarded by the Agentic AI Foundation under the Linux Foundation), so other agents read them too.
• The end of amnesia: rules + memory give you continuity - a new session doesn't start from zero.

What to watch out for

• The myth that "Claude reads AGENTS.md". It doesn't - it reads CLAUDE.md; AGENTS.md is wired in via an import or a symlink (this is stated right in the official docs).
• context/ isn't magic. Imported files still load into the window at startup: a fat context/ folder bloats context just as much as a fat CLAUDE.md. Move things into .claude/rules/ with path scoping, or into skills.
• Memory carries mistakes too. Auto-memory can lock in a stale or wrong fact and keep repeating it - clean it out periodically. Private data in memory is an extra leak surface.
• Files are context, not a sandbox. Rules don't replace technical restrictions: to hard-block something you need a PreToolUse hook, not a line in CLAUDE.md.
• Someone else's skill is someone else's code. A SKILL.md can pull in scripts: the same supply-chain risk as a package or an MCP server - read the source before installing.