A field guide to the Markdown layer
Four Markdown conventions now carry much of the durable context behind effective work with Claude and other coding agents. They look similar on disk, but each has a different owner, lifetime, and job.
CLAUDE.md is the project briefing
CLAUDE.md is a plain Markdown file Claude reads when a conversation starts. It records the instructions a capable contributor needs before changing the repository: build and test commands, architecture notes, code style, environment setup, and project-specific constraints. Files can exist at more than one directory level, allowing broad repository guidance and narrower instructions for a particular area. Because the file loads as context, concise and current guidance is more useful than a long history of completed work.
- Record stable commands and conventions that apply to future work.
- Explain constraints and the reason for them when the code cannot make that reason obvious.
- Remove stale guidance instead of allowing contradictory instructions to accumulate.
SKILL.md packages reusable expertise
SKILL.md is the entry point for an Agent Skill: a folder containing instructions and, when needed, scripts, references, or assets. Its YAML frontmatter supplies a name and description that an agent can inspect before loading the full body. This progressive-disclosure model keeps the initial context small. The complete instructions load only when the task matches, and supporting files are read on demand. A useful skill describes when it should activate, the workflow it expects, the quality checks it requires, and the boundaries it must respect.
- Metadata supports discovery before the full instruction body is loaded.
- The body defines a repeatable workflow rather than a one-off answer.
- References and scripts keep detailed material available without occupying every session.
MEMORY.md indexes learned context
Agent-managed memory serves a different purpose from user-authored project instructions. The agent records durable lessons discovered while working, while MEMORY.md acts as a compact index to focused topic files. This is useful for non-obvious decisions, environment quirks, and confirmed preferences that future sessions could not recover cheaply from the repository. It should not become a changelog, a duplicate of the code, or a place for credentials and personal data.
- Keep the index short and point to focused topic files for detail.
- Store the reason behind a durable rule so future work can judge edge cases.
- Prefer current code over a memory entry when the two disagree.
AGENTS.md makes guidance portable
AGENTS.md is a vendor-neutral instruction file supported by a growing range of coding agents. It gives a repository one portable place for build steps, conventions, testing expectations, and contribution guidance. Teams that work across Claude Code, Codex, Cursor, Copilot, Gemini CLI, and other tools can use it as a shared baseline instead of maintaining completely separate instructions for every client. Tool-specific files can still add details that apply only to one agent.
How the files fit together
Use project instruction files for facts and rules people intentionally maintain. Use skills for reusable workflows that should activate for a class of tasks. Use agent memory for lessons learned through work that are not otherwise visible. Keep portable guidance in AGENTS.md when several tools need the same baseline. The goal is not to place every fact in every file; it is to give each kind of context one clear home so instructions remain trustworthy.
- Browse the Skills Hub for reusable SKILL.md instructions.
- Explore skill bundles organized around professional workflows.
- Read more guides on prompt engineering, context engineering, and agent skills.
Frequently asked questions
- What is CLAUDE.md? It is a project instruction file Claude reads to understand repository-specific commands, conventions, and constraints.
- What is SKILL.md? It is the instruction entry point for a reusable Agent Skill, with metadata for discovery and a body loaded when the task matches.
- How is memory different? Project instructions are deliberately authored; agent memory captures durable lessons learned while doing the work.
- Why use AGENTS.md? It provides a portable baseline that multiple coding agents can read instead of tying all repository guidance to one vendor.