Prompt Template Versioning
This skill covers the runtime promotion mechanics of a prompt template: how
the live version changes, what a rollback costs in wall-clock time, and how to
serve two variants at once. The repository shape, changelog, model-pinning
policy, and drift detection live in agentforce/agentforce-prompt-versioning.
The two meet at activeVersionIdentifier — that skill decides which version
should be live, this one is about the flip.
Start From What The Platform Already Does
Prompt Builder has native versioning. You can create and use multiple
versions of a template and control which one users reach through activation and
deactivation, with only one version active at a time. The metadata mirrors
it: GenAiPromptTemplate (directory genAiPromptTemplates, minimum API 60.0)
holds every retained version in templateVersions[] — each with versionNumber,
versionIdentifier, status (Published/Draft), content, primaryModel,
inputs, outputSchema, responseFormat, and templateDataProviders — and
activeVersionIdentifier names the live one.
So "how do I keep a history" is already solved. Two gaps remain, and everything
below addresses one of them:
- Promotion latency equals your metadata deploy latency — an organisational
property, not a technical one.
- Concurrent variants are impossible natively — a hard platform limit.
Recommended Workflow
- Keep versions inside one template and have consumers reference the
template, never a version. Promotion is then a one-field change to
activeVersionIdentifier, and rollback is its inverse — both diffable in git,
neither touching a Flow or Apex class.
- Before promoting, run a structural diff of the version envelope, not just
the prose. A new
required input fails at invocation rather than deploy;
responseFormat and outputSchema break parsers silently;
templateDataProviders changes what data reaches the model; primaryModel
invalidates the goldens even when the text is byte-identical.
- Order the release: deploy consumers first (able to handle both versions),
activate second, observe, retire third on a recorded date. Consumers that
only handle the new version remove your rollback.
- Measure the rollback wall-clock time in a rehearsal and record it. That
measurement — not a preference for configurability — is the only good reason
to add a CMDT slot-binding layer.
- For a canary, accept that you need two templates plus your own resolver:
bucket deterministically on user id, emit a variant-assignment event before
the ramp starts, ramp 10 → 25 → 50 → 100 with a full working day of
observation at each step, and delete the scaffolding on completion.
- Put
GenAiPromptTemplate early in package.xml — the Metadata API
deploys types in file order, and the template must exist before anything
referencing it (for example AiAgentScorerDefinition) can deploy.
Key Considerations
- A canary with no variant tag produces two populations and no conclusion, and
attribution cannot be recovered after the conversations end.
- CMDT indirection widens who can change production behaviour. Deploy binding
records as metadata so a change is still a reviewable commit.
- Retention is the rollback plan. Keep at least two prior versions; retire on a
date, not on a cleanup instinct.
- A grounding change (
templateDataProviders) is a security event. Agents get no
Trust Layer masking, so new grounding re-opens the PII register review.
Worked Examples (see references/examples.md)
- Versions inside one template — promotion as a one-field change, with the
wrong version-per-template alternative shown alongside.
- When indirection earns its keep — CMDT slot binding, and the honest
tradeoff table for when not to use it.
- Canary with attribution — deterministic bucketing, variant tag, ramp rules.
- What actually breaks on promotion — the four envelope fields and their
failure signatures.
Common Gotchas (see references/gotchas.md)
- Only one version can be active — no platform traffic split; concurrent
variants need two templates and your own resolver.
- Required-input changes fail at invocation, not deploy — deploy consumers
first, always.
primaryModel changes make the goldens stale — even with byte-identical
prompt text.
Top LLM Anti-Patterns (full list in references/llm-anti-patterns.md)
- Claiming Prompt Builder has no version history — it does, and designs built on
the opposite premise solve nothing.
- Inventing a subagent-level
prompt_variants: weight: traffic split (subagents
were called topics before April 2026).
- Inventing
<modelVersion> metadata — the real field is primaryModel.
Official Sources Used
1---2name: prompt-template-versioning3description: "Lifecycle management for Prompt Builder templates: version, test, promote, roll back via CMDT-backed bindings. NOT for source-control layout, model-version pinning, or versioning agent topic prompts — use agentforce/agentforce-prompt-versioning. NOT for authoring a template in Prompt Builder — use agentforce/prompt-builder-templates."4category: agentforce5salesforce-version: "Spring '25+"6well-architected-pillars:7 - Operational Excellence8 - Reliability9triggers:10 - "how do I version a prompt builder template"11 - "rollback a prompt in production"12 - "a/b test a prompt variant"13 - "audit which prompt was live last week"14tags:15 - agentforce16 - prompt-builder17 - lifecycle18 - versioning19inputs:20 - "Prompt template name"21 - "release cadence"22 - "test cases"23outputs:24 - "Versioning policy doc"25 - "promotion checklist"26dependencies: []27version: 1.0.128author: Pranav Nagrecha29updated: 2026-08-1430metadata:31 source: https://skillmd.com/skills/pranavnagrecha/prompt-template-versioning32---3334# Prompt Template Versioning3536This skill covers the **runtime promotion mechanics** of a prompt template: how37the live version changes, what a rollback costs in wall-clock time, and how to38serve two variants at once. The repository shape, changelog, model-pinning39policy, and drift detection live in `agentforce/agentforce-prompt-versioning`.40The two meet at `activeVersionIdentifier` — that skill decides which version41should be live, this one is about the flip.4243## Start From What The Platform Already Does4445Prompt Builder has **native versioning**. You can create and use multiple46versions of a template and control which one users reach through activation and47deactivation, with **only one version active at a time**. The metadata mirrors48it: `GenAiPromptTemplate` (directory `genAiPromptTemplates`, minimum API 60.0)49holds every retained version in `templateVersions[]` — each with `versionNumber`,50`versionIdentifier`, `status` (`Published`/`Draft`), `content`, `primaryModel`,51`inputs`, `outputSchema`, `responseFormat`, and `templateDataProviders` — and52`activeVersionIdentifier` names the live one.5354So "how do I keep a history" is already solved. Two gaps remain, and everything55below addresses one of them:56571. **Promotion latency equals your metadata deploy latency** — an organisational58 property, not a technical one.592. **Concurrent variants are impossible natively** — a hard platform limit.6061## Recommended Workflow62631. Keep versions **inside one template** and have consumers reference the64 template, never a version. Promotion is then a one-field change to65 `activeVersionIdentifier`, and rollback is its inverse — both diffable in git,66 neither touching a Flow or Apex class.672. Before promoting, run a **structural diff of the version envelope**, not just68 the prose. A new `required` input fails at invocation rather than deploy;69 `responseFormat` and `outputSchema` break parsers silently;70 `templateDataProviders` changes what data reaches the model; `primaryModel`71 invalidates the goldens even when the text is byte-identical.723. Order the release: **deploy consumers first** (able to handle both versions),73 activate second, observe, retire third on a recorded date. Consumers that74 only handle the new version remove your rollback.754. **Measure** the rollback wall-clock time in a rehearsal and record it. That76 measurement — not a preference for configurability — is the only good reason77 to add a CMDT slot-binding layer.785. For a canary, accept that you need **two templates plus your own resolver**:79 bucket deterministically on user id, emit a variant-assignment event *before*80 the ramp starts, ramp 10 → 25 → 50 → 100 with a full working day of81 observation at each step, and delete the scaffolding on completion.826. Put `GenAiPromptTemplate` **early in `package.xml`** — the Metadata API83 deploys types in file order, and the template must exist before anything84 referencing it (for example `AiAgentScorerDefinition`) can deploy.8586## Key Considerations8788- A canary with no variant tag produces two populations and no conclusion, and89 attribution cannot be recovered after the conversations end.90- CMDT indirection widens who can change production behaviour. Deploy binding91 records as metadata so a change is still a reviewable commit.92- Retention *is* the rollback plan. Keep at least two prior versions; retire on a93 date, not on a cleanup instinct.94- A grounding change (`templateDataProviders`) is a security event. Agents get no95 Trust Layer masking, so new grounding re-opens the PII register review.9697## Worked Examples (see `references/examples.md`)9899- *Versions inside one template* — promotion as a one-field change, with the100 wrong version-per-template alternative shown alongside.101- *When indirection earns its keep* — CMDT slot binding, and the honest102 tradeoff table for when not to use it.103- *Canary with attribution* — deterministic bucketing, variant tag, ramp rules.104- *What actually breaks on promotion* — the four envelope fields and their105 failure signatures.106107## Common Gotchas (see `references/gotchas.md`)108109- **Only one version can be active** — no platform traffic split; concurrent110 variants need two templates and your own resolver.111- **Required-input changes fail at invocation, not deploy** — deploy consumers112 first, always.113- **`primaryModel` changes make the goldens stale** — even with byte-identical114 prompt text.115116## Top LLM Anti-Patterns (full list in `references/llm-anti-patterns.md`)117118- Claiming Prompt Builder has no version history — it does, and designs built on119 the opposite premise solve nothing.120- Inventing a subagent-level `prompt_variants: weight:` traffic split (subagents121 were called topics before April 2026).122- Inventing `<modelVersion>` metadata — the real field is `primaryModel`.123124## Official Sources Used125126- GenAiPromptTemplate (Metadata API) — https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/meta_genaiprompttemplate.htm127- Use Multiple Versions of a Prompt Template — https://help.salesforce.com/s/articleView?id=sf.prompt_builder_use_multiple_versions.htm&type=5128- Activate and Deactivate Prompt Templates — https://help.salesforce.com/s/articleView?id=sf.prompt_builder_activate_deactivate_templates.htm&type=5129- Manage Prompt Templates — https://help.salesforce.com/s/articleView?id=ai.prompt_builder_manage_prompt_templates.htm&type=5130- Create Custom Scorers (deploy ordering) — https://developer.salesforce.com/docs/ai/agentforce/guide/testing-api-custom-scorers.html