just use `.prompt.md` for your prompts!

3 min read

as i use llms more in my daily work, i’ve had to think about something i never considered before: where do prompts actually live?

most prompts aren’t just prompts — they’re templates. they have blank spaces that let you plug in context, personal info, or whatever else you need. every AI app has these prompt templates and system prompts tuned for maximum utility.

and yet, folks don’t give storage much thought. prompts end up scattered across the codebase — as const variables, strings buried in .py files, or worse. need to update one? make a PR for a string change. want to track versions? good luck with that excel sheet.

i’ve been there. it’s a nightmare.

the notion detour

as a notion power user (and shameless shill), my first instinct was to make an inline database. each row opens a markdown page, which makes it arguably the best place to store prompts — if you’re not a developer.

but the moment you need template-filling, API access, or prompt evaluation, notion falls short. it’s not built for this.

the solution: .prompt.md

the answer is embarrassingly simple: store prompts as .prompt.md files with frontmatter metadata.

---
name: Baby Name Generator
description: Creates baby names based on parent info
metrics:
  accuracy: 0.95
---

You are the world's top expert in naming babies. You named the babies of all the famous people including Travis Scott and Kylie Jenner's baby Stormie.

<father>
{{father}}
</father>

<mother>
{{mother}}
</mother>

this gives you everything:

  • easy caching (CDNs love small text files)
  • human and machine readable
  • simple organization in folders
  • algorithmic modification when needed
  • notion can export to it anyway

everyone wins.

why not yaml?

if you’ve thought about this before, you’ve probably seen github pushing .prompt.yml. nothing against yaml — i use it daily and prefer it over json for readability. but it’s wrong for prompts:

  1. no rendering — IDEs can’t beautify prompt content in yaml. markdown renders beautifully everywhere.

  2. multi-turn is overrated — yaml’s main advantage is structured multi-turn prompts. but most apps use single-turn templates. and you can do multi-turn in markdown anyway (it all concatenates before hitting the LLM).

  3. content stays front and center — with markdown, your prompt is the document. metadata lives in frontmatter where it belongs.

scaling up: cloudflare workers + kv

once you’re ready for production, throw your .prompt.md files into Cloudflare KV and serve them via a Worker. you get:

  • global edge distribution (sub-50ms latency everywhere)
  • simple key-value lookups (prompts/baby-name-generator)
  • generous free tier (100k reads/day)
  • version prompts using different KV namespaces

it’s basically a prompt CDN. your app fetches the latest prompt from the edge, parses the frontmatter for metadata, and you’re off.

just use .prompt.md. your future self will thank you.

Graph View