Skip to content

Context engineering: CLAUDE.md, AGENTS.md, skills and memory

Level 3: Connect AI to your tools. About 9 min. Checked on 19 November 2026 against Claude Code memory docs, AGENTS.md (agents.md).
Stage 3 of 4: Connect AI to your tools

In this lesson you'll set up a repository so a coding agent knows how to build, test and follow your conventions, without filling its context.

Your coding agent wrote a migration by hand, again, though your team always uses the generator. It ran the wrong test command. It put the new file in the old folder. None of that is the agent being careless: it simply wasn't told. Every session starts fresh, and the agent only knows what's in its context window, its working memory.

Context engineering is deciding what goes into that window, when. Too little and the agent guesses. Too much and the important rules get lost.

The layers, from always-on to on-demand

Context files: always loaded

A plain Markdown file at the root of your repository that the agent reads at the start of every session.

  • AGENTS.md is an open format, "a README for agents", now stewarded by the Agentic AI Foundation under the Linux Foundation. It has no required fields: just Markdown. Its site lists many agents that read it, including Codex, Cursor, Gemini CLI, GitHub Copilot's coding agent, Jules, VS Code and Windsurf. In a monorepo, nested files apply to their folders, and the closest one to the edited file wins.
  • CLAUDE.md is Claude Code's version. It loads ./CLAUDE.md (or ./.claude/CLAUDE.md) for the project, ~/.claude/CLAUDE.md for your personal preferences everywhere, and ./CLAUDE.local.md for personal notes on one project that you keep out of git. Its docs say Claude Code can also read a repository's AGENTS.md instead.

Skills: loaded when relevant

Instructions for one task, such as "how we write a migration", that the agent loads only when the task comes up. See agent skills.

Memory: written by the agent

Claude Code also keeps an auto memory: notes it writes for itself from your corrections, loaded each session. Check it now and then; a wrong note is repeated just as faithfully as a right one.

What to put where

Context file (every session)

  • How to build, test and lint, with the exact commands.
  • Folder layout and naming rules.
  • The few rules that apply to every change.

Skill (when needed)

  • Step-by-step procedures: a release, a migration, a new endpoint.
  • Long reference material and templates.
  • Scripts the agent should run rather than rewrite.

Claude Code's docs suggest keeping each CLAUDE.md under about 200 lines, because longer files cost more context and are followed less consistently, and note that the more specific and concise your instructions, the more consistently Claude follows them.

A starting file

# Project notes for agents

## Commands
- Install: `npm ci`
- Test: `npm test` (run before every commit)
- Lint and types: `npm run lint && npm run typecheck`

## Conventions
- New database changes: `npm run db:migrate`, never hand-written SQL files.
- Components live in `src/components/<area>/`; one component per file.
- Copy is in sentence case.

## Don't
- Don't edit generated files in `src/__generated__/`.

In Claude Code, /init writes a first CLAUDE.md for you by reading the codebase; refine it with what the agent couldn't discover itself.

In short

  • The agent knows only what's in its context window; you decide what goes in.
  • Context files for every-session rules; skills for procedures; memory for learned habits.
  • Short, specific instructions are followed more reliably than long ones.

What to try next

Share this lesson

Lesson 1 of 1 in this path

Words used in this lesson

Sources

Official documentation, checked on 19 November 2026. Products change: if a step differs, the source has the current version.

Get the next lesson

New Academy lessons are announced in the weekly AI-Powered email.