Prompt Libraries & Versioning

Every prompt you've refined through trial and error represents real invested effort — and if it only lives in your memory or buried in old chat history, that effort evaporates the moment you forget it or a colleague needs the same thing. A library turns individual prompt-crafting into a shared, durable asset.

The payoff compounds over time in three ways: consistency (everyone uses the same proven approach for the same task), shareability (a new team member can use your best prompts on day one), and improvement (each refinement makes the library better permanently, instead of the improvement living and dying in one chat session).

Three common homes, each with tradeoffs. A Notion database gives you filterable views, rich formatting, and is friendly for non-technical teams — the natural default for most people. A Git repo suits teams already comfortable with version control and wanting proper diff history and pull-request review on prompt changes.

Project instructions (inside your AI tool itself) work well for prompts that are really standing context for one specific project rather than reusable templates used across many contexts. The decision mostly comes down to team technical comfort and whether prompts need to be reused across many different projects (favoring Notion/Git) or are specific to one ongoing project (favoring Project instructions).

Each library entry should capture: name (following your naming convention), use-case (a one-line description of when to reach for this), the prompt text itself, variables (the parts meant to be swapped out for each use, clearly marked), an example output (so anyone can see what "good" looks like without running it), an owner (who maintains it), and a last-changed date.

Skipping any of these fields creates friction later — a prompt with no example output requires someone to run it just to understand it, and a prompt with no owner has nobody responsible for keeping it current. The format is short but each field earns its place.

"Good prompt 2" tells you nothing six weeks from now, let alone six months. A naming convention like "email/triage-daily-v3" encodes three things at a glance: the domain (email), the specific use-case (triage-daily), and the version (v3) — enough information to know what it does and whether you're looking at the current one without opening it.

Pick a convention early and apply it consistently across every entry — domain/use-case-version is a solid default, but the specific scheme matters less than everyone using the same one. Consistency is what makes a library searchable and scannable instead of a junk drawer.

Every time you meaningfully change a prompt, add one dated line explaining what changed and why: "2026-07: added banned-words list + hook variants after 3 flat posts." This single habit is what lets anyone — including future you — understand why the current version looks the way it does, instead of just seeing a black-box final result.

The changelog doesn't need to be elaborate; a single line per change is enough. What matters is that it exists at all and that it's attached to the specific version it describes, so the history of "why is this prompt shaped this way" is never lost.

Never trust a prompt revision on vibes alone. Before promoting `v4` to `v5`, run both versions on the same 3 real inputs and compare the outputs directly. If v5 wins clearly — say 3 out of 3 — promote it and archive v4 rather than deleting it, in case you need to reference or revert later.

This discipline prevents the common failure of "improving" a prompt in a way that actually helps one specific case while quietly regressing others. A side-by-side comparison on identical inputs is the cheapest insurance against that regression, and it takes minutes, not hours.

Once more than one person contributes, set simple rules: who can add entries, whether additions need review before being marked as the "current" version, and how disagreements about which version is best get resolved. Even a lightweight rule like "new entries start as drafts until one other person has used them successfully" prevents the library from filling with untested prompts.

Equally important is a monthly pruning ritual: archive or delete entries nobody has used in months, and update the "last verified" date on entries that are still actively used and still working well. A library that only grows, and never prunes, eventually becomes a place nobody trusts to reflect the current best version of anything.