Release shared prompts as versioned components

Learning objective

Modularize prompts into reusable, versioned components shared across use cases.

Core idea

A shared prompt component is source text with a defined responsibility, owner, and release version. You assemble components into the API’s system and messages fields. Reuse removes independent copies, but it also expands a change’s reach: one edited component can alter every consuming use case.

Treat the assembled prompt as the behavior you release. A component that looks correct in isolation can conflict with another component, change how examples are interpreted, or place variable data before a cache breakpoint. The architect owns composition and compatibility, not only extraction of repeated paragraphs.

How it works

Divide by responsibility and variability

Start with repeated instructions that have the same meaning across consumers. A company writing convention, a domain-specific procedure, and an output example can each be shared, but they need not have the same owner or release cadence. Avoid extracting a paragraph solely because its words happen to match: if two teams expect it to evolve independently, sharing it creates coupling without a common requirement.

Separate fixed guidance from request values. Render the former into consistent instruction blocks and the latter into the request’s message content. An order identifier, customer statement, or date is an input, not a different released version of the policy. Keeping those roles distinct lets you compare behavior across a release without confusing changed instructions with changed test data.

Anthropic recommends XML tags to distinguish instructions, context, examples, and variable inputs, with consistent, descriptive tag names. Tags such as instructions, context, and input provide an assembly vocabulary. They do not create authorization: a customer’s text inside an input tag remains supplied data. The trust-flow distinction is covered in 0.5.

Define the assembled interface

Write down each component’s expected inputs, the API field it contributes to, and what its consumer must provide. For example, a returns-policy component can supply system instructions about eligibility interpretation while a use-case wrapper supplies the task and messages supplies the customer request. If an output example assumes fields that one consumer does not support, that consumer needs a compatible example rather than another hidden exception.

Your release record can list the composition in a compact form:

release: service-drafting-12
system:
  company-language@3
  returns-policy@8
  response-examples@4
messages:
  task-specific instruction
  request values
consumers: store-support, email-support

This is an application-owned artifact, not an Anthropic request field or hosted component registry. Its versioned entries identify which source text your application renders into system and messages. Keep both the ordered composition and the component contents so an operator can reconstruct the prompt behind a reported output.

Choose one place to resolve conflicting instructions. A shared component should not contain “unless email support says otherwise” while the email wrapper contains the inverse exception. Put the common requirement in the shared component and the legitimate variation in an explicit consumer parameter or separate version. Where the requirements cannot coexist, split the component instead of relying on accidental ordering to hide the contradiction.

Release consumers deliberately

Pin each consumer to a reviewed composition. Editing a source file then becomes preparation for a release, rather than an immediate change to all running consumers. A release should state which use cases adopt it and which remain on the previous version. Record the composition identifier in application request logs alongside the selected model; it is your metadata, not a model-generated assertion about what instructions were supplied.

Anthropic’s evaluation guidance starts with measurable success criteria and testing against them, including A/B comparison against a baseline or earlier version. Apply that principle to the assembled prompt. For a shared policy, test each consuming task’s accepted outcomes, not just whether the component contains the desired sentence. Keep model and test inputs fixed for the comparison so the effect of the component change is visible.

Versioning also gives you a specific rollback target. If a policy update improves store support but breaks email drafts, reverting the composition restores the tested combination; merely rewriting the shared paragraph in place leaves its previous dependencies uncertain. A release record should retain the preceding composition and the evaluation results that supported promotion.

When the whole agent configuration is the release unit, Claude Managed Agents provides a hosted agent version covering the model, system prompt, tools, MCP servers, and Skills; this feature is beta and requires anthropic-beta: managed-agents-2026-04-01. A configuration change creates another version, and supplying version on an update enables optimistic concurrency, returning 409 on a mismatch. Pin a session with agent: {"type": "agent", "id": AGENT_ID, "version": 1}, replacing AGENT_ID with the agent’s ID string, to stage releases independently; this pins the whole configuration rather than individual shared components, so components consumed by several agents still need the application-side composition record.

Preserve deterministic assembly

For a given composition and request inputs, render components in a fixed order with consistent tag names and serialization. Avoid generated timestamps inside reusable instructions. Anthropic’s caching requirements make this consequential: identical meaning is insufficient when the reusable prefix differs. The breakpoint and pricing mechanics belong to 2.5.1.

Order components by their actual instruction needs first, then arrange stable reusable material before varying content where that preserves the intended meaning. Do not move the task after unrelated examples solely to improve a cache hit if it weakens comprehension. When a shared component changes, expect the affected assembled prefix to change as well; compare cache usage after promotion instead of calling the resulting cold write a regression in model quality.

Modularity does not reduce token count by itself. If every request still includes all three components, it still carries all three. The gain is controlled maintenance and traceability. Excluding irrelevant components can reduce context, but only after you show that the consumer does not need their instructions; on-demand procedures are covered in 2.5.3.

Key distinctions and trade-offs

Shared source versus shared deployment: One authoritative component prevents copy drift. Pinned compositions let consumers adopt changes on a controlled schedule. You need both when the same policy supports different operational workflows.

Component test versus composition test: A well-formed policy can still conflict with examples or task wording. Acceptance belongs to each rendered consumer prompt.

Consistency versus coupling: A common component makes one policy decision easier to propagate, while increasing the number of workflows its owner must consider. Split by genuine responsibility, not by arbitrary file size.

The maintenance cost is an assembler, release records, and consumer evaluations. Accept that cost when multiple use cases genuinely share behavior. A single contained prompt may need disciplined versioning without a large component library.

Architecture / decision scenario

A retail company has six drafting assistants. Four interpret the same returns policy; two handle supplier communications with different obligations. The product lead proposes one unpinned “company-policy” file for all six to make updates instantaneous.

The architect rejects that composition because shared branding does not make returns and supplier obligations interchangeable. The architect extracts company language for all six and returns policy only for the four relevant consumers. Each consumer’s release record pins the versions rendered into system, while transaction details stay in messages.

The policy owner changes an eligibility exception. Evaluation compares the preceding and candidate compositions for all four consumers. Store drafts pass, but email drafts reproduce an incompatible example. The team updates the email example before promotion rather than assuming the shared policy’s correctness proves consumer correctness.

The policy owner approves the meaning; the platform team owns deterministic assembly and rollout; each product owner accepts its task results. The release logs identify adopted compositions, and a failed rollout can restore the preceding combination. Cache usage is measured separately after the prefix changes. The choice buys controlled reuse without turning six distinct workflows into one accidental policy surface.

Common exam traps

• Expecting prompt caching to propagate a policy correction between copied prompts.
• Calling placeholders a version-control mechanism.
• Releasing a shared paragraph without testing its consuming prompts.
• Keeping versions but failing to record their ordered composition.
• Assuming XML tags make input trustworthy or guarantee instruction compliance.

What to remember

Reuse source text where responsibility and meaning are shared. Render components into explicit API fields, pin their composition, and evaluate every affected consumer. A prompt release is the assembled behavior, with a reconstructable version and a known rollback target.

Knowledge check

References

• Anthropic, Prompting best practices
• Anthropic, Define success criteria and build evaluations
• Anthropic, Prompt caching
• Anthropic, Define your agent
• Anthropic, Start a session