Building a Prompt Library People Actually Reuse

The typical prompt library is a wiki page with forty snippets, no indication of which ones still work, and no way to tell whether the one you want already exists. People stop looking after the second time they find a prompt that references a model retired six months ago, and go back to writing their own.

A library is not a collection of text. It is an interface with a contract, an owner and a test, and the ones that survive are built that way from the start.

The unit is a task, not a prompt

The mistake at the root of most libraries is cataloguing strings. A string has no contract: you cannot tell what it expects, what it returns or when it breaks.

Catalogue callable units instead. A library entry should be a named function with typed inputs, a typed output, a pinned model, and a template it renders internally. Callers never see the prompt text and never copy it. That way a fix ships to everyone at once, and someone reading the call site knows what they get without reading English prose.

classify_ticket(text: str, locale: str) -> TicketLabel
summarise_thread(messages: list[Message], max_words: int) -> Summary

This also settles the question of what a prompt does when the model changes. If the unit is a function, swapping the model is an implementation detail with a test to prove it still works. If the unit is a snippet on a wiki, every caller has to find out for themselves.

Every entry needs an owner and an expiry

Unowned prompts rot silently. Nobody notices that the classification prompt stopped handling a label that was added in March, because nobody is responsible for it.

Put a named owner in the metadata, and treat it like on-call: if the owner leaves, the entry gets reassigned or deleted. Deletion is the important half. A library that only grows becomes unsearchable, and an unsearchable library is not used.

Add a last-verified date and a policy that anything unverified for six months is quarantined. Quarantine rather than deletion, so the history survives, but out of the default search path. Most teams find that a third of their entries fail this test the first time they apply it, and the library becomes dramatically more useful once they are gone.

Discoverability is the whole problem

People write duplicate prompts because searching was harder than writing. Fix the search and duplication mostly stops.

Name entries by the task in the domain language, not by technique. Nobody searches for "chain-of-thought classifier"; they search for "categorise support ticket". Index on the input and output types as well as the name, so that "takes an email, returns a label" is a findable query.

Give each entry a one-line description of what it is for and, more usefully, a one-line description of what it is not for. The negative line prevents the most expensive kind of reuse, where somebody applies an entity extractor built for invoices to contracts and gets plausible garbage. Include one real input and one real output in the entry, because a concrete example communicates scope faster than any description.

Ship the contract, not the wording

An entry is only reusable if callers can rely on something. Define that something explicitly: the output schema, the failure behaviour, and the latency and cost envelope.

The output schema should be a real schema object that the entry validates against before returning, so a caller never has to parse free text. Failure behaviour needs to be stated rather than implied — does it return null, raise, or return a low-confidence answer? An entry that sometimes returns a made-up value instead of admitting it does not know will be discovered by its callers at the worst moment.

Publish typical tokens in and out, and the model it targets. Someone deciding whether to call your entry inside a loop needs the cost per call, and if they have to measure it themselves they will instead write their own cheaper version. The distinction between a library entry and a one-off matters most here, since enforcing an output schema rather than parsing prose is what turns a prompt into something another team can depend on.

Tests are what separate a library from a folder

Each entry carries a small evaluation set: ten to thirty cases with expected outputs, run in CI against the pinned model. This is unglamorous and it is the entire difference between a library and a folder of text files.

The tests answer the question that stops people reusing prompts, which is "does this still work". A green badge on an entry is worth more than a paragraph of documentation. It also lets you upgrade models deliberately: point the entry at a new model, run the set, see what breaks.

Keep the sets small enough to run on every commit. If an entry needs two hundred cases to feel safe, it is probably two entries. And record cost per run, because a library where the test suite costs real money per commit gets disabled, which is worse than having no tests.

The statistics of comparing one version against another are easy to get wrong, and worth reading properly in how to tell whether a prompt change actually helped before you start gating merges on a score.

Layer the library so common parts are shared

Entries accumulate the same fragments: the output contract boilerplate, the refusal policy, the date handling, the tone rules. Copied fragments drift, and then two entries disagree about what null means.

Factor the shared parts into composable pieces with their own versions, and let entries include them. This is ordinary software layering and it has the same benefit: a policy change happens in one place. It has the same risk too, which is that changing a shared fragment changes every entry that includes it, so shared fragments need the broadest test coverage in the library.

Keep example sets separate from instruction fragments. They change on different schedules and under different rules, as set out in managing few-shot examples so they do not contradict each other.

Governance that does not become bureaucracy

Three rules cover most of it. Adding an entry requires an owner, a schema and a test set. Changing an entry requires a version bump and a passing test run. Removing an entry requires checking callers, which is trivial when entries are functions and impossible when they are snippets.

Review new entries for duplication rather than for wording. The most valuable thing a reviewer does is say "this is the ticket classifier with two extra labels, extend that one instead". Wording review is low value because the tests decide whether the wording works.

Underneath all of it sits the mechanical layer: templates in files, stable names, content hashes and immutable versions, described in treating prompts as versioned code artefacts. A library without that layer cannot tell you which version produced an output, and a library that cannot answer that question will not be trusted for long. And pin the model per entry rather than globally, for the reasons in pinning model versions instead of tracking a floating alias.