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

Level 3: Connect AI to your tools · 9 min · Updated 19 November 2026 · Path: Code with AI agents

By the end 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](https://ai-powered.com/academy/glossary/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](https://ai-powered.com/academy/agent-skills/agent-skills-install-and-write).

### 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

```markdown
# 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.

**Watch out**

Context files are context, not enforcement. Claude Code's docs are explicit that it treats them as instructions, not configuration; to block an action whatever the agent decides, they point to hooks. Never rely on a line in a Markdown file to protect production.

**Try it**

Add an AGENTS.md (or CLAUDE.md) with your three most-repeated corrections to a repository you work in. Start a new session, ask for a small change, and see whether the agent follows them without being told.

## Key takeaways

- 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

- Turn your longest procedure into a skill: [agent skills](https://ai-powered.com/academy/agent-skills/agent-skills-install-and-write).
- Give your agent live access to your tools with MCP: [Claude Code](https://ai-powered.com/academy/connect-mcp-servers/claude-code) or [Cursor](https://ai-powered.com/academy/connect-mcp-servers/cursor).

## Sources

Official documentation, checked on 19 November 2026:

- [How Claude remembers your project (Claude Code docs)](https://code.claude.com/docs/en/memory)
- [AGENTS.md (agents.md)](https://agents.md)
- [Agent Skills overview (Claude docs)](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview)
- [Glossary, context window (Claude docs)](https://platform.claude.com/docs/en/about-claude/glossary)
