The Prompt Folder Structure That Scales: Markdown, Metadata, and MCP

A good prompt folder structure is invisible: you open the right file in seconds, the metadata tells you which model it targets, and nothing you save ever goes missing. A bad one grows into the dreaded prompts directory of 400 files with names like final_v2_actually_final.md.

This guide defines a folder structure that scales from a laptop to a team monorepo, with markdown files, frontmatter metadata, and an MCP-aware layout. It is the file-based version of what the LayerFlow workspace does in the browser — and the docs explain how the two connect.

The structure

Organize by domain first, task second, and never by chat or date:

• prompts/coding/ — codegen, code review, debugging, refactoring.
• prompts/writing/ — blog, docs, email, social.
• prompts/study/ — research, flashcards, explanations.
• prompts/clients/ — one subfolder per client or project.
• prompts/shared/ — team-wide prompts that outlive projects.

Each prompt is one markdown file. The filename is the job it does — react-component-generator.md — never the conversation it came from.

Frontmatter metadata: the hidden search layer

YAML frontmatter at the top of each file turns a folder into a database. Minimum viable set: model, task, quality, cost, updated, and a one-line summary. Example: model: claude-sonnet-4-5, task: code-gen, quality: 5, cost: 0.02, summary: generates typed React components with tests.

With frontmatter you can grep, script, and filter by anything. Teams that add a status field (winner, experimental, archived) can run quarterly cleanup with a one-liner instead of an afternoon of clicking.

Naming conventions that survive teams

• job-first names: code-review-agent.md, not my-awesome-prompt-v2.md.
• No version numbers in filenames — versioning belongs in git history or a version field, not in names.
• No personal initials or dates in names; the frontmatter carries both.
• Lowercase with hyphens; sorting and grep stay predictable.

MCP-aware layout: make the structure machine-readable

In 2026 the folder structure is read by humans and by AI agents. Model Context Protocol (MCP) servers let assistants browse your prompt library as a tool. To stay MCP-friendly: keep one prompt per file, keep frontmatter strictly structured, and keep a top-level index.md that lists every domain with a one-line description. An agent that can read your index and frontmatter can find the right prompt without you.

Common mistakes

• Nesting deeper than three levels — depth becomes navigation tax.
• Mixing templates with actual prompts in the same folder.
• Storing prompts as chat exports with no metadata.
• Letting anyone create top-level folders — structure dies by democracy.
• No index file, so newcomers cannot discover what exists.

When to move from folders to a workspace

File folders are free, greppable, and git-friendly — a great start. They stop scaling when you need to run prompts (copy-paste from files into chats), need cost and quality history, or need non-technical teammates to participate. That is the switch point for a workspace like LayerFlow, which keeps the domain structure and adds execution.

Internal next steps

Pair this with Domain-Based Prompt Organization and Moving from ChatGPT History to a Workspace. For file-based templates, see Prompt Template Systems.

Set up your structure in LayerFlow or keep it in files first — either way, start with domains and frontmatter today. See pricing for free tier details.

FAQ