A team skill library needs a librarian, not more prompts

A shared AI skill library should solve distribution, not become another place where a team writes prompts. The bounded v1 is a reviewed library of playbooks, a small registry, and a read-only MCP (opens in a new tab) path that lets an AI client discover and retrieve only approved guidance.

This note teaches the pattern, not a universal product recipe. The reader should be able to sketch a bounded v1, explain why the boundaries exist, and recognize when a shared library is too much architecture for the problem.

The domain model comes before the connector

The useful nouns are not “prompt” and “tool.” They are the people, authority, artifacts, and boundaries that determine whether a playbook can be trusted.

Concept	Type	Description
Contributor	Actor	Proposes a playbook after learning something useful. A contributor may draft, but cannot silently publish.
Process owner	Actor	Owns how a business area such as returns, delivery, or billing should work and is accountable for the guidance.
Reviewer	Actor	Checks the proposed playbook for accuracy, safety, scope, and escalation boundaries. In a small team, this can be the process owner.
Support representative	Actor	Uses an AI client while helping a customer and may read only approved guidance allowed for that role.
Skill body	Entity	The full playbook: purpose, steps, examples, limits, and escalation path. The canonical content lives in the library.
Skill registry	Entity	The catalogue card for a playbook: name, purpose, owner, version, approval status, and access policy.
AI client	System	The application where a person asks for help, such as Claude (opens in a new tab), ChatGPT (opens in a new tab), Codex (opens in a new tab), or Cursor (opens in a new tab).
MCP (opens in a new tab) connector	System	The bounded read path that authenticates the client, lists allowed skills, and retrieves one approved skill body. It is a librarian, not the library.
Approved version	State	A skill body and registry record that passed review and may be returned to an eligible client. Draft and rejected versions are not discoverable.

The relations matter as much as the nouns: a contributor proposes a skill, a reviewer approves a version owned by a process owner, and an authenticated AI client retrieves that approved version for a representative. The connector may read the library; it does not decide who is allowed to approve the process.

The bounded v1 has four pieces

Start with four building blocks:

1. Skill storage holds the full playbook in one canonical location.
2. A skill registry holds the short catalogue record and approval state.
3. An MCP (opens in a new tab) connector authenticates the caller and serves a tiny read surface.
4. A review signal tells the accountable reviewer that a new version needs attention; the approval record still belongs in the registry.

flowchart LR
accTitle: The bounded read path for a shared AI skill library
accDescr: A support representative asks an AI client for guidance. The client calls an authenticated connector. The connector reads an approved catalogue record and the matching skill body before returning it.
Representative[Support representative] --> Client[AI client]
Client --> Connector[Governed connector]
Connector --> Registry[Skill registry]
Connector --> Storage[Skill body storage]
Connector --> Client

The important separation is between the long skill body and the short registry record. The client sees a small catalogue before it loads detailed guidance. That keeps the context surface bounded as the library grows.

The read path should stay smaller than the library

The MCP (opens in a new tab) connector needs only two operations for a useful v1:

list_skills()
  -> name, purpose, owner, version, and approval state for allowed skills

get_skill(skill_name)
  -> the full approved playbook for one skill the caller may read

Do not turn every playbook into a separate MCP (opens in a new tab) tool. If the team has 60 skills, the client would see 60 tool names before it understands the support question. A catalogue operation plus one retrieval operation keeps discovery proportional to the task.

The connector is also the policy boundary. It authenticates the client, checks the caller’s read permission, hides draft and rejected versions, and returns only an approved body. The MCP (opens in a new tab) protocol can carry the request; it does not choose the organisation’s role model for you.

Publishing comes before browsing

The reading path is easy to imagine: a representative asks an AI client for help, the client finds a relevant skill, and the connector retrieves it. The publishing path is what makes the result a shared capability rather than a folder of competing prompts.

flowchart TD
accTitle: The publishing lifecycle for a shared AI skill
accDescr: A contributor drafts a playbook and submits it for review. A reviewer checks the process, scope, examples, and escalation boundary. Only an approved version enters the registry and storage for governed retrieval.
Contributor[Contributor] --> Draft[Draft skill]
Draft --> Proposal[Submitted proposal]
Proposal --> Review[Reviewer checks]
Review --> Approved[Approved version]
Approved --> Registry[Skill registry]
Approved --> Storage[Skill body storage]

The smallest useful publishing sequence is:

• a contributor drafts one recurring playbook;
• the proposal names its process owner and reviewer;
• review checks accuracy, examples, boundaries, and escalation;
• approval publishes a version to the canonical library;
• the next eligible request can discover that version through the connector.

Drafts are proposals. Only approved versions are discoverable.

A delayed-order skill makes the boundary concrete

Do not begin with a library of 100 generic prompts. Choose one recurring support situation where correct process matters.

The following registry record is illustrative, not a production record; its purpose is to show the minimum fields that make publication inspectable.

name: delayed-order-reply
purpose: Explain a late order without making unsupported delivery promises.
owner: Head of Customer Service
status: approved
version: 3

The full skill body belongs in storage. The registry record is the catalogue card. An MCP (opens in a new tab) list_skills response can return the short record; get_skill("delayed-order-reply") returns the full playbook only when the assistant is working on that kind of customer question.

A real body would define:

• when the skill applies;
• what checks the assistant must make;
• the order in which it explains a delay;
• promises it must not make;
• the point where a human owns the case; and
• one good example of the finished reply.

That is enough structure to make the library searchable, reviewable, and safe to change.

The governance boundary is the real architecture

The four controls that make this v1 safe enough to test are:

The connector should be read-only in v1. A playbook may explain a process, but it should not become an unreviewed action surface just because the client can call it.

Alternatives I would reject for the first version

The simplest design is not always the smallest-looking design. These are the alternatives I would deliberately reject for this v1:

Alternative	Why it is tempting	Why I would reject it now	When it becomes reasonable
Every skill is its own MCP (opens in a new tab) tool	The tool list looks explicit	Discovery becomes noisy and the client sees the whole catalogue too early	A very small, stable capability set
One shared document with no registry	It is quick to start	No clear owner, version, approval state, or role boundary	A private experiment before multiple people contribute
Write access from the AI client	It feels like end-to-end automation	It mixes guidance retrieval with consequential actions and expands the failure surface	A separately designed action workflow with approvals and audit
A custom authoring interface first	It promises a polished workflow	It delays learning whether people contribute and review useful guidance	A real review queue or ownership problem appears

The accepted trade-off is deliberate simplicity: a small read path and manual review create less automation, but they make the operating model legible before the system earns more complexity.

When the pattern fits and when it does not

When this pattern fits

Use it when a team has repeated process knowledge scattered across personal prompts, chat history, and documents, and needs a reviewed way to retrieve the right guidance in the flow of work. It fits especially well when playbooks need owners, versions, and escalation boundaries but the client should not perform the business action itself.

• Good fit: repeated guidance, named ownership, and a separate action boundary.
• Good fit: a team needs approved versions without forcing every representative to maintain a local copy.

When it does not fit

Do not build this just to centralize a few static instructions that one person can maintain in an ordinary document. Do not use it as the action layer for refunds, cancellations, money movement, or irreversible changes. Those need approval, idempotency, limits, audit trails, and recovery from partial writes.

• Non-fit: one person maintains a small, stable document.
• Non-fit: the proposed connector would perform irreversible business actions.

A simpler shared document or a normal service endpoint may be the better answer. The point of the pattern is governed retrieval, not adding MCP (opens in a new tab) to every knowledge problem.

The related order-context case study shows the same identity, ownership, and disclosure reasoning applied to a live operational read path.

Common questions

Does every representative need the same AI client?

No. The library can stay independent of the client, provided each client supports the chosen MCP (opens in a new tab) connection and sign-in method. Start with one client and validate additional clients deliberately.

Why not store prompts in a shared document?

You can start there. The registry and connector become useful when you need to know which version is approved, who owns it, who may see it, and how a client retrieves only relevant guidance.

Should every skill be an MCP (opens in a new tab) tool?

Usually no. Keep the MCP (opens in a new tab) surface small: a catalogue operation plus a retrieval operation is enough for a bounded v1.

When do we need a dedicated authoring interface?

When the review queue, ownership, and version history are difficult to manage through the workflow the team already has. Build it in response to that friction, not before it exists.

The takeaway

• Keep the skill body, registry, connector, and approval boundary distinct.
• Expose a small read path: list approved guidance, then retrieve one approved playbook.
• Start with one real process and add complexity only when ownership, review, or scale proves that the simpler design is no longer enough.

If your team has useful process knowledge trapped in personal prompts or chat history, message me and tell me where the shared capability currently breaks.