prompt_versioning v1.0.0

name: "prompt_versioning" description: "Version prompt text like source code: keep a change log, diff versions side by side, pin a known-good version for production, and roll back when a change misbehaves. Use when a prompt is shared, reused, or changed over time and someone asks what changed, whether you can roll back, or which version is live." metadata: { "includeInPrompt": true }

Prompt Versioning

Purpose

Prompts change silently and behavior shifts with no record of why. One edit to a system instruction, one reworded line, and a product behaves differently for everyone who uses it. Treating prompt text like source code, versioned, diffable, and rollback-able, fixes that. This skill covers the file-level discipline: how to store prompts, how to log changes, how to pin the version that is live, and how to roll back.

Workflow

1. One prompt, one file. Store each prompt as plain text in its own file (for example prompts/support_triage.txt). No embedding prompt text inside scripts or scattered config files where nobody can find it.

1. Log every change. Keep a change log next to the prompt (for example prompts/support_triage.log or a shared prompts/CHANGELOG.md). Each entry has three things: the date, what changed, and why. One or two lines is enough.

2026-10-05  Added "Ask for the order number before anything else." Reason: the bot kept guessing which order the customer meant and got it wrong half the time.
2026-10-03  Softened the refund refusal to offer a callback instead. Reason: too many angry escalations in the support inbox this week.

1. Diff versions side by side. Before shipping a change, read exactly what moved. Standard diff works fine:

diff prompts/support_triage.v3.txt prompts/support_triage.v4.txt

Read every line of the diff out loud to yourself if the change matters. Most silent breakage is a word that looked harmless.

1. Pin the live version. Production points at a pinned, known-good copy, never at the draft you are editing. The pin is a tiny marker: a file or a line that names which version is live.

LIVE: prompts/support_triage.v4.txt

Edit only draft copies. Update the pin only when a new version is deliberately shipped, and log that in the change log too.

1. Roll back on a misbehaving change. Rollback means: point the pin back to the last good version and note why in the change log. No code rewrites, no frantic re-editing under pressure.

2026-10-05  Rolled live pin back to v4 from v5. Reason: v5 dropped the order-number ask and the misfires returned within an hour.

Output Contract

A versioned prompt bundle looks like this:

• The prompt file itself, plain text, one per prompt.
• A change log with dated entries, each stating what changed and why.
• A pinned-version marker naming exactly which version production uses.

A rollback looks like this: the pin now points at an older version, and the change log has a new entry recording the rollback, the date, and the reason. That is all. If any of those three artifacts is missing, the bundle is incomplete.

Operating Rules

• Never edit the pinned production copy in place. Edit a draft, ship it, then move the pin.
• A change log entry without a reason is filler. "What changed" alone tells you nothing when the next problem arrives. Always write the why.
• Date every entry. An undated log is a diary with the pages shuffled.
• Keep one canonical location for the live pin. If two places disagree about which version is live, you have no live version.
• Name versions sequentially and keep old ones around. Deleting the version you rolled back to is how a second outage starts.
• When someone asks "what changed", answer from the change log and the diff, not from memory.