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](https://modelcontextprotocol.io/) 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](https://claude.com/), [ChatGPT](https://openai.com/), [Codex](https://openai.com/codex/), or [Cursor](https://cursor.com/). |
| [MCP](https://modelcontextprotocol.io/) 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](https://modelcontextprotocol.io/) 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.

```mermaid
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](https://modelcontextprotocol.io/) connector needs only two operations
for a useful v1:

```text
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](https://modelcontextprotocol.io/)
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](https://modelcontextprotocol.io/) 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.

```mermaid
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.

```text
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](https://modelcontextprotocol.io/) `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:

| Control | What it protects | What the connector or library must do |
|---|---|---|
| Authentication | The identity of the caller | Know who is connecting before returning a skill |
| Roles | The difference between proposing, approving, and reading | Keep contributor, reviewer, and representative permissions separate |
| Approved-only discovery | The trustworthiness of returned guidance | Hide draft and rejected versions from ordinary readers |
| Secret separation | Customer data and credentials | Keep passwords, credentials, and customer records out of skill bodies |

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](https://modelcontextprotocol.io/) 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](https://modelcontextprotocol.io/)
to every knowledge problem.

The related [order-context case study](/notes/automating-order-status-for-print-on-demand)
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](https://modelcontextprotocol.io/) 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](https://modelcontextprotocol.io/) tool?

Usually no. Keep the [MCP](https://modelcontextprotocol.io/) 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](/#contact) and tell me where the
shared capability currently breaks.