The prompt library: versioned, shared, and measurable

What you will take away from this lesson

A prompt starts as one person's careful instruction and ends as something a team depends on. Between those two states sit the questions that decide whether the library is worth having. Who else can run this? Which version did they get? Who approved that version? Has anyone run it since March? Is the report template it fills the current one?

In 207 - Governance: personas, access, and audit, we covered the runtime checks that decide which tools a caller can reach. This lesson is the mechanism behind the prompt library: how it is organized, how a change to a shared prompt is reviewed before anyone is served it, how usage is measured, and how the agent resolves a prompt from whatever name the user happened to use.

Learning Objectives

01Read the two buckets the library opens on: My Prompts, everything you own plus everything shared with you, and Library, the approved team prompts grouped by collection.
02Organize a library with collections, and narrow one with the collection, tag, status, owner, and usage facets.
03Read the run count and last-run age on every row, and say what a never run or unused 60d+ badge is actually claiming.
04Read a version history: author, timestamp, status, and the approver bound to one specific version, and say what a pending draft changes for the people reading the prompt.
05State what a Library reader can and cannot see of a prompt whose latest draft is still in review.
06Explain why material attached to a prompt is used as given rather than paraphrased, and which resources may be attached to which prompts.
07Run a prompt by whatever handle you happen to know it by, and recognize scope prefixes as a serve-time detail you never type.

Where we are in the curriculum

If any term in this lesson feels unfamiliar, the 100 series is one click back. The 200 series assumes that mental model.

100 Series: the foundation

Open index

If a term in this lesson looks unfamiliar, back up to the 100 series. The 200 series assumes that mental model. Every row above is a direct link.

What a prompt is, and what it carries

In the Model Context Protocol, a prompt is a named, reusable instruction the server advertises to the client. The server defines it once, along with the arguments it accepts, and any session can invoke it. That is the protocol-level definition and it is worth holding on to, because everything else in this lesson is what Plexara adds around it: an organization model, a review gate, a usage record, and reference material.

The useful mental model is not a saved message. It is a written procedure. A prompt composes several tools into a predictable sequence that produces a predictable output shape, so two people running it on two different topics both get correctly shaped answers without either of them re-describing the workflow.

What a prompt record carries

Name
The stable identifier, like daily-sales-report. Personal names are unique per owner, so two people can each keep a prompt called report without colliding.
Display name
The human-readable label, like Daily Sales Report. It is a real handle, not decoration: the agent resolves a prompt from its display name as readily as from its name.
Description
A sentence on what the prompt produces. It carries weight in relevance search, so a vague description makes a prompt hard to find later.
Arguments
Named inputs written into the content as {placeholder}, each with a description and a required flag. The editor extracts them from the body into a typed table as you write.
Content
The instruction itself, in markdown. In a well-written prompt this is a procedure: which datasets to pull, how to shape the output, what to flag.
Category, tags, collection
The organizing metadata. Tags are free-form and comma-separated; a collection is a shared named group, and a prompt belongs to at most one.

Every mutation of the content, display name, description, arguments, or tags snapshots an immutable version with its author. Nothing on this list can be changed without leaving a record of who changed it.

The library opens on two buckets

An earlier version of this surface asked users to think in scopes: was this prompt personal, persona, or global? That is the right model for the system and the wrong one for the person using it, because a scope is an answer to a question about visibility that most users never asked.

The Prompts page now opens on the question people do ask. Is this mine, or is it the team’s?

Two buckets, not five scopes

My Prompts
Every prompt you own, whatever scope it sits at, plus every prompt another person has shared with you, each attributed to the person who shared it.
This is the bucket with lifecycle in it. Your own prompts show status badges (draft, approved, deprecated, superseded), and the status facet is offered here rather than in the Library.
Library
The approved team prompts you are allowed to see, grouped under the collection each one belongs to, with anything uncollected under a General group.
Everything here is approved by definition, so the useful facet is owner rather than status. This is the shared shelf, and it is the same shelf your agent resolves against.

The question a person actually has is whether a prompt is theirs or the team's, so that is the split the page makes. Scope and persona mechanics still exist underneath, and they surface where they are the subject: the promote flow and the admin review queue.

What the Library looks like

The Library bucket of the portal Prompts page, with prompts grouped under the Data Operations, Executive Briefings, Sales Reporting, and General collections, each row showing a run count and a last-run age, and several rows carrying a never run or unused 60d+ badge — The Library bucket, grouped by collection. Daily Sales Report has been run 128 times and was run yesterday. Data Quality Scan has been run seven times and not for three months, which is why it carries an `unused 60d+` badge. Three prompts under General have never been run at all. None of that is visible from reading the prompts themselves.

Collections group the shared shelf

A flat list of forty approved prompts is a list nobody reads. Collections are the grouping the Library uses instead: named groups by team, domain, or workflow, with a General group holding whatever has not been placed.

How collections behave

Anyone can create one
Collections are named groups by team, domain, or workflow, and creating one is not an admin action. Renaming and deleting are limited to the collection creator or an admin.
One collection per prompt
A prompt belongs to at most one collection, which is what keeps the Library groupable into a single flat set of headings rather than a tree. Owners place their own prompts; admins place shared ones.
Deleting releases, never destroys
Deleting a collection moves its prompts to the General group. A collection is an organizing label, so removing the label cannot remove the work it was labelling.

Managing them

The Manage collections dialog over the Prompts page, listing Sales Reporting, Data Operations, and Executive Briefings with their descriptions and prompt counts, each with rename and delete controls, above a form for naming a new collection — The Collections manager, opened from the button beside the search field. Each collection reports how many prompts it holds, which is the number that matters before deciding to delete one. Behind the dialog, the My Prompts bucket shows the status and sharing detail that the Library bucket does not: an Approved badge, and rows attributed to the colleague who shared them.

Finding one

Search ranks by meaning rather than by substring, and the facets differ between the two buckets on purpose. Each bucket offers the facet that answers a live question in that bucket, and omits the one that does not.

Search and facets

Search by meaning
Type a phrase and prompts rank by relevance to what you meant, not by literal substring. Results span both buckets: your own prompts at any status, shared prompts once approved, and prompts shared with you matched on name and description.
Collection
Narrow to one named group. This is the facet that answers "what does the sales team actually run".
Tag
Free-form labels set on create and edit. Useful for the cross-cutting groupings a single collection cannot express.
Status, in My Prompts
Draft, approved, deprecated, or superseded. Offered on your own prompts, where lifecycle is a live question.
Owner, in the Library
Who owns the shared prompt. In a bucket where everything is already approved, the useful question is whose procedure this is.
Usage
Recently used, or never and long unused. The facet that turns the library into something you can prune.

Usage is a first-class column

The failure mode of a prompt library is not that it stays empty. It is that it fills with procedures nobody runs, and nothing on the screen distinguishes the one the sales team depends on every morning from the one somebody wrote in March and abandoned. Both look like a name and a description.

Usage is a column, not a report you have to request

Every row carries a run count and a last-run age, aggregated from prompt-serve audit events: each time the prompt is fetched over MCP, and each resolved run, counts as a serve. The list sorts by name, by runs, or by last run, and the usage sorts open most-active-first, because the question that sends you to that column is usually which procedures the team is actually leaning on.

A dead prompt is flagged with a badge that names the exact condition rather than a vague warning. never run means it has been served zero times since it was created. unused 60d+ means it has been run and then not for at least sixty days. A prompt created within the last week carries no flag at all, because a week-old prompt with no runs is new, not dead, and a library that cannot tell those apart quickly trains people to ignore its badges.

The same counts come back on the tool side: manage_prompt get and list report run_count and last_run_at per prompt, so an agent asked to tidy the library is working from the numbers the portal shows, not a separate estimate.

Every change is a version, and shared changes are reviewed

A prompt other people run is not a document you edit. It is something being served, and changing it changes what a colleague gets tomorrow morning without them being told. The version history is what makes that visible, and the review gate is what stops it happening silently.

What a version carries

Author and timestamp
Who wrote that version and when. Every mutation of content, display name, description, arguments, or tags snapshots one.
Status
Applied, draft, superseded, or rejected. Applied versions are the ones that have been served; the others record what was proposed and what happened to it.
Approval, bound to the version
Who approved it and when, attached to that specific version rather than to the prompt. An approval is a statement about a particular text, and it does not carry forward to the next edit.
Diff against current
Any version renders as a line diff against the content being served now, so a reviewer reads the change rather than the whole procedure.

Editing an approved global or persona prompt does not take effect on save. The edit lands as a pending draft, the prompt page shows a banner naming its author, and every caller keeps being served the approved snapshot until an admin approves the draft. Personal prompts and never-approved drafts version silently, because there is nobody else being served to protect.

A Library prompt, open

The history, and a pending draft

The version history panel of a prompt: a banner reporting that draft v4 is pending review and readers are served the approved v3, above rows for v4 draft, v3 applied and current with its approver, v2 superseded, and v1 applied with its approver, each offering a diff against the current content — Four versions and one pending draft. The banner states the consequence rather than the state: readers are served the approved v3 until an admin approves v4. Note that v3 and v1 each name their own approver, and that v2 names none, because it was superseded before it was ever approved. Above the history sits the Run from chat panel, whose copyable line is built from the prompt's stable name and its required arguments.

What a Library reader can and cannot see

Version history is visible to anyone who can view the prompt, which raises the question of how much of the editorial record a reader is entitled to. The answer follows one principle: a reader sees what was served, and an admin sees what was written.

Who sees which history

The owner, on their own prompt
The full history, every version and every status, including drafts nobody else has been served.
A Library reader, on an enabled shared prompt
The served history. Applied snapshots in full, and a pending draft as an author and date stub whose content stays private until an admin approves it.
A Library reader, on rejected or superseded drafts
Nothing. A draft that was never served to anyone appears only to admins, so the history a reader sees is a record of what they could have received.
Someone a prompt was shared with person-to-person
The served content only, with no version history. A direct share hands over a runnable prompt, not the editorial record behind it.

The organizing idea is that history is visible to whoever can view the prompt, and that a reader is shown what was served rather than what was written. A rejected draft is an editorial fact about the authoring team, not a fact about the procedure anyone ran.

Prompts carry their reference material

A procedure that says "produce the quarterly summary in the usual format" is not a procedure. The format is the part that matters and it is the part being left out, which is why a prompt can carry the material it depends on: the report template it fills, the checklist it follows, the brand header it embeds, the sample payload it matches.

Attachments are links to managed resources, stored by resource id rather than copied, so editing the uploaded file updates every prompt that attaches it. Because a prompt can travel further than the person who wrote it, the visibility rule is enforced rather than assumed.

An attachment must be at least as visible as the prompt carrying it

Global resource
Any prompt.
Persona resource, for persona P
Personal prompts, and persona prompts scoped to exactly P.
User resource
The author's own personal prompts only.

The rule is checked when the attachment is made, again when the prompt changes scope, and a third time at serve time against the individual caller. Requesting promotion of a personal prompt that carries a private template is refused with the resource named, rather than promoted into a state where most of its audience gets a broken procedure.

Attached material is authoritative

Attached material is used as given

A resolved prompt delivers its materials after the prompt text: text at or below 64 KiB arrives inline as an embedded resource, and anything binary or larger arrives as a link the client reads on demand. What matters is the framing that comes with them. An attached template is to be filled rather than reinvented, and an attached checklist is to be followed. This is the rule that turns a prompt from an instruction into a complete standard operating procedure, because the format is no longer something the agent improvises each time.

Attachments are links to managed resources stored by id, so editing the uploaded file updates every prompt that attaches it, and deleting one does not break the prompt: it still serves, and both the result and the portal flag the material as missing. A reader who cannot see an attachment receives the prompt with a note that some materials were not delivered, never their contents and never their names.

Run it by whatever handle you know

Users do not remember prompt names. They remember what the thing does, or roughly what it is called, and they ask for it in those terms: "run the daily sales report". So when a user names a report, a procedure, or a recurring task, the agent does not enumerate the library and guess. It resolves the handle with the `use` command.

What manage_prompt use accepts as a handle

The exact name
daily-sales-report
The display name, case-insensitively
Run the Daily Sales Report
A reference from a search result
mcp:prompt:<id>
A description of it, ranked against the library
the one that breaks revenue down by region

One confident match resolves, and the response carries the rendered content, the argument specs, any required argument still missing, and the provenance the agent needs to say what it is about to do: running Daily Sales Report v4, approved by [email protected]. An ambiguous handle returns a short ranked candidate list to choose from. It is never an error, and it is never a silent first match.

Served over MCP, prompt names are prefixed by scope so they cannot collide across users and personas: personal-, <persona>-, global-, and shared- for a prompt someone handed you directly. The prefixes are computed at serve time and the stored name stays bare. They are worth recognizing in a tool-call log and are not something anyone types.

The List Prompts app

The portal is one way to look at a library. The other is inside the conversation, in a client that renders MCP Apps, where the library can be browsed without leaving the chat.

List Prompts, bound to show_prompts

In a host that renders MCP Apps, asking to see your prompts calls show_prompts, and the built-in List Prompts app renders in the conversation: search-as-you-type over the ranked query, the same My Prompts and Library buckets, the same collection and tag filters and usage sorting, cards carrying version, approval provenance, and run count, and a detail view with a form generated from the prompt's argument specs. Run resolves the prompt through manage_prompt use with the filled arguments and places the rendered result straight into the chat.

The binding is the design decision worth noticing. show_prompts performs no data operation at all; its entire job is to render the library for a human who asked to look at their library. manage_prompt, the tool that actually resolves, runs, creates, and edits, carries no app and renders nothing. So the agent's routine prompt work never puts a surprise interface in front of you, and a request to browse never has to be inferred from a request to run.

The app is presentation only, and it holds no state of its own: it populates itself from the same manage_prompt calls whose JSON results are complete on their own in clients that do not render apps. Nothing about the library is only reachable through the picture of it.

Editing without rewriting

From personal to shared

Everything in the Library started as somebody’s personal prompt. There are three distinct ways out of a personal account, and the difference between them is worth being precise about, because two of them produce a runnable prompt and one produces a document.

Three ways a personal prompt leaves your account

Share it with a person
Owner-initiated, by email, and no admin approval. The recipient sees it in their My Prompts bucket attributed to you, and their agent can run it with its arguments intact, because a share hands over a real prompt rather than a markdown snapshot. Revoke it any time from the same dialog.
Request promotion to the team
Pick one or more personas, or global. The prompt stays personal and carries a Promotion requested badge while an admin reviews it. On approval it moves to the requested scope and becomes a genuinely shared prompt. Requesting is self-service; promoting is admin-only.
Save it as an asset
A separate action that exports the content as a markdown asset, for documentation or for sending outside the platform. It produces a document, not a runnable prompt, and it is worth not confusing with sharing.

One ownership and publication rule runs across every prompt surface, so the portal, the agent, and the admin review queue agree on who may do what. An admin creating a global or persona prompt is its approver, which is why it lands approved and searchable with the approval already stamped rather than sitting in draft behind its own author. 403 - Sharing prompts, and closing the loop with feedback takes the same ground from the practitioner side.

The prompts that ship with a deployment

Alongside anything a team authors, every deployment advertises a baseline set of workflows: discovery, dashboard building, report generation, lineage tracing, asset management, and knowledge capture that turns usage into documentation.

What ships in the box (from the ACME demo)

explore-available-data
workflow · arg: topic
Search the catalog for datasets related to a topic, present them with descriptions, ownership, and quality scores, and flag deprecation warnings.
create-interactive-dashboard
workflow · arg: topic
Discover the relevant datasets, query them, build an interactive visualization, and save it as a shareable asset.
create-a-report
workflow · arg: topic
Discover the relevant datasets, analyze them, and produce a structured Markdown report with tables, metrics, and conclusions.
trace-data-lineage
workflow · arg: dataset
Trace upstream sources and downstream consumers for a dataset, including column-level lineage where available.
save-this-as-an-asset
toolkit
Identify the key output from the current conversation and save it as a shareable asset with name, description, and tags.
show-my-saved-assets
toolkit
List the assets you have saved, with names, descriptions, tags, and creation dates.
capture-this-as-knowledge
toolkit
Review the conversation for corrections, business context, data quality observations, or newly discovered relationships, and capture each as an insight for the knowledge pipeline.

These come from server configuration rather than the database, and they are reported in the prompts array of the platform_info response. They resolve through use like anything else, and they are read-only to the management commands. They are also worth reading as reference implementations: each one is a numbered procedure rather than a paragraph of intent.

When to write one

Write the prompt the second time you run the workflow

The signal is repetition, not complexity. If an analyst runs the same three searches and the same query shape every Monday, that sequence belongs in a prompt taking the date as an argument. If a steward performs the same review on insights for one dataset every month, that belongs in a prompt too. The first run of a hard workflow deserves real thought; the tenth should not need any.

Writing it down is also what makes the rest of this lesson apply to it. Once a workflow is a prompt it has a version history, an approver, a run count, and a place in a collection, and the question of whether anyone still uses it stops being a matter of opinion. 401 - Prompts are the new SOPs and 402 - Letting the agent write the prompt cover the writing itself.

Where this leads

Key terms

Seven terms cover the vocabulary of the library. Collection, version, and attachment are the ones a user meets on screen; approval provenance, serve event, and scope prefix are the ones that explain what the screen is showing them.

Key Terms

Collection: A named group of prompts, organized by team, domain, or workflow. Any user can create one; renaming and deleting are limited to its creator or an admin. A prompt belongs to at most one, and deleting a collection releases its prompts to the General group.
Version: An immutable snapshot taken on every change to a prompt content, display name, description, arguments, or tags. Carries its author, timestamp, and status (applied, draft, superseded, rejected).
Pending draft: An edit to an approved shared prompt that has not yet been approved. It is visible as an author and date stub, and every caller keeps being served the approved version until an admin approves it.
Approval provenance: Who approved a version and when, bound to that specific version rather than to the prompt. An approval is a statement about one text, so the next edit does not inherit it.
Attachment: A managed resource linked to a prompt by id: a template, a checklist, a brand file, a sample payload. Delivered with the resolved prompt and framed as authoritative, meaning it is used as given rather than paraphrased.
Serve event: One fetch or one resolved run of a prompt, recorded in the audit log. The run count and last-run age on every row, and the never run and unused 60d+ badges, are all aggregated from these.
Scope prefix: The personal-, <persona>-, global-, or shared- prefix applied to a prompt name when it is served over MCP, so names cannot collide across users and personas. Computed at serve time; the stored name stays bare and nobody types the prefix.

208 - The prompt library: versioned, shared, and measurable