---
name: shared-claude-skills
description: Set up a shared, team-editable Claude skill library in Notion, generate lookup skills that read from it, and run a suggest-and-approve loop so skills improve through error correction. Use when someone wants to share skills across a team, wants teammates to be able to improve a skill they did not create, says skills only live on their own computer, or asks how to version, approve or track changes to a skill.
---

# Shared Claude skills, in Notion

Companion to the *Show Me Your AI* episode on building, sharing and improving skills.

## The problem this solves

A skill is a recipe, and it lives in the instance of whoever wrote it. Share it with
a teammate and they get a copy they cannot edit, because only the author can change
the original. So when the recipe falls over, the person who found the fault has no
way to fix it, and the recipe never gets any better.

The principle: store the recipe in a shared cloud space, and keep only a thin
*lookup skill* on each person's own instance, which reads the recipe from that
shared space at run time. One edit in the shared space then changes the recipe for
everyone, and anyone can propose a change.

That is the whole idea. Everything below is plumbing.

## Before you start

The person needs the **Notion connector (MCP)** enabled in Claude, plus edit access
to a Notion workspace. Check both first, because every step depends on them.

If the connector is not enabled, stop and tell them to add it: Claude Settings →
Connectors → Notion. Do not carry on without it, and do not quietly substitute a
different store.

Then ask which version they want, before building anything:

- **Store only.** Shared library plus lookup skills. Fine for two or three people
  who trust each other.
- **Store plus approval loop.** Adds change requests and an owner who signs them
  off. Worth the extra structure once more than about five people run the same
  skill, or once a skill touches client-facing work.

## Step 1: create the shared library

Create a Notion database called **Skill Library** with these properties:

| Property | Type | Notes |
|---|---|---|
| `Name` | Title | Skill name, kebab-case, e.g. `case-study-builder` |
| `Trigger phrases` | Text | What a person says to invoke it |
| `Owner` | Person | Who approves changes |
| `Status` | Select | `Draft`, `Live`, `Deprecated` |
| `Version` | Number | Increment on every approved change |
| `Last updated` | Last edited time | |

Keep the actual instructions in the body of each page, never in a property.
Properties truncate and are awkward to edit, whereas the body is what people will
read and improve.

## Step 2: write the instructions in the page body

Use this shape for every skill page:

```markdown
## When to use this
One or two lines on the situation that triggers this recipe.

## Inputs
What the person must supply, and in what format.

## Steps
1. ...
2. ...

## Output
Exactly what gets produced, and where it goes.

## Known failure modes
Things that went wrong before, and what to do instead.
```

That last section matters most and gets skipped most. A skill gets good by
accumulating error corrections, not by being written well the first time, so keep
it even when it looks thin.

## Step 3: generate the lookup skill

For each skill in the library, create a small local skill on each person's
instance. It holds no instructions of its own, it fetches them.

Write it like this, substituting the real name, triggers and Notion URL:

```markdown
---
name: case-study-builder
description: Build a client case study from a brief. Use when the person asks to build, write or draft a case study, or says "case study from this brief".
---

# Case study builder

The canonical instructions for this skill live in Notion and may have been
updated since this file was written. Always read them fresh.

1. Fetch this Notion page: <PASTE THE NOTION PAGE URL>
2. Follow the instructions in its body exactly.
3. If the page cannot be fetched, stop and tell the person the shared library is
   unreachable. Do not improvise a substitute recipe.
```

Three things are easy to get wrong here:

- **The description carries the trigger phrases.** Claude decides whether to load a
  skill from its description alone, so the trigger words belong there rather than in
  the body. Copy them across from the `Trigger phrases` property word for word.
- **Fetch every time.** Never cache the instructions into the local file, because
  the entire point is that the local file stays thin and the shared page stays the
  single source of truth.
- **Fail loudly.** If the lookup fails the skill has to stop rather than guess. A
  recipe that silently invents its own steps is worse than no recipe at all.

Each person then saves the lookup skill into their own Claude. They each hold a copy
of the stub, and they all read the same recipe.

## Step 4: the suggest-and-approve loop

Only build this if they chose the approval option.

Create a second Notion database, **Skill Change Requests**:

| Property | Type | Notes |
|---|---|---|
| `Name` | Title | Short description of the change |
| `Skill` | Relation → Skill Library | Which recipe |
| `Raised by` | Person | |
| `Type` | Select | `Didn't work`, `Add step`, `Remove step`, `Clarify` |
| `What happened` | Text | The actual failure, concretely |
| `Proposed change` | Text | |
| `Status` | Select | `Suggested`, `Approved`, `Rejected`, `Implemented` |
| `Approver` | Person | Defaults to the skill's Owner |

The loop runs like this:

1. Someone runs the skill and it falls short, so they log a request, with the
   failure in `What happened` and the fix in `Proposed change`.
2. The owner reviews it and sets `Status` to `Approved` or `Rejected`.
3. On approval, edit the skill page body in Skill Library, bump `Version`, and set
   the request to `Implemented`.
4. Everybody's next run picks up the change automatically, because their lookup
   skill reads the page fresh.

Nobody has to reinstall anything, and that is the payoff.

Push them to fill in `What happened` properly, even though Notion cannot enforce it.
A request that says "make it better" cannot be actioned, whereas one that says "it
output a Google Doc and we needed a one-page HTML" can be actioned in a minute.

## Step 5: offer to automate the approval step

Once the loop exists, offer to add a skill that does step 3 for them, reading
`Approved` requests, editing the skill page body, bumping the version and marking
them `Implemented`. Build it only if they say yes, because plenty of small teams
would rather make that edit by hand and see what changed.

## What to tell them at the end

Three sentences, no more:

- Their skills now live in Notion, and their Claude holds only pointers.
- To change a recipe for everyone, edit the Notion page.
- The `Known failure modes` section is where a skill gets sharp, so log the
  failures as they happen.

## Scope

What you have built is the small-team pattern, with Notion as the store and lookup
skills as the clients. It stops scaling somewhere past a few dozen people, or as
soon as skills need review gates, environment-specific variants and a real audit
trail, and at that point the store wants to be a repository with the library as a
read-only view over it. Say so if they ask, and do not attempt to build that here.