Free Claude Code lesson 3 of 3

Context budget: what loads when

Every toolkit is mostly Markdown fed to your coding agent. What separates them is which kinds of files they ship, and when those files enter the context window.

Three places a file can live

Always loadedIn context every turn. This is what causes overload.

Loaded when calledCosts nothing until you (or the agent) invoke it.

Runs outside the modelReal code. Only its printed output reaches the agent.

Use the colour as a question: which zone is this file in, and what moves it into context? A skill body moves from “when called” into context on invocation. A hook script stays outside the model, unless the host adds its output as context.

U2 · Supplied toolkits guide ↗

Ten kinds of files, three places they live

Every repository in this guide is some combination of these. Once you can name them, “skills vs. workflow vs. settings” stops being confusing.

Project memory

CLAUDE.md · AGENTS.md

Plain Markdown instructions about your project. Read at the start and kept for the whole session. By default Claude Code reads AGENTS.md when no CLAUDE.md exists.

Always loaded, in full

Rules

.claude/rules/*.md

Standing coding standards (“use immutability”, “80% coverage”). Markdown, same as project memory. A rule with a paths: scope loads only when Claude reads a matching file.

Always loaded, unless path-scoped

Skill

skills/<name>/SKILL.md (+ scripts/, references/)

A how-to procedure with a short YAML header (name, description). The agent only sees the one-line description until the skill is used; then the full body loads.

Description always, body on call

Slash command

.claude/commands/<name>.md

A saved prompt you trigger by typing /name. Custom commands have merged into skills: .claude/commands/deploy.md and .claude/skills/deploy/SKILL.md both create /deploy.

Loaded when you type it

Subagent

.claude/agents/<name>.md

A role (“code-reviewer”, “planner”) with its own tool list and model. It runs in a separate context window and returns only a report.

Description always, work elsewhere

Hook

settings.json · hooks.json → .sh / .js / .py

Code that fires on events: session start, before/after a tool call, on stop. Of these ten, the only kind that can enforce something during a session (a PreToolUse hook can deny a tool call). Runs with your user permissions.

Zero, unless it injects text

MCP server

.mcp.json

A real program that gives the agent new tools (browser, database, GitHub). With tool search, the current default, only tool names sit in context and full schemas load on demand. ENABLE_TOOL_SEARCH=false loads every schema up front.

Tool names always, schemas on demand

Plugin

.claude-plugin/plugin.json

A box, not a new thing. One install can drop skills + subagents + commands + hooks + mods on you at once. Always check what’s inside.

Whatever it contains

Spec / state files

openspec/ · specs/ · .planning/ · _bmad-output/

Markdown, YAML or JSON saved in your repo: requirements, plans, task checklists, progress. This is what “specification management” means. See Spec-driven frameworks.

Zero until an agent reads them

CLI / binary

npm or uv package, compiled executable

Actual TypeScript/Python/Go code: installers, validators, spec mergers, a headless browser.

Only its printed output

Correcting one assumption. A “workflow” in these repositories is almost never TypeScript. It’s a Markdown file with steps the agent follows. Real code only shows up in four places: hooks, CLIs, installers, and gstack’s browser. So “specification management” in code terms = a folder of Markdown files, plus (sometimes) a small CLI that creates, validates, and merges them. This is the prompt workflow versus program workflow distinction from The agentic stack.

U2 · Supplied toolkits guide ↗C2 · Claude Code: skills ↗C6 · Claude Code: memory ↗C10 · Claude Code: MCP ↗

CLAUDE.md or AGENTS.md: which file Claude reads

AGENTS.md is the instruction file other coding agents read. Claude Code reads it too (v2.1.277 or later), but by default only when no CLAUDE.md claims the directory. It is one check, made from your working directory upwards.

What counts for the check. A project CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md counts. Your ~/.claude/CLAUDE.md, your organization’s managed CLAUDE.md and .claude/rules/ don’t; they load alongside AGENTS.md.

When it loads. At session start, every AGENTS.md and .claude/AGENTS.md from the working directory up. Later, a subfolder’s AGENTS.md, when Claude reads a file there and that folder has no CLAUDE.md of its own. @path imports inside it are expanded. AGENTS.local.md, AGENTS.override.md and anything under .agents/ are never read.

Changing the rule. In /config, set Project instructions to claude-md-or-agents-md (the default), claude-md-and-agents-md (both; each folder’s CLAUDE.md first), claude-md or managed-only. Run /memory to see which instruction files actually loaded.

Two traps. A personal CLAUDE.local.md added to a repository that relies on AGENTS.md turns AGENTS.md off for you. A tool that writes a new CLAUDE.md into such a repository turns it off for everyone. The fix for both is @AGENTS.md as the first line of the CLAUDE.md. It also works in sessions that can’t read AGENTS.md directly, and on Windows it is safer than a symlink, which Git can check out as a one-line text file.

C6 · Claude Code: memory ↗

What actually loads, and when

Current Claude Code documentation traces a session from startup to compaction. Read this table as the zones in motion.

The built-in Explore and Plan agents skip CLAUDE.md for a smaller context. Exact behaviour changes between versions; the linked page has an interactive timeline.

C8 · Claude Code: context window ↗C6 · Claude Code: memory ↗C2 · Claude Code: skills ↗C3 · Claude Code: hooks ↗

Installed is not loaded

Having 25 skills installed does not mean 25 files sit in context. Only their one-line descriptions do, and not even that for slash-only skills. The real weight comes from CLAUDE.md, unscoped rules, session-start injections, and many descriptions at once.

Installfiles on disk

Discoverdescriptions in context

Invokebody enters context

U2 · Supplied toolkits guide ↗C8 · Claude Code: context window ↗

Measure instead of guessing

Run /context before and after installing anything. It visualizes current context usage as a coloured grid, with optimization suggestions for context-heavy tools, memory bloat and capacity warnings. Pass all to expand the per-item breakdown.

If the always-loaded part grows and you didn’t ask for it, remove it. See Load only what you call.

C9 · Claude Code: built-in commands ↗U2 · Supplied toolkits guide ↗

Audit the instruction files: /doctor prompt-audit

Instruction files age. A rule names a command that was renamed, two files contradict each other, a sentence was written for an older model. /doctor prompt-audit (v2.1.283 or later) asks Claude to look for exactly these problems.

ReadCLAUDE.md, CLAUDE.local.md, AGENTS.md, rules, skills, commands, subagents, output styles

Reportstale, broken or conflicting text

Propose editsnothing changes until you ask

It covers .claude/ and ~/.claude/ by default. Pass a path to narrow it, as in /doctor prompt-audit .claude/skills/deploy. It runs through the bundled /claude-api skill, so it is unavailable while that skill is turned off.

A finding is a proposal, not proof that an instruction is useless. Before you delete a rule, ask what behaviour it protected; after you accept edits, rerun a task you know well.

C6 · Claude Code: memory ↗

Implementation exercise: sort your own setup into the three zones

List every file under .claude/ and ~/.claude/. Mark each one always, on call or outside. Then run /context and compare your list with its breakdown. Any surprise is either a session-start injection, an unscoped rule, or a description you forgot you installed.

← PreviousNext: Skills & plugins →

Lessons 1 to 3 are free. Sign in to open the other 21 chapters and ask the assistant.