~$ cat ./deep-dives/claude-code-agents-memory-skills.md
Claude Code: agents.md, memory.md, skills.md — how they work together
Claude Code extends standard LLM interactions by introducing explicit file-based configuration for agents operating in development environments. The system relies on three primary artifacts that developers place in the project root to control behavior at different levels of abstraction.
agents.md supplies static project instructions, memory.md maintains dynamic state between conversations, and skills.md exposes callable capabilities. Together they form a coherent architecture that turns Claude into a persistent coding collaborator rather than a stateless assistant.
Project Instructions via agents.md
agents.md, sometimes referenced as CLAUDE.md, contains high-level directives that apply to the entire codebase. It specifies coding standards, architecture decisions, dependency rules, and response formats that Claude must respect on every interaction.
Developers write concise, declarative statements in this file rather than repeating context in each prompt. The file acts as the top layer of the instruction stack and is read automatically at the start of any session.
Persistent State with memory.md
memory.md stores structured information that survives across separate Claude sessions. It records decisions, open tasks, known issues, and evolving design notes that would otherwise be lost when a conversation ends.
The file is updated by Claude itself during sessions and reloaded on subsequent starts. This mechanism provides the continuity required for multi-day or multi-week development efforts without manual context reconstruction.
Reusable Capabilities in skills.md
skills.md defines modular, triggerable functions that Claude can invoke by name. Each skill describes inputs, outputs, and execution steps, allowing the model to delegate repetitive operations such as running tests, generating boilerplate, or performing refactors.
Skills remain dormant until explicitly referenced, keeping the primary context window clean while still offering powerful extensions. The file format supports both simple command mappings and more complex scripted behaviors.
Layer Integration and Execution Flow
At session start, Claude loads agents.md first to establish constraints, then memory.md to restore prior state, and finally registers any skills defined in skills.md. Subsequent user requests are interpreted against this combined context.
When a skill is invoked, Claude executes the defined steps while still obeying agents.md rules and updating memory.md with outcomes. This creates a closed loop where instructions, memory, and capabilities reinforce each other without external orchestration.
Structuring Practices and Workflow Examples
Keep agents.md under 40 lines and focused on immutable rules. Store only high-signal entries in memory.md and version the file alongside code. Define skills with clear trigger phrases and minimal side effects to avoid unpredictable behavior.
A typical workflow begins with a planning request that updates memory.md, followed by skill invocations for implementation, and periodic reviews that reference agents.md constraints. Teams commonly maintain one shared memory.md per repository while allowing per-developer skills.md extensions.
key takeaways
- agents.md establishes non-negotiable project rules that Claude applies automatically.
- memory.md enables true multi-session continuity by persisting decisions and task state.
- skills.md turns common operations into named, reusable commands that reduce prompt length.
- The three files are loaded in a fixed order that creates a predictable execution context.
- Effective use requires keeping each file focused and updating memory.md after every significant change.
frequently asked questions
How does Claude locate and load these configuration files?
Claude scans the current working directory and its parents for agents.md, memory.md, and skills.md at the beginning of each session. The first occurrence of each file in the directory tree is used.
Can memory.md be safely committed to version control?
Yes, memory.md is intended to be committed so that all team members share the same persistent context. Sensitive data should be excluded through .gitignore or separate encrypted storage.
What happens if a skill defined in skills.md conflicts with agents.md rules?
agents.md instructions take precedence. Claude will refuse or modify the skill execution to remain compliant with the project-level directives stored in agents.md.
How frequently should memory.md be updated during a session?
Claude should append or revise memory.md after completing any task that changes project state, such as finishing a feature or discovering a new constraint. Frequent small updates prevent context loss between sessions.
