Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

docs(ok): split Skills Studio into individual and team paths (#4349)

tim-inkeep9b3145c9c633
diff --git a/docs/_snippets/skill-update-states.mdx b/docs/_snippets/skill-update-states.mdx
new file mode 100644
index 000000000..d6d06faeb
--- /dev/null
+++ b/docs/_snippets/skill-update-states.mdx
@@ -0,0 +1,5 @@
+| What you see | What it means | What to do |
+| --- | --- | --- |
+| **Update from source** | The source moved since you imported the skill. | Open it to read the diff, then apply it. |
+| **Auto-update** | Off by default, per skill. | Turn it on for a source you want to follow without reviewing each change. |
+| **Modified** | You edited your copy, which pauses its automatic updates. | Keep your version, or **Revert** to the imported original. |
diff --git a/docs/content/features/skills/built-in-skills.mdx b/docs/content/features/skills/built-in-skills.mdx
new file mode 100644
index 000000000..6facf7d1a
--- /dev/null
+++ b/docs/content/features/skills/built-in-skills.mdx
@@ -0,0 +1,30 @@
+---
+title: Skills OpenKnowledge ships
+description: What each built-in skill does, and how to install or remove it.
+---
+
+OpenKnowledge ships skills that teach an AI how to work with OpenKnowledge itself. None is required, and none installs without you choosing it.
+
+| Skill | Use it to | Where |
+| --- | --- | --- |
+| `open-knowledge-discovery` | Help an AI recognize an OpenKnowledge project and set a new one up. | **Settings → User** |
+| `open-knowledge-write-skill` | Have an AI draft and install a new skill. | **Settings → User** |
+| `open-knowledge` | Teach an AI to read, search, link, and write through this project's tools. | **Settings → This project** |
+
+## User scope
+
+<Image src="/images/skills-studio/settings-user-skills.png" alt="Settings, User, Skills Studio: the skills OpenKnowledge ships, each showing the AI tools it reaches, above the panel that shares skill folders between tools." width={1600} height={1244} />
+
+- **Install** adds the skill to every AI tool detected on this machine. **Uninstall** removes it again, and touches nothing you wrote.
+- **Manage** opens a read-only preview of the full `SKILL.md`.
+- **Update** appears when a newer copy exists. Built-ins never update on their own.
+
+Only the discovery skill is offered at first launch; the authoring one is offered once, and declining is remembered.
+
+## Project scope
+
+<Image src="/images/skills-studio/settings-project-skills.png" alt="Settings, This project, Skills Studio: the project's own open-knowledge skill and the project-local skill folders." width={1600} height={1244} />
+
+The `open-knowledge` skill installs into the project's own skill folders, which are not committed by default. A teammate who clones the repository installs it themselves.
+
+From the CLI: `ok init --skills discovery,write-skill` selects built-ins during setup, `ok init --no-skills` skips them.
diff --git a/docs/content/features/skills/find-and-install.mdx b/docs/content/features/skills/find-and-install.mdx
index 95461e06b..876d633ed 100644
--- a/docs/content/features/skills/find-and-install.mdx
+++ b/docs/content/features/skills/find-and-install.mdx
@@ -5,9 +5,7 @@ description: Find a skill, read what it does, and choose the AI tools that can u
Start with a skill someone has already written, or bring in one you keep elsewhere.
-OpenKnowledge also ships its starter packs as [plugins](./reference.mdx#plugin-marketplace).
-
-## Find a skill
+## Find one
<Steps>
@@ -23,42 +21,46 @@ Hover the **Skills Studio** dock header and click **Explore skills**. Search [sk
<Step>
-### Preview before adding
+### Read it before you add it
+
+Open a result to see its full instructions, its bundled files, and how much context it costs. **Install** takes it from here, at Project or Global scope; if the source holds several skills, choose the one you want.
-Open a result to read its description, instructions, and bundled files. Check that it fits the task you have in mind.
+<Image src="/images/skills-studio/explore-preview.png" alt="A skill's preview open as an editor tab, showing its instructions, token cost, and the control to add it." width={1600} height={1333} />
</Step>
<Step>
-### Add it to your collection
+### Choose your AI tools
+
+Open the skill's **Install** menu and check the tools that should use it, or **All**.
-Add the skill to your Project or Global collection. If a source contains several skills, choose the one you want. It opens in the editor, ready to read and customize.
+<Image src="/images/skills-studio/install-destinations.png" alt="The Install menu lists Claude Code, Cursor, Codex, and the shared source folder, with an All control at the top." width={1600} height={860} />
+
+Each checked location points at the same source, so your tools cannot drift. [Symlink skills](./symlink-skills.mdx) covers sharing a whole folder instead.
</Step>
</Steps>
-## Choose your AI tools
+A skill is live for its agent the moment it lands. There is no separate install step to flip: the menu controls *where* it is available.
-Open the skill's **Install** menu (shown as **Installed** once it is in use). Check the locations for the tools that should use it, or choose **All** for all eligible tools.
+## Bring one you already have
-A skill is live for its agent the moment it lands. There is no separate install step to flip: this menu controls *where* the skill is available.
+Use the **Upload** tab. It takes a GitHub repository, a git URL, a local path, a folder, or a `.zip` / `.skill` file.
-<Image src="/images/skills-studio/install-destinations.png" alt="The Install menu lists Claude Code, Cursor, Codex, and the shared source folder, with an All control at the top." width={1600} height={860} />
+<Image src="/images/skills-studio/add-skill-upload.png" alt="The Add skill dialog on the Upload tab, with a repository entered and a picker for which skill to import." width={1600} height={1157} />
-Each checked location gets access to the skill. OpenKnowledge keeps those locations in step when you edit the source. [Manage and share skills](./manage-and-share.mdx) explains scopes and shared folders.
+Skills already in your AI tools' folders show up in the dock on their own. Open one to edit it in place; a read-only plugin skill offers **Edit a copy**.
-## Bring a skill you already have
+<Callout type="warn">
+A skill can include scripts that run on your machine. Read what it does and use sources you trust. OpenKnowledge does not run a skill's scripts during import.
+</Callout>
-Use the **Upload** tab in the add-skill dialog. It accepts:
+## Keep it up to date
-- A GitHub repository, git URL, or local path.
-- A folder on your computer.
-- A `.zip` or `.skill` file.
+An imported skill remembers where it came from.
-Skills already in your AI tools' folders also appear in the dock. Open one to edit it in place; read-only plugin skills offer **Edit a copy**.
+<Snippet file="skill-update-states.mdx" />
-<Callout type="warn">
-A skill can include scripts that run on your machine. Read what it does and use sources you trust. OpenKnowledge does not run a skill's scripts during import.
-</Callout>
+Skills imported from a folder on your own machine stay in sync by default.
diff --git a/docs/content/features/skills/for-teams.mdx b/docs/content/features/skills/for-teams.mdx
new file mode 100644
index 000000000..36835322c
--- /dev/null
+++ b/docs/content/features/skills/for-teams.mdx
@@ -0,0 +1,52 @@
+---
+title: Share skills with your team
+description: Set up the repository your team installs skills from.
+---
+
+Your team's skills live in one Git repository. People install the ones they want and get your later changes as an update they can review. It is a repo, so it already has reviewers, history, and permissions.
+
+<Steps>
+
+<Step>
+
+### Put the skills in one repository
+
+One folder per skill, each with a `SKILL.md`. Nothing else is required.
+
+```text
+team-skills/
+├── code-review/
+│ └── SKILL.md
+├── incident-response/
+│ └── SKILL.md
+└── release-notes/
+ └── SKILL.md
+```
+
+Put in what you would otherwise explain to every new person: how this team writes a design doc, what an incident timeline must contain. Leave out one person's preferences, which belong in their own global skill.
+
+Private repositories work. A public one also appears on [skills.sh](https://skills.sh).
+
+</Step>
+
+<Step>
+
+### Write them in OpenKnowledge
+
+Open the repository itself as an OpenKnowledge project. Each `SKILL.md` is a normal page: its frontmatter shows as properties, the instructions sit below, and it carries the same version history as any other content. Ship a change the way you ship any change: commit and push.
+
+<Image src="/images/skills-studio/skill-in-repo.png" alt="A SKILL.md from a skills repository open as an ordinary page, its name and description shown as properties above the instructions." width={1600} height={916} />
+
+[Write a skill](./write-a-skill.mdx) covers the authoring itself, including having an agent draft one.
+
+</Step>
+
+</Steps>
+
+Then send your team [Install your team's skills](./install-team-skills.mdx) with your repository name.
+
+## What this is not
+
+- Not a hosted store. Distribution is your repository, and permissions are its permissions.
+- Nothing is pushed onto anyone. Every install and update is a person's choice.
+- No team-wide setting. Two people can install different skills into different tools.
diff --git a/docs/content/features/skills/index.mdx b/docs/content/features/skills/index.mdx
index ced938491..394ef427c 100644
--- a/docs/content/features/skills/index.mdx
+++ b/docs/content/features/skills/index.mdx
@@ -79,29 +79,73 @@ buttons.forEach(function(button){button.addEventListener("click",function(){
</script>
```
-## Start here
+## Two ways people use Skills Studio
+
+Both start in the same place and use the same skills. They differ in who the skill is for.
+
+### You are teaching your own AI tools
+
+You explain the same thing to your AI every week: how you like meeting notes written, which folder research goes in. A skill is that explanation, written once and read by every AI tool you use.
+
+You edit it in the same editor as your docs. There is no publish step.
<Cards>
<Card title="Write a skill" href="/docs/features/skills/write-a-skill">
- Turn a task you repeat into instructions your AI can follow.
+ Turn a task you repeat into instructions your AI can follow, by hand or with an agent.
</Card>
<Card title="Find and install skills" href="/docs/features/skills/find-and-install">
Browse the catalog, preview a skill, and choose the tools that get it.
</Card>
- <Card title="Manage and share skills" href="/docs/features/skills/manage-and-share">
- Organize your skills, review updates, and share them between tools.
+ <Card title="Symlink skills" href="/docs/features/skills/symlink-skills">
+ Point one tool's skills folder at another so both read the same skills.
</Card>
- <Card title="Developer reference" href="/docs/features/skills/reference">
- File layout, CLI commands, MCP tools, and configuration.
+ <Card title="Skills OpenKnowledge ships" href="/docs/features/skills/built-in-skills">
+ What each built-in skill does, and how to install or remove it.
</Card>
</Cards>
+### You are setting your team's skills up
+
+Someone has been asked how the team should manage skills: where they live, how a person gets them, how a fix reaches everyone. The answer is a Git repository your team already knows how to review, plus a per-person install that takes a minute.
+
+Nothing is pushed onto anyone. Each person picks the skills they want and how updates arrive. A skill someone adapts stays adapted.
+
+<Cards>
+ <Card title="Share skills with your team" href="/docs/features/skills/for-teams">
+ Set up the repository your team installs from, and decide what goes in it.
+ </Card>
+ <Card title="Install your team's skills" href="/docs/features/skills/install-team-skills">
+ The page to send a teammate. Add the repository, pick skills, done.
+ </Card>
+ <Card title="Keep team skills current" href="/docs/features/skills/team-updates">
+ How a fix reaches everyone, and what happens to a skill someone changed.
+ </Card>
+ <Card title="Distribute as a plugin" href="/docs/features/skills/team-plugins">
+ When a plugin is the better shape, and what you give up by choosing it.
+ </Card>
+</Cards>
+
+## Project or global?
+
+Every skill lives in one of two scopes. You pick when you create or import it, and its menu can move it later.
+
+| Choose | When you want |
+| --- | --- |
+| **Project** | Instructions tied to this knowledge base, such as how to write its meeting notes. Commit the skill's folder to share it through git. |
+| **Global** | Personal instructions available across projects on this machine, such as your writing style. These are not shared through git. |
+
+Moving between scopes starts a new history.
+
## Where to find Skills Studio
-Open **Skills Studio** at the bottom of the file sidebar to write and browse skills. Open **Settings → Skills Studio** for built-in skills and shared folders.
+**Skills Studio** sits at the bottom of the file sidebar. **Settings → Skills Studio** holds the built-in skills and shared folders.
+
+<Image src="/images/skills-studio/skills-dock.png" alt="The Skills Studio dock in the file sidebar, listing project skills above global ones." width={1600} height={1446} />
+
+Skills already in your AI tools appear there on their own, read and versioned where they live.
## See also
+- [Developer reference](/docs/features/skills/reference): file layout, CLI, MCP tools, configuration.
- [Agentic search](/docs/reference/agentic-search): how the agent reads your base.
- [LLM wiki](/docs/workflows/karpathy-llm-wiki): build a source-grounded knowledge base an agent curates, end to end.
-
diff --git a/docs/content/features/skills/install-team-skills.mdx b/docs/content/features/skills/install-team-skills.mdx
new file mode 100644
index 000000000..1fb9ce085
--- /dev/null
+++ b/docs/content/features/skills/install-team-skills.mdx
@@ -0,0 +1,59 @@
+---
+title: Install your team's skills
+description: Add your team's skill repository and install the skills you want, in about a minute.
+---
+
+Someone on your team set up a repository of skills. This page gets them into your AI tools. You need the repository name, such as `your-org/team-skills`, and nothing else.
+
+<Steps>
+
+<Step>
+
+### Open Skills Studio
+
+In OpenKnowledge, expand **Skills Studio** at the bottom of the file sidebar, then click **Explore skills** in its header.
+
+<Image src="/images/skills-studio/skills-dock.png" alt="The Skills Studio dock at the bottom of the file sidebar, with its New skill and Explore skills actions in the header." width={1600} height={1446} />
+
+</Step>
+
+<Step>
+
+### Add the repository
+
+Switch to the **Upload** tab and paste the repository name or URL. OpenKnowledge reads it and, when the source holds more than one skill, asks which one you want.
+
+Choose the **Scope** first: **Project** for a skill tied to this repository, **Global** for one you want on every project on this machine.
+
+<Image src="/images/skills-studio/add-skill-upload.png" alt="The Add skill dialog on the Upload tab, with a repository entered, a Which skill picker, and a summary of what import will do." width={1600} height={1157} />
+
+Private repositories work here too, using the git access you already have.
+
+</Step>
+
+<Step>
+
+### Repeat for each skill you want
+
+Adding the repository does not install everything in it. Import the skills that apply to your work and leave the rest. You can come back for more later.
+
+</Step>
+
+<Step>
+
+### Choose which AI tools get each skill
+
+Open a skill's **Install** menu and check the tools that should read it. Each checked location points at the same source, so the skill cannot drift between your tools.
+
+<Image src="/images/skills-studio/install-destinations.png" alt="The Install menu listing Claude Code, Cursor, Codex, and the shared source folder, with an All control." width={1600} height={860} />
+
+</Step>
+
+</Steps>
+
+A skill is live the moment it lands. There is no separate step to switch it on: give one of those tools a task matching the skill's description and it will use it.
+
+## Next
+
+- [Keep team skills current](./team-updates.mdx): choose how your teammate's later changes reach you.
+- [Symlink skills](./symlink-skills.mdx): share a whole folder between two tools instead of picking per skill.
diff --git a/docs/content/features/skills/manage-and-share.mdx b/docs/content/features/skills/manage-and-share.mdx
deleted file mode 100644
index 3625482f8..000000000
--- a/docs/content/features/skills/manage-and-share.mdx
+++ /dev/null
@@ -1,61 +0,0 @@
----
-title: Manage and share skills
-description: Organize your collection, review updates, and share skills between AI tools.
----
-
-Use the **Skills Studio dock** for your collection and **Settings → Skills Studio** for built-in skills and shared folders.
-
-## Project or global?
-
-| Choose | When you want |
-| --- | --- |
-| **Project** | Instructions tied to this knowledge base, such as how to write its meeting notes. Commit the skill's folder to share it through git. |
-| **Global** | Personal instructions available across projects on this machine, such as your writing style. These are not shared through git. |
-
-A skill's menu lets you move it between Project and Global. Moving scopes starts a new history; the old version history does not transfer.
-
-## Keep your collection tidy
-
-The dock groups imported skills by publisher, repository, or plugin. Your own skills sit at the top.
-
-- **Pin to top** keeps a favorite above the groups.
-- **Group skills by source**, in the sidebar's view options, turns grouping on or off.
-- Drag the divider above the dock to resize it, or focus the divider and press Up or Down. Collapse the dock when you need more room for files.
-
-## Review updates
-
-| What you see | What to do |
-| --- | --- |
-| **Update from source** | Review the diff, then apply the publisher's update. |
-| **Auto-update** | Enable it for an individual remote skill when you want updates applied automatically. It starts off. |
-| **Modified** and **Revert** | Restore the imported original after your own edits. |
-
-Skills imported from a local folder stay in sync by default. A source group's menu also offers **Update all from this source**, with a result for each skill.
-
-## Share folders between tools
-
-Both scopes carry this panel. In **Settings → User → Skills Studio** it links your home folders; in **Settings → This project → Skills Studio** it links the project-local ones. Find **Share skills between AI tools** on either page.
-
-<Image src="/images/skills-studio/skills-settings.png" alt="Share skills between AI tools lists each tool’s folder with a Link button and an Add custom path field." width={1600} height={1080} />
-
-1. Choose **Link** to point one tool's skills folder at another. Both tools then see the same skills.
-2. Use **Add custom path** for a folder OpenKnowledge has not detected.
-3. Choose **Unlink** to turn a linked folder back into a directory that keeps access to its current skills.
-
-If folders contain different versions of the same skill, resolve those differences before linking.
-
-To share only one skill, use its [Install control](./find-and-install.mdx#choose-your-ai-tools) instead.
-
-## Skills OpenKnowledge ships
-
-The first two live in **Settings → User → Skills Studio**; the `open-knowledge` skill lives in **Settings → This project → Skills Studio**.
-
-| Skill | Use it to |
-| --- | --- |
-| `open-knowledge-discovery` | Help an AI recognize and set up an OpenKnowledge project. |
-| `open-knowledge-write-skill` | Have an AI draft and install a new skill. |
-| `open-knowledge` | Teach an AI to read, search, link, and write through this project's OpenKnowledge tools. |
-
-Choose **Install** or **Uninstall** for a built-in skill. **Manage** opens a read-only preview; **Update** appears when a newer copy is available. Built-in skills never update automatically.
-
-They install for your user account. The `open-knowledge` skill installs in project-local editor folders, which are not committed by default. A teammate cloning the repository installs it themselves.
diff --git a/docs/content/features/skills/meta.json b/docs/content/features/skills/meta.json
index 180d2606f..1ab7e4c2e 100644
--- a/docs/content/features/skills/meta.json
+++ b/docs/content/features/skills/meta.json
@@ -1,5 +1,19 @@
{
"title": "Skills Studio",
"icon": "LuGraduationCap",
- "pages": ["index", "write-a-skill", "find-and-install", "manage-and-share", "reference"]
+ "pages": [
+ "index",
+ "---FOR YOUR OWN WORK---",
+ "write-a-skill",
+ "find-and-install",
+ "symlink-skills",
+ "built-in-skills",
+ "---FOR YOUR TEAM---",
+ "for-teams",
+ "install-team-skills",
+ "team-updates",
+ "team-plugins",
+ "---REFERENCE---",
+ "reference"
+ ]
}
diff --git a/docs/content/features/skills/reference.mdx b/docs/content/features/skills/reference.mdx
index 19f372fed..ff22ff04f 100644
--- a/docs/content/features/skills/reference.mdx
+++ b/docs/content/features/skills/reference.mdx
@@ -16,10 +16,12 @@ meeting-notes/
└── scripts/
```
+A new skill goes into a skills folder the project already has. OpenKnowledge never creates one for you: if no agent folder exists yet, the import is refused and names the folders it would accept. When `.agents/` already exists it wins; otherwise the first editor folder present, by precedence.
+
| Scope | Source folder | Other locations |
| --- | --- | --- |
-| Project | `.agents/skills/<name>/` when the hub exists, otherwise an editor's project skills directory | Other project-local editor skills directories |
-| Global | `~/.agents/skills/<name>/` or a home editor skills directory | Other home editor skills directories |
+| Project | The project's existing skills folder (`.agents/skills/<name>/` when `.agents/` is there, else `.claude/skills/<name>/` and so on) | Other project-local editor skills directories |
+| Global | The same, under your home directory | Other home editor skills directories |
OpenKnowledge keeps one source folder per skill. Other locations use symlinks by default, so they read the same bytes. The install menu can convert a location to a copy, which OpenKnowledge refreshes until it is edited independently outside the app.
@@ -29,7 +31,7 @@ OpenKnowledge keeps one source folder per skill. Other locations use symlinks by
OpenKnowledge discovers skills in `.claude/skills`, `.cursor/skills`, `.codex/skills`, `.opencode/skills`, `.github/skills`, `.pi/skills`, `.agents/skills`, and supported plugin locations.
-Detected skills are read and versioned in place. Plugin skills are read-only; **Edit a copy** creates an editable version.
+Detected skills are read and versioned in place. Plugin skills are read-only: **Edit a copy** creates an editable version in your base. Choosing an install destination for a plugin skill does the same thing, because install locations always link to a skill in the base. The copy no longer follows the plugin's updates.
## CLI
@@ -92,11 +94,3 @@ The repo is grouped by role: `skills/core/` holds the built-ins, and `skills/sta
```
`ok seed --pack <id>` installs a pack's skills directly, without the plugin workflow.
-
-<Callout type="info">
-Pack skills were renamed: the generated `open-knowledge-pack-…` names became product names, so `open-knowledge-pack-plain-notes` is now `note-taking` and `open-knowledge-pack-knowledge-base-research` is now `research-with-sources`.
-
-**Skills you already have are not renamed.** Nothing on your disk changes and your `.ok/skills-lock.json` is not rewritten. An existing skill keeps its name, keeps working, and still updates from source. Re-seeding a pack recognizes it and will not install a second copy under the new name. Only newly installed skills use the new names.
-
-Four plugin handles were renamed alongside their packs (`entity-vault` → `personal-crm`, `okf` → `okf-knowledge-base`, `plain-notes` → `note-taking`, `writing-pipeline` → `writing-workflow`). The old handles still resolve for one release and are marked outdated in the marketplace; switch to the new ones. `ok seed --pack <id>` flags are unchanged.
-</Callout>
diff --git a/docs/content/features/skills/symlink-skills.mdx b/docs/content/features/skills/symlink-skills.mdx
new file mode 100644
index 000000000..163566922
--- /dev/null
+++ b/docs/content/features/skills/symlink-skills.mdx
@@ -0,0 +1,31 @@
+---
+title: Symlink skills
+description: Point one AI tool's skills folder at another so both read the same skills.
+---
+
+Every AI tool reads skills from its own folder: `.claude/skills`, `.cursor/skills`, `.codex/skills`, and so on. OpenKnowledge keeps one real folder per skill and links the others to it, so a change reaches every tool without a second copy to keep in sync.
+
+Link at whichever level matches what you want.
+
+| Link this | Where | Use it when |
+| --- | --- | --- |
+| One skill | The skill's **Install** control in the dock | You want a particular skill in particular tools. |
+| A whole folder | **Share skills between AI tools**, in Settings | You want two tools to share everything, now and later. |
+
+## Link one skill
+
+Open the skill's **Install** menu and check the tools that should read it, as in [Find and install skills](./find-and-install.mdx#choose-your-ai-tools). Each checked location points at the one real folder, so it cannot drift.
+
+## Link a whole folder
+
+The panel appears at both scopes: **Settings → User → Skills Studio** links your home folders, **Settings → This project → Skills Studio** the project-local ones.
+
+<Image src="/images/skills-studio/settings-share-folders.png" alt="Share skills between AI tools lists each tool's folder with a Link button, showing Claude and Cursor already sharing one folder." width={1600} height={785} />
+
+1. **Link** points one tool's folder at another. Both tools then see the same skills, including ones you add later.
+2. **Add custom path** includes a folder OpenKnowledge has not detected, such as `~/.myteam/skills`.
+3. **Unlink** turns a linked folder back into a real directory that keeps the skills it has today.
+
+Linking refuses when the two folders hold different versions of the same skill. Resolve that first, then link.
+
+For copies, relocating the source folder, and what OpenKnowledge writes where, see the [developer reference](./reference.mdx#file-layout).
diff --git a/docs/content/features/skills/team-plugins.mdx b/docs/content/features/skills/team-plugins.mdx
new file mode 100644
index 000000000..333df1017
--- /dev/null
+++ b/docs/content/features/skills/team-plugins.mdx
@@ -0,0 +1,30 @@
+---
+title: Distribute as a plugin
+description: When packaging your team's skills as a plugin is the better choice, and what you give up.
+---
+
+A Git repository is the simplest way to get skills to a team. Packaging them as a Claude Code plugin is the other option.
+
+## Choosing
+
+| Your goal | Reach for |
+| --- | --- |
+| A shared folder of instructions the team edits and pulls | [A Git repository](./for-teams.mdx) |
+| A published, versioned artifact for people outside the team | A plugin |
+| Both | The repository first; publish it as a plugin once it has settled |
+
+```bash
+/plugin marketplace add your-org/team-skills
+```
+
+## What a plugin costs
+
+**Plugin skills are read-only here, and getting one into a second tool forks it.**
+
+Every install destination offered for a plugin skill makes one real copy first, at the first location picked, and points the rest at that copy. That happens even when someone only wanted the skill in a second editor. The copy is shared across their tools normally, but it no longer follows the plugin's updates.
+
+The reason is ownership: the plugin folder belongs to the harness, which replaces its files whenever the plugin updates. A link into it would break on the next update, and OpenKnowledge could neither version nor edit what it points at.
+
+So anyone adapting a plugin skill, or spreading it across their tools, quietly leaves the channel you set up. With a repository they stay on it.
+
+Authoring is the same either way: you open the repository as an OpenKnowledge project. The plugin adds distribution, not a place to edit.
diff --git a/docs/content/features/skills/team-updates.mdx b/docs/content/features/skills/team-updates.mdx
new file mode 100644
index 000000000..b2c153a1d
--- /dev/null
+++ b/docs/content/features/skills/team-updates.mdx
@@ -0,0 +1,24 @@
+---
+title: Keep team skills current
+description: How a change to a team skill reaches everyone, and what happens to one somebody adapted.
+---
+
+Every skill installed from a repository remembers where it came from. Nothing is rewritten without the person's say-so: a skill runs instructions inside their agent, so following a source is an explicit choice, made per skill.
+
+<Snippet file="skill-update-states.mdx" />
+
+A source group's menu also offers **Update all from this source**, with a result per skill.
+
+## Rolling out a change
+
+1. Edit the skill in the repository, review it, push.
+2. Anyone with **Auto-update** on gets it on their next run.
+3. Everyone else sees **Update from source** and applies it when ready.
+
+No version to bump, no release to cut. The repository's history is the skill's history.
+
+## When someone adapts a skill
+
+Editing an installed skill pauses its automatic updates, so their change is not overwritten. It shows as **Modified**, and **Revert** puts them back on yours whenever they want.
+
+If several people make the same edit, fold it into the repository so nobody has to make it again.
diff --git a/docs/content/features/skills/write-a-skill.mdx b/docs/content/features/skills/write-a-skill.mdx
index cd7fd643b..688560d86 100644
--- a/docs/content/features/skills/write-a-skill.mdx
+++ b/docs/content/features/skills/write-a-skill.mdx
@@ -5,6 +5,14 @@ description: Turn a task you repeat into instructions your AI tools can follow.
A useful first skill captures something you already explain often: how to summarize a meeting, review a draft, or organize research.
+<Image src="/images/skills-studio/skill-editor.png" alt="A meeting-notes skill in the editor, with its name and description in Properties and numbered instructions below." width={1600} height={1370} />
+
+<Callout type="info">
+**Pro tip.** If you would rather have an agent do the writing, install **open-knowledge-write-skill** first, from **Settings → User → Skills Studio**. Then skip to [Have an agent write it](#have-an-agent-write-it).
+</Callout>
+
+## Write it yourself
+
<Steps>
<Step>
@@ -13,6 +21,8 @@ A useful first skill captures something you already explain often: how to summar
Expand **Skills Studio** at the bottom of the file sidebar. Hover its header and click **New skill**. A new project skill opens in the editor.
+<Image src="/images/skills-studio/skills-dock.png" alt="The Skills Studio dock with New skill and Explore skills in its header, listing project skills above global ones." width={1600} height={1446} />
+
</Step>
<Step>
@@ -25,22 +35,31 @@ The **description** tells your AI when to reach for the skill. Be specific about
> Use when I paste a meeting transcript. Capture decisions, action items, and the person responsible for each one.
-<Image src="/images/skills-studio/skill-editor.png" alt="A meeting-notes skill in the editor, with its name and description in Properties and numbered instructions below." width={1600} height={1370} />
-
</Step>
<Step>
### Write the instructions
-Explain the task as you would to a teammate. Start with a few concrete steps:
+Explain the task as you would to a teammate. Copy this in and change it to match your own folders and conventions:
+
+```markdown
+---
+name: meeting-notes
+description: Use when I paste a meeting transcript. Capture decisions, action items, and the person responsible for each one.
+---
+
+# Meeting notes
-1. Pull out decisions and action items.
-2. Create a note in `meetings/` with the meeting's date and topic.
+1. Pull out the decisions and the action items.
+2. Create a note in `meetings/` named for the meeting's date and topic.
3. Link each person to their page in `people/`.
-4. Add open action items to `todo.md`.
+4. Add every open action item to `todo.md`.
-Use your own folder names and conventions. Edit the skill like any other page; changes save as you work.
+Keep the summary under ten lines. Quote a decision only when the wording matters.
+```
+
+The name and description are the skill's properties; everything below them is what your AI reads. Changes save as you work.
</Step>
@@ -50,12 +69,65 @@ Use your own folder names and conventions. Edit the skill like any other page; c
Open the skill's **Install** control and select the AI tools that should use it. Then give one of those tools a task matching the description, such as a meeting transcript.
+<Image src="/images/skills-studio/install-destinations.png" alt="The Install menu listing Claude Code, Cursor, Codex, and the shared source folder, with an All control at the top." width={1600} height={860} />
+
Refine the instructions after seeing the result. There is no separate publish step.
</Step>
</Steps>
-<Callout type="info">
-Want help drafting it? In **Settings → User → Skills Studio**, install **open-knowledge-write-skill**. Ask your AI: "Write a skill that turns my meeting transcripts into decisions and action items."
-</Callout>
+## Have an agent write it
+
+An agent can draft the skill for you, either from a description or from work you just finished together.
+
+<Steps>
+
+<Step>
+
+### Install the skill that teaches this
+
+Open **Settings → User → Skills Studio**, find **open-knowledge-write-skill**, and choose **Install**. The confirmation lists every folder it will write to. It installs for your user account, so you only do this once per machine.
+
+<Image src="/images/skills-studio/settings-user-skills.png" alt="Settings, User, Skills Studio: the three skills OpenKnowledge ships, each with the AI tools it reaches and a Manage control." width={1600} height={1244} />
+
+</Step>
+
+<Step>
+
+### Ask for the skill you want
+
+Give your AI the task in plain language:
+
+> Write a skill that turns my meeting transcripts into decisions and action items, with each person linked to their page in `people/`.
+
+</Step>
+
+<Step>
+
+### Or turn a session you already had into a skill
+
+The most useful skills come out of work you just did. At the end of a session, ask:
+
+> We just worked out how to review a draft for this project. Turn what we did into a skill so you do it the same way next time.
+
+</Step>
+
+<Step>
+
+### Review it and choose your tools
+
+It appears in the dock and opens in the editor like any other skill. Tighten the description, then use **Install** to choose which AI tools get it.
+
+</Step>
+
+</Steps>
+
+## Edit an existing skill
+
+Skills you already have show up in Skills Studio on their own. There is nothing to import: OpenKnowledge reads the skills folders of your AI tools and lists what it finds, alongside the skills you wrote here.
+
+- Click a skill to open it. Changes save to the skill's own folder, and every tool reading it picks them up.
+- Ask an agent instead: "The `meeting-notes` skill keeps missing action items. Fix its instructions."
+- A plugin skill is read-only; **Edit a copy** gives you an editable version.
+- Editing an imported skill pauses its automatic updates, so your changes stay. See [Keep it up to date](./find-and-install.mdx#keep-it-up-to-date).
diff --git a/docs/next.config.ts b/docs/next.config.ts
index f8e2f641b..cfc825cc3 100644
--- a/docs/next.config.ts
+++ b/docs/next.config.ts
@@ -48,6 +48,16 @@ const nextConfig: NextConfig = {
},
async redirects() {
return [
+ {
+ source: '/docs/features/skills/manage-and-share',
+ destination: '/docs/features/skills/symlink-skills',
+ permanent: true,
+ },
+ {
+ source: '/docs/features/skills/manage-and-share/',
+ destination: '/docs/features/skills/symlink-skills',
+ permanent: true,
+ },
{
source: '/docs/get-started/install',
destination: '/docs/get-started/quickstart',
diff --git a/docs/public/images/skills-studio/add-skill-upload.png b/docs/public/images/skills-studio/add-skill-upload.png
new file mode 100644
index 000000000..7d73e5cfb
Binary files /dev/null and b/docs/public/images/skills-studio/add-skill-upload.png differ
diff --git a/docs/public/images/skills-studio/explore-preview.png b/docs/public/images/skills-studio/explore-preview.png
new file mode 100644
index 000000000..b4cca3482
Binary files /dev/null and b/docs/public/images/skills-studio/explore-preview.png differ
diff --git a/docs/public/images/skills-studio/settings-project-skills.png b/docs/public/images/skills-studio/settings-project-skills.png
new file mode 100644
index 000000000..babd62562
Binary files /dev/null and b/docs/public/images/skills-studio/settings-project-skills.png differ
diff --git a/docs/public/images/skills-studio/settings-share-folders.png b/docs/public/images/skills-studio/settings-share-folders.png
new file mode 100644
index 000000000..0b7f710b8
Binary files /dev/null and b/docs/public/images/skills-studio/settings-share-folders.png differ
diff --git a/docs/public/images/skills-studio/settings-user-skills.png b/docs/public/images/skills-studio/settings-user-skills.png
new file mode 100644
index 000000000..e427697b0
Binary files /dev/null and b/docs/public/images/skills-studio/settings-user-skills.png differ
diff --git a/docs/public/images/skills-studio/skill-in-repo.png b/docs/public/images/skills-studio/skill-in-repo.png
new file mode 100644
index 000000000..118673015
Binary files /dev/null and b/docs/public/images/skills-studio/skill-in-repo.png differ
diff --git a/docs/public/images/skills-studio/skills-dock.png b/docs/public/images/skills-studio/skills-dock.png
new file mode 100644
index 000000000..8dd204be1
Binary files /dev/null and b/docs/public/images/skills-studio/skills-dock.png differ
diff --git a/docs/public/images/skills-studio/skills-settings.png b/docs/public/images/skills-studio/skills-settings.png
deleted file mode 100644
index 2bc187e4f..000000000
Binary files a/docs/public/images/skills-studio/skills-settings.png and /dev/null differ
diff --git a/docs/src/lib/mdx-serializer-registry.ts b/docs/src/lib/mdx-serializer-registry.ts
index 5a93443db..d28f1bd40 100644
--- a/docs/src/lib/mdx-serializer-registry.ts
+++ b/docs/src/lib/mdx-serializer-registry.ts
@@ -1,3 +1,5 @@
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
import { visit } from 'unist-util-visit';
import { AGENTS } from '@/components/agent-icons';
import { mcpInstallMarkdown } from '@/components/mcp-install';
@@ -36,6 +38,12 @@ function codeCell(value: string): string {
const code = inlineCodeSpan;
+function snippet(node: MdxJsxNode, api: SerializerApi): string {
+ const file = requiredLiteral(node, api, 'file');
+ const resolved = path.resolve(process.cwd(), '_snippets', file);
+ return readFileSync(resolved, 'utf8').trim();
+}
+
function titledBlockquote(lead: string | undefined, body: string): string {
const lines = [...(lead ? [`**${escapeInlineProse(lead)}**`, ''] : []), ...body.split('\n')];
return lines.map((line) => (line === '' ? '>' : `> ${line}`)).join('\n');
@@ -290,6 +298,7 @@ export const DOCS_SERIALIZER_REGISTRY: SerializerRegistry = {
].join('\n');
},
Mermaid: mermaid,
+ Snippet: snippet,
Tab: tabPanel,
TabPreview: tabPanel,
Tabs: tabs('Tab'),
diff --git a/knip.config.ts b/knip.config.ts
index 54958b470..11f947931 100644
--- a/knip.config.ts
+++ b/knip.config.ts
@@ -53,6 +53,7 @@ export default {
'packages/desktop/src/shared/ipc-events.ts': ['files'],
'packages/app/src/components/CloneDialog.tsx': ['files'],
'docs/content/**/*.mdx': ['files'],
+ 'docs/_snippets/**/*.mdx': ['files'],
'packages/app/src/components/McpConsentDialogBody.tsx': ['duplicates'],
'packages/core/src/extensions/list.ts': ['duplicates'],
'packages/desktop/src/main/auto-updater.ts': ['types'],