SfSkills Domains Docs GitHub

Home / agentforce / prompt-template-versioning

prompt-template-versioning

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.

Open the skill folder on GitHub

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:

  1. Promotion latency equals your metadata deploy latency — an organisational

    property, not a technical one.

  2. Concurrent variants are impossible natively — a hard platform limit.
  1. 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.

  2. 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.

  3. 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.

  4. 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.

  5. 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.

  6. 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

Worked Examples (see references/examples.md)

Common Gotchas (see references/gotchas.md)

Top LLM Anti-Patterns (full list in references/llm-anti-patterns.md)

Official Sources Used

Package files