CLAUDE.md, AGENTS.md and skills as context files
Coding agents start each session with an empty window, so project knowledge lives in files they load. These are context-engineering artefacts: every line costs tokens and competes for attention.
Kinds of files (Claude Code docs)
- CLAUDE.md: your instructions, at managed-policy, user (
~/.claude/CLAUDE.md), project (./CLAUDE.md) and local (CLAUDE.local.md) scope. Files up the directory tree load at launch and are concatenated; subdirectory files load on demand.@pathimports expand at launch (they organise but do not save context). - AGENTS.md: the cross-tool file (see agents-md). Claude Code reads it when no CLAUDE.md exists; otherwise add
@AGENTS.mdinside CLAUDE.md. Needs v2.1.277+. .claude/rules/: modular rules, optionally path-scoped withpaths:frontmatter so they load only for matching files.- Auto memory: notes Claude writes itself (context-compaction-and-memory).
- Skills (
SKILL.md, open Agent Skills standard at agentskills.io): only name and description load at startup; the body loads when invoked. Use them for multi-step procedures that do not apply every session.
Writing guidance from the docs
- Target under 200 lines per CLAUDE.md; longer files cost context and reduce adherence.
- Be concrete and verifiable (“Use 2-space indentation”, not “format properly”); avoid contradictions across files.
- Keep facts needed in every session: build/test commands, conventions, layout. Skip what Claude can derive from the code.
- CLAUDE.md is context, not enforcement. To block or force an action, use hooks or permission settings.
/doctor prompt-audit(v2.1.283+) flags stale or conflicting instructions, including ones written for older models.
Related
Claude Code, claude-agent-sdk, speckit and other spec files (spec-driven-development).
Sources
- https://code.claude.com/docs/en/memory (2026-09-30)
- https://code.claude.com/docs/en/skills (2026-09-30)
- See the agents-md note for the AGENTS.md standard sources (not re-fetched here)