Markdown file types
Common .md files for AI and software projects
Modern projects use Markdown files for humans, AI coding agents, documentation systems, changelogs, prompts, and design decisions.
The most useful .md files
| File | Purpose |
|---|---|
| README.md | Project overview, setup, usage, and first context layer. |
| AGENTS.md | Instructions for AI coding agents. |
| CLAUDE.md | Claude Code project memory and workflow rules. |
| DESIGN.md | Design intent, architecture decisions, and trade-offs. |
| SKILL.md | Defines an Agent Skill with YAML frontmatter and instructions. |
| CONVENTIONS.md | Tool-neutral coding standards for AI coding agents. |
| CHANGELOG.md | Release notes and version history. |
| TODO.md | Task list, backlog, or implementation checklist. |
| PROMPTS.md | Reusable AI prompts and prompt patterns. |
| API.md | API endpoints, examples, payloads, and auth notes. |
| CONTRIBUTING.md | Contribution rules, branch workflow, and review expectations. |
| SECURITY.md | Security policy and how to report a vulnerability. |
How these files work together
Each file owns a different layer of context. Use README.md as the front door for humans. Use AGENTS.md and CLAUDE.md to guide AI coding agents. Use DESIGN.md to explain intent before code changes. Use CHANGELOG.md and TODO.md to keep project state visible. Use PROMPTS.md when your team repeatedly asks AI tools to perform similar work.
Think of them as a stack: README for "what", DESIGN for "why", AGENTS and CLAUDE for "how the agent should work", and CHANGELOG for "what changed". Together they give both people and models a complete, plain-text map of the project.
README, AGENTS, CLAUDE, and DESIGN at a glance
| File | Audience | Answers |
|---|---|---|
| README.md | Humans | What is this and how do I use it? |
| AGENTS.md | Any coding agent | How do I build, test, and behave here? |
| CLAUDE.md | Claude Code | What context and rules apply to this project? |
| DESIGN.md | Team and agents | Why was it built this way? |
Each tool also has its own instruction file, from GEMINI.md and Cursor rules to Copilot instructions. The AI agent instruction files guide compares all of them.
Why file names matter for AI
Predictable names help humans and agents find the right context quickly. A coding agent can infer that README.md is a project overview, AGENTS.md is an instruction file, and DESIGN.md contains decisions. Clear names reduce ambiguity and improve retrieval. The same idea now extends to whole sites through llms.txt, a root-level Markdown file that tells AI models what a site is about.
Recommended folder pattern
project/
README.md
AGENTS.md
CLAUDE.md
DESIGN.md
CHANGELOG.md
TODO.md
docs/
API.md
PROMPTS.md
ARCHITECTURE.mdEdit and preview your .md files
Use Markdown Docs online editor for quick previews or download Markdown Docs to open and edit local `.md` files on Windows.
Related references
- GitHub README docs for README.md behavior.
- OpenAI Codex AGENTS.md guide for AGENTS.md.
- Anthropic Claude Code memory docs for CLAUDE.md.
FAQ
Do all projects need every .md file?
No. Start with README.md. Add AGENTS.md, CLAUDE.md, DESIGN.md, or PROMPTS.md only when the project needs that type of context.
Are Markdown file names case-sensitive?
On some systems, file names can be case-sensitive. Use conventional uppercase names like README.md, AGENTS.md, and CLAUDE.md for clarity.
Can Markdown Docs edit all these files?
Yes. Markdown Docs can open, edit, preview, and save Markdown files such as README.md, AGENTS.md, CLAUDE.md, DESIGN.md, TODO.md, and CHANGELOG.md.