Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

docs(ok): Split Skills Studio into focused visual guides (#4274)

tim-inkeep5ffbc4916845
diff --git a/docs/content/features/editor.mdx b/docs/content/features/editor.mdx
index 262c767c2..785ffed19 100644
--- a/docs/content/features/editor.mdx
+++ b/docs/content/features/editor.mdx
@@ -146,7 +146,7 @@ A folder can describe itself (its own properties, just like a doc's) and offer t
## File sidebar
-The sidebar lists every file in your project on disk, including files excluded by `.gitignore` / `.okignore`, except dot-prefixed entries and tooling internals (`.git/`, `.ok/`, `node_modules/`). Turn on **Show Hidden Files** to reveal the dot-prefixed entries. Folder rows expand and collapse; file rows open in a tab on click. A file with validation problems shows a tinted row and a count badge, and clicking the badge (or tabbing to it and pressing Enter) opens that file with the Problems panel on it, see [Where problems show up](../advanced/content-rules/overview.mdx#where-problems-show-up). The toolbar at the top of the sidebar has buttons to create files, create folders, and search. At the bottom of the sidebar, the collapsible **Skills Studio** dock lists your skills next to your files, so a file and a skill can be open side by side; see [Skills](./skills.mdx#the-skills-studio-dock).
+The sidebar lists every file in your project on disk, including files excluded by `.gitignore` / `.okignore`, except dot-prefixed entries and tooling internals (`.git/`, `.ok/`, `node_modules/`). Turn on **Show Hidden Files** to reveal the dot-prefixed entries. Folder rows expand and collapse; file rows open in a tab on click. A file with validation problems shows a tinted row and a count badge, and clicking the badge (or tabbing to it and pressing Enter) opens that file with the Problems panel on it, see [Where problems show up](../advanced/content-rules/overview.mdx#where-problems-show-up). The toolbar at the top of the sidebar has buttons to create files, create folders, and search. At the bottom of the sidebar, the collapsible **Skills Studio** dock lists your skills next to your files, so a file and a skill can be open side by side; see [Skills Studio](./skills/index.mdx#where-to-find-skills-studio).
### Right-click context menus
diff --git a/docs/content/features/skills.mdx b/docs/content/features/skills.mdx
deleted file mode 100644
index 6f4cfd8e3..000000000
--- a/docs/content/features/skills.mdx
+++ /dev/null
@@ -1,162 +0,0 @@
----
-title: Skills
-icon: LuGraduationCap
-description: "Create, import, version, and install Agent Skills across your editors from one OpenKnowledge source."
----
-
-A skill in OpenKnowledge is content, not a config file: authored or imported in the WYSIWYG editor, versioned with your base, and installed into every editor from one source.
-
-```html preview
-<div style="padding:18px">
- <div class="flow">
- <div class="col">
- <div class="lbl">edit in the WYSIWYG editor</div>
- <div class="ed">
- <div class="h3">Log a fishing trip</div>
- <div class="p">Capture <b>date</b>, spot, and catch, then link the spot.</div>
- <div class="meta">same editor as your docs &middot; versioned</div>
- </div>
- </div>
- <div class="mid"><div class="arr">→</div><div id="inst" class="pill">install</div></div>
- <div class="col">
- <div class="lbl">symlinked into every editor</div>
- <div id="eds" class="eds"></div>
- </div>
- </div>
- <div class="cap">One canonical skill folder, mirrored into each editor. Edit once, no re-install, no drift.</div>
-</div>
-<style>
-.flow{display:grid;grid-template-columns:1.15fr auto 1fr;gap:16px;align-items:center}
-@media(max-width:620px){.flow{grid-template-columns:1fr}.mid .arr{transform:rotate(90deg)}}
-.lbl{font:11px ui-monospace,monospace;text-transform:uppercase;letter-spacing:.04em;color:var(--muted-foreground);margin-bottom:6px}
-.ed{border:1px solid var(--border);border-radius:12px;background:var(--card);padding:13px;box-shadow:0 1px 3px rgba(0,0,0,.06)}
-.ed .h3{font-weight:600;font-size:14.5px}
-.ed .p{color:var(--muted-foreground);font-size:12.5px;margin:5px 0}
-.ed .meta{font-size:11.5px;color:var(--accent-ink)}
-.mid{display:flex;flex-direction:column;align-items:center;gap:7px;color:var(--muted-foreground)}
-.pill{font:700 11px ui-monospace,monospace;text-transform:uppercase;letter-spacing:.04em;border-radius:999px;padding:4px 11px;border:1px solid var(--border);transition:all .3s}
-.pill.on{background:var(--accent-soft);color:var(--accent-ink);border-color:var(--primary)}
-.eds{display:flex;flex-wrap:wrap;gap:7px}
-.eds .chip{border:1px solid var(--border);border-radius:9px;padding:6px 11px;font-size:12.5px;color:var(--muted-foreground);opacity:.5;transition:all .5s}
-.eds .chip.on{opacity:1;border-color:var(--primary);background:var(--accent-soft);color:var(--accent-ink)}
-.cap{margin-top:14px;color:var(--muted-foreground);font-size:12px}
-.cap code{font-size:11.5px}
-</style>
-<script>
-var eds=["Claude Code","Cursor","Codex","OpenCode","Pi"],box=document.getElementById("eds"),inst=document.getElementById("inst"),chips=[];
-eds.forEach(function(e){var c=document.createElement("div");c.className="chip";c.textContent=e;box.appendChild(c);chips.push(c);});
-var reduce=matchMedia("(prefers-reduced-motion:reduce)").matches;
-function run(){
- inst.classList.remove("on");chips.forEach(function(c){c.classList.remove("on");});
- setTimeout(function(){inst.classList.add("on");},250);
- chips.forEach(function(c,i){setTimeout(function(){c.classList.add("on");},500+i*130);});
-}
-run();
-if(!reduce)setInterval(run,3400);
-</script>
-```
-
-## Edit skills like docs
-
-A project skill is not a raw text file you hand-edit in a dotfile. It is a document in your base: written in the same WYSIWYG editor, versioned, with the same backlinks and live preview as the rest of your knowledge. Improving a skill is the same flow as improving any page.
-
-## One source, every editor
-
-A skill is a **real folder** in your agent's skills directory — `.claude/skills`, `.cursor/skills`, `.codex/skills`, `.opencode/skills`, or the vendor-neutral `.agents/skills` hub. OpenKnowledge keeps one real folder per skill name and mirrors it into your other editors. A new location is a symlink to that source by default, since it duplicates no bytes and cannot drift; you can convert any location to an independent copy when you want one, and a new location otherwise follows the form the skill's existing locations already use. Edit the source once and every agent has the change.
-
-## Create, import, and install skills
-
-Skills live in **Skills Studio**, which shows up in two places: a dock at the bottom of the file sidebar, where you author and browse, and a page in Settings, where you install the skills OpenKnowledge ships and decide which folders your AI tools share. The Settings side is covered in [Skills Studio in Settings](#skills-studio-in-settings).
-
-### The Skills Studio dock
-
-The dock sits under the file tree as a collapsible **Skills Studio** section, so a file and a skill can be open side by side. It starts collapsed and remembers its state per machine. Expanded, it takes up to 45% of the window and scrolls on its own, so the file tree always keeps a usable body; drag the handle above it to resize, or focus the handle and press Up / Down. Its toolbar shows on hover or keyboard focus, with two actions:
-
-- **New skill** creates a project-scope skill named `new-skill` (then `new-skill-2`, and so on) and opens its `SKILL.md` as an editor tab. Rename it and fill in the description: the name is the id agents use to invoke it, and the description is what agents match on to decide when to use it.
-- **Explore skills** opens the import dialog. **Explore** searches skills.sh, previews a skill before it lands in your base, and imports it with one click. **Upload** imports from skills.sh, GitHub, a git URL, a local path, a `.zip` / `.skill` archive, or a folder containing `SKILL.md`.
-
-The palette's **Skills** command and an unresolved `/skill-name` link reveal the dock rather than opening a separate page. To hide the dock, untick **Skills Studio** in the sidebar's tree view options, run **Skills section** from the command palette, or set `appearance.sidebar.showSkillsSection` to `false`.
-
-Agents use the same marketplace flow over MCP: `skills({ query: "..." })` searches skills.sh, then `import({ source, skill: name })` imports the selected result.
-
-A skill is live for its agent the moment it lands. There is no separate "install" step to flip. The skill's **install** menu instead controls *where* it is available: add or remove editors, flip any editor between a copy and a symlink, or relocate the canonical source. If a source bundles several skills, OpenKnowledge asks which one to import; scripts are stored as versioned content for review and never run during import.
-
-### Grouped by where they came from
-
-Within each scope, the dock groups skills by source: the skills.sh publisher or GitHub repo they were imported from, or the Claude plugin that ships them. Skills you wrote yourself stay ungrouped at the top of their scope, the way your own files carry no label in the file tree; only content from elsewhere gets a row naming its origin. A source with a single skill collapses onto that skill's row instead of earning a group, and grouping is per scope, so one source can group under Project and sit flat under Global. OpenKnowledge's own built-ins publish to `inkeep/open-knowledge-skills` and group under it like anything else.
-
-A group row leads with the publisher's avatar or the plugin's glyph; when the source resolves to a URL, that mark is a link to it. The group's menu offers **Update all from this source**, which re-pulls every skill in the group in one request (the source is cloned once for the whole batch) and reports per skill how many updated, how many were already current, and which failed and why. One skill that cannot be written does not stop the rest.
-
-A skill row's menu offers **Pin to top** to keep it above the groups. Pins follow the skill's scope: a project pin stays with the repo (`appearance.sidebar.pinnedProjectSkills`, per machine), a global pin follows you into every project (`appearance.sidebar.pinnedGlobalSkills`, per user). A pinned skill keeps its normal row too, so its group still lists everything from that source. Turn grouping off with **Group skills by source** in the tree view options (`appearance.sidebar.showSkillGroups`).
-
-## Skills Studio in Settings
-
-**Settings → Skills Studio** exists at both scopes. It carries the skills OpenKnowledge ships, not the ones you author (those live in the dock), and the folders your AI tools read skills from.
-
-**User scope** (under User) lists **Skills from OpenKnowledge**, the machine-wide bundles: `open-knowledge-discovery` (how to set up new projects with OpenKnowledge) and `open-knowledge-write-skill` (how to write a new skill and install it). Each row shows a one-line description written for a person, the AI tools it reaches, and an Install / Uninstall control behind a confirmation that names every path it will touch. Installing one adds it to every AI tool detected on this machine (`~/.agents/skills/` plus each editor's own skills folder). **Manage** opens the skill's preview tab, which shows the full `SKILL.md` (including the agent-facing trigger text the row leaves out), links to its source, and offers **Update** when the published copy differs. Built-ins never update on their own.
-
-Only the discovery skill is offered at first launch. The first time you open Skills Studio, a short dialog explains the page and offers the authoring skill once, with the same disclosure as the install confirmation. **Not now** is remembered on this machine and the row underneath keeps the skill available; a skill you declined at setup is never re-offered.
-
-**Project scope** (under This project) lists the project's own `open-knowledge` skill: how to use OpenKnowledge and its MCP tools. It lives in the project folder (`.claude/skills/`, `.cursor/skills/`, and the other project-local skill dirs), so once installed it is available to whoever opens the project in that editor. Those folders are not committed by default, so a teammate cloning the repo installs it themselves — OpenKnowledge no longer creates it for them on open. When it is missing, the page says so and offers **Install**.
-
-Both scopes end with **Share skills between AI tools**, the folders each AI tool reads skills from. **Link** points one folder at another so both tools see the same skills, and you add a skill once instead of copying it into every tool. **unlink** turns a folder back into a real directory holding a per-skill symlink for each skill it currently sees, so nothing stops working and each skill's install menu manages it from there. **Add custom path** (`~/.myteam/skills`, `.myteam/skills`) includes a folder OpenKnowledge does not detect on its own. Linking refuses when the two folders hold different versions of the same skill, or when the target holds entries that are not skills; a folder that something outside OpenKnowledge changed is shown as it is on disk, and your next Link / unlink wins.
-
-The **AI tools & CLI** page (User) and **AI tools** page (This project) keep only the *connections*: each editor's MCP entry and the `ok` command. They point at Skills Studio for anything skill-shaped.
-
-A skill can also bundle `references/` and `scripts/` files beside its `SKILL.md`; agents read those through the [`skills` MCP tool](../reference/mcp.mdx).
-
-## Two scopes
-
-- **Project** skills live in the base, versioned and shared with it like any other content.
-- **Global** skills live in your home editor dirs (`~/.agents/skills`, `~/.claude/skills`, …) and follow you across every project on your machine. Outside any base, they carry no version history.
-
-The skill that makes an agent behave well the moment you connect it (read and write through the tools, cite sources, keep the link graph healthy) is the project's built-in `open-knowledge` skill. OpenKnowledge ships it read-only: it shows in the dock grouped under `inkeep/open-knowledge-skills`, and **Settings → This project → Skills Studio** installs or removes it.
-
-Moving a skill between scopes re-creates it in the destination scope: history does not transfer, but the locations it occupied are re-projected for you.
-
-## Skills from your other tools
-
-Skills you already keep in `.claude/skills`, `.cursor/skills`, and the like are versioned **in place, automatically** — OpenKnowledge reads and versions them where they live. There is no store to opt into and no `ok skills manage` switch.
-
-The Skills Studio dock lists what OpenKnowledge found across your other tools: the Claude, Codex, Cursor, OpenCode, Copilot, Pi, and Agents skill dirs, plus Claude plugins. They appear as **Detected** rows. Click one to edit it in place; changes save straight to that editor's own copy. From the CLI, `ok skills installed` lists every skill across your agents (read-only) and `ok skills import <source>` brings a new one in.
-
-<Callout type="warn">
-Skills are an open standard, and a skill can carry scripts that run on your machine. Treat a third-party skill like installing software. Use trusted sources, and read what it does first.
-</Callout>
-
-## Staying up to date
-
-An imported skill records where it came from, so its toolbar can show an **Update from source** action when upstream moves.
-
-Updates from a remote source (skills.sh, GitHub, a git URL) are **not** applied automatically. A skill's instructions run in your agent, so continuing to trust a publisher is an explicit, per-skill opt-in: the **Auto-update** toggle starts off, and until you turn it on you get a diff to review before anything is rewritten. Skills imported from a local path on your own machine stay in sync by default, since the source is already yours.
-
-## Skills we publish
-
-OpenKnowledge's own skills are published at [inkeep/open-knowledge-skills](https://github.com/inkeep/open-knowledge-skills), and they install like any other Claude Code plugin marketplace:
-
-```bash
-/plugin marketplace add inkeep/open-knowledge-skills
-/plugin install open-knowledge@open-knowledge-skills
-```
-
-`open-knowledge` is the platform skill that teaches an agent to read, search, link, and write markdown through the MCP server. The starter packs ship there too, and `ok seed --pack <id>` installs a pack's skills directly.
-
-The repo is grouped by role: `skills/core/` holds the three built-ins, and `skills/starter-packs/<pack>/` holds each pack's skills next to a README explaining the pack. Each pack is also its own plugin, so you can install just the one you want:
-
-```bash
-/plugin install knowledge-base@open-knowledge-skills
-/plugin install personal-crm@open-knowledge-skills
-```
-
-<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 — these are project-level skills that normally live in your git repo, so a silent rename would show up as an unexplained diff for you and everyone who pulls. 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>
-
-## Up next
-
-- **[Agentic search](../reference/agentic-search.mdx)**: how the agent reads your base.
-- **[LLM wiki](../workflows/karpathy-llm-wiki.mdx)**: build a source-grounded knowledge base an agent curates, end to end.
diff --git a/docs/content/features/skills/find-and-install.mdx b/docs/content/features/skills/find-and-install.mdx
new file mode 100644
index 000000000..95461e06b
--- /dev/null
+++ b/docs/content/features/skills/find-and-install.mdx
@@ -0,0 +1,64 @@
+---
+title: Find and install skills
+description: Find a skill, read what it does, and choose the AI tools that can use it.
+---
+
+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
+
+<Steps>
+
+<Step>
+
+### Open the catalog
+
+Hover the **Skills Studio** dock header and click **Explore skills**. Search [skills.sh](https://skills.sh) for a task, such as writing or research.
+
+<Image src="/images/skills-studio/explore-skills.png" alt="The Add skill dialog with Explore selected and results for a writing search." width={1600} height={1630} />
+
+</Step>
+
+<Step>
+
+### Preview before adding
+
+Open a result to read its description, instructions, and bundled files. Check that it fits the task you have in mind.
+
+</Step>
+
+<Step>
+
+### Add it to your collection
+
+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.
+
+</Step>
+
+</Steps>
+
+## Choose your AI tools
+
+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.
+
+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.
+
+<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 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.
+
+## Bring a skill you already have
+
+Use the **Upload** tab in the add-skill dialog. It accepts:
+
+- A GitHub repository, git URL, or local path.
+- A folder on your computer.
+- A `.zip` or `.skill` file.
+
+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**.
+
+<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>
diff --git a/docs/content/features/skills/index.mdx b/docs/content/features/skills/index.mdx
new file mode 100644
index 000000000..ced938491
--- /dev/null
+++ b/docs/content/features/skills/index.mdx
@@ -0,0 +1,107 @@
+---
+title: Skills Studio
+icon: LuGraduationCap
+description: Reusable instructions for the way you work.
+sidebarTitle: Overview
+footer: false
+---
+
+A **skill** tells an AI tool when and how to do a task. Write one beside your notes, then choose the tools that use it.
+
+```html preview
+<section class="skill-flow" aria-label="How one skill works across your AI tools">
+ <div class="flow-heading"><span>ONE SKILL, SHARED INSTRUCTIONS</span><span class="example-label">Try an example</span></div>
+ <div class="examples" role="group" aria-label="Example skill">
+ <button type="button" aria-pressed="true" data-example="meeting">Meeting notes</button>
+ <button type="button" aria-pressed="false" data-example="writing">Writing feedback</button>
+ </div>
+ <div class="flow">
+ <article class="recipe" aria-live="polite">
+ <div class="recipe-label">YOUR SKILL</div>
+ <h3 id="skill-name">meeting-notes</h3>
+ <p id="skill-when">When I share a meeting transcript…</p>
+ <ol id="skill-steps"><li>Capture decisions.</li><li>Assign action items.</li><li>Link the people involved.</li></ol>
+ </article>
+ <div class="connector" aria-hidden="true"><span></span><b>→</b></div>
+ <div class="tools">
+ <div class="recipe-label">YOUR CHOSEN TOOLS</div>
+ <div class="tool"><span>Claude Code</span><span class="status">Reads <b>meeting-notes</b></span></div>
+ <div class="tool"><span>Cursor</span><span class="status">Reads <b>meeting-notes</b></span></div>
+ <div class="tool"><span>Codex</span><span class="status">Reads <b>meeting-notes</b></span></div>
+ <p class="more">And the other tools you install it in.</p>
+ </div>
+ </div>
+ <p class="caption">Change the skill once. The tools you selected read the updated instructions.</p>
+</section>
+<style>
+.skill-flow{padding:24px;background:linear-gradient(135deg,var(--accent-soft),transparent 65%)}
+.flow-heading{display:flex;justify-content:space-between;gap:12px;color:var(--muted-foreground);font-size:10px;letter-spacing:.1em;font-weight:650}
+.example-label{letter-spacing:0;font-weight:400;font-size:12px}
+.examples{display:flex;gap:6px;margin:12px 0 20px;flex-wrap:wrap}
+.examples button{font:inherit;font-size:13px;cursor:pointer;padding:6px 12px;color:var(--muted-foreground);background:var(--card);border:1px solid var(--border);border-radius:999px}
+.examples button[aria-pressed=true]{color:var(--accent-ink);border-color:var(--primary);background:var(--accent-soft)}
+.examples button:hover{border-color:var(--primary)}
+.examples button:focus-visible{outline:2px solid var(--primary);outline-offset:3px}
+.flow{display:grid;grid-template-columns:1.15fr 38px 1fr;align-items:center;gap:12px}
+.recipe{background:var(--card);padding:18px 20px;border:1px solid var(--border);border-radius:14px;box-shadow:0 5px 20px rgba(0,0,0,.03)}
+.recipe-label{font-size:10px;color:var(--muted-foreground);letter-spacing:.08em;font-weight:650}
+.recipe h3{font-family:ui-monospace,monospace;font-size:17px;margin:8px 0 5px;letter-spacing:-.03em}
+.recipe p{font-size:13px;color:var(--muted-foreground);margin:0 0 12px;min-height:39px}
+.recipe ol{font-size:14px;margin:0;padding-left:18px;line-height:1.8}
+.connector{display:flex;align-items:center;color:var(--primary)}
+.connector span{height:1px;background:var(--primary);flex:1;opacity:.45}
+.connector b{font-size:24px;font-weight:400}
+.tools{min-width:0}
+.tools>.recipe-label{margin-bottom:8px}
+.tool{border:1px solid var(--border);background:var(--card);border-radius:10px;padding:10px 12px;margin:7px 0;display:flex;flex-direction:column;gap:2px;font-weight:600;font-size:14px;transition:border-color .25s,transform .25s}
+.status{font-size:11px;font-weight:400;color:var(--muted-foreground)}
+.status b{color:var(--primary);margin-left:4px;font-family:ui-monospace,monospace}
+.more,.caption{color:var(--muted-foreground);font-size:12px}
+.more{margin:8px 0 0}
+.caption{margin:18px 0 0}
+.updating .tool{border-color:var(--primary);transform:translateX(3px)}
+@media(max-width:540px){.skill-flow{padding:18px}.flow{grid-template-columns:1fr;gap:12px}.connector{display:none}.recipe p{min-height:0}.tool{flex-direction:row;justify-content:space-between;align-items:center}.example-label{display:none}}
+@media(prefers-reduced-motion:reduce){.tool{transition:none}.updating .tool{transform:none}}
+</style>
+<script>
+var examples={meeting:{name:"meeting-notes",when:"When I share a meeting transcript…",steps:["Capture decisions.","Assign action items.","Link the people involved."]},writing:{name:"review-my-writing",when:"When I ask for feedback on a draft…",steps:["Lead with the main point.","Replace vague wording.","Keep the writer’s voice."]}};
+var buttons=document.querySelectorAll("[data-example]"),root=document.querySelector(".skill-flow"),steps=document.getElementById("skill-steps"),timer;
+buttons.forEach(function(button){button.addEventListener("click",function(){
+ var item=examples[button.dataset.example];
+ buttons.forEach(function(other){other.setAttribute("aria-pressed",String(other===button));});
+ document.getElementById("skill-name").textContent=item.name;
+ document.getElementById("skill-when").textContent=item.when;
+ steps.replaceChildren(...item.steps.map(function(text){var li=document.createElement("li");li.textContent=text;return li;}));
+ document.querySelectorAll(".tool .status b").forEach(function(el){el.textContent=item.name;});
+ clearTimeout(timer);
+ if(!matchMedia("(prefers-reduced-motion:reduce)").matches){root.classList.add("updating");timer=setTimeout(function(){root.classList.remove("updating");},650);}
+});});
+</script>
+```
+
+## Start here
+
+<Cards>
+ <Card title="Write a skill" href="/docs/features/skills/write-a-skill">
+ Turn a task you repeat into instructions your AI can follow.
+ </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>
+ <Card title="Developer reference" href="/docs/features/skills/reference">
+ File layout, CLI commands, MCP tools, and configuration.
+ </Card>
+</Cards>
+
+## 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.
+
+## See also
+
+- [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/manage-and-share.mdx b/docs/content/features/skills/manage-and-share.mdx
new file mode 100644
index 000000000..3625482f8
--- /dev/null
+++ b/docs/content/features/skills/manage-and-share.mdx
@@ -0,0 +1,61 @@
+---
+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
new file mode 100644
index 000000000..180d2606f
--- /dev/null
+++ b/docs/content/features/skills/meta.json
@@ -0,0 +1,5 @@
+{
+ "title": "Skills Studio",
+ "icon": "LuGraduationCap",
+ "pages": ["index", "write-a-skill", "find-and-install", "manage-and-share", "reference"]
+}
diff --git a/docs/content/features/skills/reference.mdx b/docs/content/features/skills/reference.mdx
new file mode 100644
index 000000000..19f372fed
--- /dev/null
+++ b/docs/content/features/skills/reference.mdx
@@ -0,0 +1,102 @@
+---
+title: Developer reference
+description: Skill file layout, install locations, CLI commands, MCP tools, and sidebar configuration.
+---
+
+For the UI walkthrough, start with [Skills Studio](./index.mdx).
+
+## File layout
+
+A skill is a folder containing `SKILL.md`, with `name` and `description` in its YAML frontmatter. Optional `references/` and `scripts/` folders travel with it.
+
+```text
+meeting-notes/
+├── SKILL.md
+├── references/
+└── scripts/
+```
+
+| 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 |
+
+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.
+
+**Make source** relocates the real folder. Moving between Project and Global recreates the skill and its locations; history does not transfer. Project skills are versioned with project content. Global skills outside a base carry no version history.
+
+## Existing skills
+
+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.
+
+## CLI
+
+```bash
+ok skills installed
+ok skills import <source>
+ok seed --pack <id>
+ok init --skills discovery,write-skill
+ok init --no-skills
+```
+
+| Command | Purpose |
+| --- | --- |
+| `ok skills installed` | List installed skills across agents without changing them. |
+| `ok skills import <source>` | Import from skills.sh, a repository, a git URL, or a local path. |
+| `ok seed --pack <id>` | Install a starter pack's skills. |
+| `ok init --skills discovery,write-skill` | Select built-ins during setup; the default is discovery. |
+| `ok init --no-skills` | Skip skill installation for this setup run. |
+
+See the [CLI reference](../../reference/cli.mdx) for all flags.
+
+## MCP
+
+| Task | Tool |
+| --- | --- |
+| Search skills.sh | `skills({ query })` |
+| Import a skill | `import({ source, add })` |
+| Choose install locations, copies, or symlinks | `install` |
+| Author or change a skill | `write`, `edit`, `move`, `delete` with a `skill` target |
+| Inspect or restore versions | `history`, `restore_version` with a `skill` target |
+| Read a bundled file | `skills({ name, file })` |
+
+See the [MCP reference](../../reference/mcp.mdx) for parameter shapes.
+
+## Sidebar configuration
+
+| Key | Controls |
+| --- | --- |
+| `appearance.sidebar.showSkillsSection` | Whether the dock is visible. |
+| `appearance.sidebar.showSkillGroups` | Grouping by source. |
+| `appearance.sidebar.pinnedProjectSkills` | Pinned project skills. |
+| `appearance.sidebar.pinnedGlobalSkills` | Pinned global skills. |
+
+See [Configuration](../../reference/configuration.mdx) for where these settings live.
+
+## Plugin marketplace
+
+OpenKnowledge's skills and starter packs are published at [inkeep/open-knowledge-skills](https://github.com/inkeep/open-knowledge-skills). For Claude Code's plugin workflow:
+
+```bash
+/plugin marketplace add inkeep/open-knowledge-skills
+/plugin install open-knowledge@open-knowledge-skills
+```
+
+The repo is grouped by role: `skills/core/` holds the built-ins, and `skills/starter-packs/<pack>/` holds each pack's skills. Each pack is also its own plugin, so you can install just the one you want:
+
+```bash
+/plugin install knowledge-base@open-knowledge-skills
+/plugin install personal-crm@open-knowledge-skills
+```
+
+`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/write-a-skill.mdx b/docs/content/features/skills/write-a-skill.mdx
new file mode 100644
index 000000000..cd7fd643b
--- /dev/null
+++ b/docs/content/features/skills/write-a-skill.mdx
@@ -0,0 +1,61 @@
+---
+title: Write a skill
+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.
+
+<Steps>
+
+<Step>
+
+### Create the skill
+
+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.
+
+</Step>
+
+<Step>
+
+### Name it and say when to use it
+
+Give it a short name such as `meeting-notes`. Use lowercase letters, numbers, and hyphens.
+
+The **description** tells your AI when to reach for the skill. Be specific about the situation:
+
+> 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:
+
+1. Pull out decisions and action items.
+2. Create a note in `meetings/` with the meeting's date and topic.
+3. Link each person to their page in `people/`.
+4. Add open action items to `todo.md`.
+
+Use your own folder names and conventions. Edit the skill like any other page; changes save as you work.
+
+</Step>
+
+<Step>
+
+### Choose your tools and try it
+
+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.
+
+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>
diff --git a/docs/content/get-started/overview.mdx b/docs/content/get-started/overview.mdx
index 0a90fa906..385e4ed3c 100644
--- a/docs/content/get-started/overview.mdx
+++ b/docs/content/get-started/overview.mdx
@@ -18,6 +18,7 @@ OpenKnowledge is three layers working together: a WYSIWYG editor for you, MCP an
<LayerStack />
## Additional Features
+- **[Skills Studio](../features/skills/index.mdx)**: write reusable instructions for your AI tools, or find a skill in the catalog.
- **[Ask AI](../features/editor.mdx#ask-ai)** experience: chat with your agent **in app** without leaving OpenKnowledge, or hand the work to an external agent app or the built-in **[TUI](../features/editor.mdx#terminal)** in the desktop app.
- Annotate your knowledge base with **[comments](../features/comments.mdx)**, then resolve them with AI.
- **[Auto-sync](../features/github-sync.mdx)** knowledge base changes with your team using Git.
diff --git a/docs/content/plugins/okf.mdx b/docs/content/plugins/okf.mdx
index df197ab57..d5ce38c69 100644
--- a/docs/content/plugins/okf.mdx
+++ b/docs/content/plugins/okf.mdx
@@ -121,4 +121,4 @@ See the [configuration reference](/docs/reference/configuration) for the surroun
- [Supporting the Open Knowledge Format](/docs/workflows/supporting-open-knowledge-format): start a project with the OKF starter pack
- [Content rules overview](/docs/advanced/content-rules/overview): where warnings appear and how editor, CLI, and agent surfaces agree
- [Frontmatter schemas](/docs/advanced/content-rules/frontmatter): validate frontmatter against your own JSON Schema files
-- [Skills](/docs/features/skills): project skill installation and editing
+- [Skills Studio](/docs/features/skills): project skill installation and editing
diff --git a/docs/content/reference/agentic-search.mdx b/docs/content/reference/agentic-search.mdx
index e1c6a245e..60ea67bf1 100644
--- a/docs/content/reference/agentic-search.mdx
+++ b/docs/content/reference/agentic-search.mdx
@@ -240,7 +240,7 @@ set("ok");
</script>
```
-`brokenLinks` comes back on every write and edit (empty when they all resolve), so the agent never needs a follow-up dead-link check. A brand-new doc nothing points to comes back flagged as an orphan with a hub to link it from. Every write and edit is versioned, attributed, and the preview updates as it lands. Append to a file by hand and the edit still lands: the file watcher folds it into the live doc and versions it, but anonymously, as `file-system`, and nothing talks back. [Skills](../features/skills.mdx) teach the conventions, and the write path enforces the connective tissue.
+`brokenLinks` comes back on every write and edit (empty when they all resolve), so the agent never needs a follow-up dead-link check. A brand-new doc nothing points to comes back flagged as an orphan with a hub to link it from. Every write and edit is versioned, attributed, and the preview updates as it lands. Append to a file by hand and the edit still lands: the file watcher folds it into the live doc and versions it, but anonymously, as `file-system`, and nothing talks back. [Skills](../features/skills/index.mdx) teach the conventions, and the write path enforces the connective tissue.
## The index is authored, not extracted
diff --git a/docs/content/reference/configuration.mdx b/docs/content/reference/configuration.mdx
index 2dacdd825..af5c3052d 100644
--- a/docs/content/reference/configuration.mdx
+++ b/docs/content/reference/configuration.mdx
@@ -46,7 +46,7 @@ A key set in a file more specific than its scope (a user-scope key in `.ok/confi
| `appearance.colorThemeEnabled` | boolean | `true` | user | Whether the Themes plugin appears in **Settings → Plugins**. On by default (absent = enabled). |
| `appearance.customTheme` | object | (unset) | user | The `custom` palette's [base16](https://github.com/tinted-theming/schemes) scheme: sixteen `base00`–`base0F` `#rrggbb` slots, plus optional `name`, `author` (a credit line carried through from an imported scheme), and `variant` (`"dark" \| "light"`, auto-detected from the tonal ramp when absent). A config written before base16 carried six semantic seed colors (`background`/`surface`/`foreground`/`primary`/`accent`/`border`) instead; that shape still parses and is upgraded to the sixteen slots automatically on read. Edit in **Settings → Plugins → Themes**. |
| `appearance.sidebar.showHiddenFiles` | boolean | `false` | project-local | Show files whose path segments start with `.`. The sidebar otherwise lists every file on disk under the content directory; tooling internals (`.git/`, `.ok/`, `node_modules/`) stay hidden regardless. Toggled from the sidebar's right-click menu or the **View → Show Hidden Files** menu item. |
-| `appearance.sidebar.showSkillsSection` | boolean | `true` | project-local | Show the **Skills Studio** dock at the bottom of the file sidebar. Toggled from the sidebar's tree view options or the **Skills section** palette command. See [Skills](/docs/features/skills). |
+| `appearance.sidebar.showSkillsSection` | boolean | `true` | project-local | Show the **Skills Studio** dock at the bottom of the file sidebar. Toggled from the sidebar's tree view options or the **Skills section** palette command. See [Skills Studio](/docs/features/skills). |
| `appearance.sidebar.showSkillGroups` | boolean | `true` | project-local | Group skills in the dock by where they came from: the publisher they were imported from, or the plugin that ships them. Skills you authored stay ungrouped at the top of their scope. Toggled with **Group skills by source** in the tree view options. |
| `appearance.sidebar.pinnedProjectSkills` | string[] | `[]` | project-local | Project-scope skills pinned to the top of the dock, by name. A pinned skill keeps its normal row too, so a source group still lists everything from that source. |
| `appearance.sidebar.pinnedGlobalSkills` | string[] | `[]` | user | Global-scope skills pinned to the top of the dock, by name. Stored per user rather than per project, so a pinned global skill follows you into every project. |
diff --git a/docs/content/reference/mcp.mdx b/docs/content/reference/mcp.mdx
index 1163b790e..7fe907347 100644
--- a/docs/content/reference/mcp.mdx
+++ b/docs/content/reference/mcp.mdx
@@ -32,7 +32,7 @@ To point an MCP client at this server, locally or over a tunnel from another mac
| `delete` | Delete a `document` (one path or an array), `folder`, `template`, `skill`, or `asset` |
| `move` | Move or rename a `document`, `folder`, `asset`, `template`, or `skill`, rewriting every affected link (templates and skills carry no inbound links). A skill also moves between Project and Global scope via `scope` + `toScope`: history does not transfer, and you re-establish its editor locations with `install` |
| `install` | Manage **where** a skill is available. A skill is one real folder (its source, which itself loads) plus managed copies/symlinks at other locations — there is no draft state and no "uninstall everywhere". `add` / `remove` change the other locations (editor ids, `agents`, or custom root paths); `mode` flips an editor copy↔symlink; `source` relocates the real folder. To make a skill stop existing, use `delete` |
-| `import` | Acquire a skill from a full skills.sh skill-page URL (`https://www.skills.sh/<owner>/<repo>/<skill>`, or `https://www.skills.sh/site/<hostname>/<skill>` for a website catalog), `owner/repo[/subpath]`, a git URL, or a local / `file://` path into the vendor-neutral `.agents/skills/<name>/` hub as versioned content — live immediately, with cross-harness projection via `install`. Use `skill` to choose one skill from a multi-skill source or a `skills({ query })` result. Records provenance in `.ok/skills-lock.json`; a name collision lands under `<name>-imported`; scripts are imported as content and never executed |
+| `import` | Acquire a skill from a full skills.sh skill-page URL (`https://www.skills.sh/<owner>/<repo>/<skill>`, or `https://www.skills.sh/site/<hostname>/<skill>` for a website catalog), `owner/repo[/subpath]`, a git URL, or a local / `file://` path into the vendor-neutral `.agents/skills/<name>/` hub as versioned content — live immediately, with cross-harness projection via `install`. Pass the required `add` array with at least one install location (an editor id, `agents`, or a custom root path). Use `skill` to choose one skill from a multi-skill source or a `skills({ query })` result. Records provenance in `.ok/skills-lock.json`; a name collision lands under `<name>-imported`; scripts are imported as content and never executed |
| `checkpoint` | Save a project-wide version snapshot — a single restore point. Returns its `version` |
| `restore_version` | Restore one `document` or `skill` to a historical `version` (the SHA from `history` or `checkpoint`) |
| `conflicts` | Read GitHub-sync merge conflicts. `kind: "list"` enumerates tracked conflicts; `kind: "content"` returns one file's base / ours / theirs stages |
diff --git a/docs/content/reference/what-open-knowledge-writes.mdx b/docs/content/reference/what-open-knowledge-writes.mdx
index ddb65dcc3..b89c41204 100644
--- a/docs/content/reference/what-open-knowledge-writes.mdx
+++ b/docs/content/reference/what-open-knowledge-writes.mdx
@@ -81,7 +81,7 @@ Delete the block and the app **won't re-add it** — the removal is recorded and
### User-global Agent Skills
-OpenKnowledge ships two user-global [Agent Skills](../features/skills.mdx) — `open-knowledge-discovery` (helps your coding agent recognize and route through OpenKnowledge projects) and `open-knowledge-write-skill` (a workflow for authoring new skills). They install into each detected editor's global skill folder (`~/.claude/skills/`, `~/.cursor/skills/`, `~/.codex/skills/`, `~/.opencode/skills/`, `~/.lmstudio/skills/`) plus the shared `~/.agents/skills/` hub.
+OpenKnowledge ships two user-global [Agent Skills](../features/skills/index.mdx) — `open-knowledge-discovery` (helps your coding agent recognize and route through OpenKnowledge projects) and `open-knowledge-write-skill` (a workflow for authoring new skills). They install into each detected editor's global skill folder (`~/.claude/skills/`, `~/.cursor/skills/`, `~/.codex/skills/`, `~/.opencode/skills/`, `~/.lmstudio/skills/`) plus the shared `~/.agents/skills/` hub.
Only `open-knowledge-discovery` is set up at first launch — it is what lets an agent recognize an OpenKnowledge project at all, so it comes with the MCP wiring. `open-knowledge-write-skill` is an authoring convenience with no bearing on whether your tools work, so setup neither installs it nor records a decision about it; it is offered the first time you open **Settings → Skills Studio**, and remains installable there afterwards.
diff --git a/docs/content/workflows/codebase-wiki.mdx b/docs/content/workflows/codebase-wiki.mdx
index fb54c5ac2..70f8bd33d 100644
--- a/docs/content/workflows/codebase-wiki.mdx
+++ b/docs/content/workflows/codebase-wiki.mdx
@@ -87,7 +87,7 @@ ok seed --pack codebase-wiki
The pack scaffolds the `wiki/` tree above with a stubbed `OVERVIEW.md` (empty `source_commit`), a starter template per section (`architecture-page`, `module-page`, `flow-page`, `concept-page`, `guide-page`), and `wiki/log.md`. Each folder's `.ok/frontmatter.yml` teaches the agent that section's job, so guidance lives next to the action rather than inside every page.
<Callout type="info" title="Seeding also installs a skill">
- `ok seed --pack codebase-wiki` installs the **Codebase wiki** project skill into your agent editors (Claude Code, Cursor, Codex, OpenCode). It's the "how to work here" guidance behind the generate / refresh procedure, the audience and depth knobs, and the source-reference discipline — read automatically, and editable like any other doc. It lands as a real `SKILL.md` committed to your repo — one source folder in your project's skills directory (`.agents/skills/` when you have one, otherwise your editor's, e.g. `.claude/skills/`), copied into the skills directory of each editor already set up for the project. The copies refresh from the source until you hand-edit one. See [Skills](../features/skills.mdx) and [what OpenKnowledge writes to disk](../reference/what-open-knowledge-writes.mdx).
+ `ok seed --pack codebase-wiki` installs the **Codebase wiki** project skill into your agent editors (Claude Code, Cursor, Codex, OpenCode). It's the "how to work here" guidance behind the generate / refresh procedure, the audience and depth knobs, and the source-reference discipline — read automatically, and editable like any other doc. It lands as a real `SKILL.md` committed to your repo — one source folder in your project's skills directory (`.agents/skills/` when you have one, otherwise your editor's, e.g. `.claude/skills/`), copied into the skills directory of each editor already set up for the project. The copies refresh from the source until you hand-edit one. See [Skills Studio](../features/skills/index.mdx) and [what OpenKnowledge writes to disk](../reference/what-open-knowledge-writes.mdx).
</Callout>
## Generate, then refresh
diff --git a/docs/content/workflows/entity-vault.mdx b/docs/content/workflows/entity-vault.mdx
index 1ff361c59..40480fdc9 100644
--- a/docs/content/workflows/entity-vault.mdx
+++ b/docs/content/workflows/entity-vault.mdx
@@ -86,7 +86,7 @@ your-project/
Each folder includes an `.ok/frontmatter.yml` description that agents see during file listings/searches, plus templates under `.ok/templates/`.
<Callout type="info" title="Seeding also installs a skill">
- `ok seed --pack entity-vault` installs the **Entity vault** project skill into your agent editors (Claude Code, Cursor, Codex, OpenCode). It's the "how to work here" guidance behind the dossier conventions — compiled-truth vs. append-only timeline, path-qualified links, the correction loop — read automatically, and editable like any other doc. It lands as a single `SKILL.md` in your repo, in your project's skills directory (`.agents/skills/` when you have one, otherwise your editor's), copied into the skills directory of each editor already set up for the project. The copies refresh from the source until you hand-edit one. See [Skills](../features/skills.mdx) and [what OpenKnowledge writes to disk](../reference/what-open-knowledge-writes.mdx).
+ `ok seed --pack entity-vault` installs the **Entity vault** project skill into your agent editors (Claude Code, Cursor, Codex, OpenCode). It's the "how to work here" guidance behind the dossier conventions — compiled-truth vs. append-only timeline, path-qualified links, the correction loop — read automatically, and editable like any other doc. It lands as a single `SKILL.md` in your repo, in your project's skills directory (`.agents/skills/` when you have one, otherwise your editor's), copied into the skills directory of each editor already set up for the project. The copies refresh from the source until you hand-edit one. See [Skills Studio](../features/skills/index.mdx) and [what OpenKnowledge writes to disk](../reference/what-open-knowledge-writes.mdx).
</Callout>
## Markdown shape
diff --git a/docs/content/workflows/karpathy-llm-wiki.mdx b/docs/content/workflows/karpathy-llm-wiki.mdx
index c09159c0d..c5c94cd4c 100644
--- a/docs/content/workflows/karpathy-llm-wiki.mdx
+++ b/docs/content/workflows/karpathy-llm-wiki.mdx
@@ -50,7 +50,7 @@ The difference from a folder of notes or a RAG app is who maintains it, and how
| Over time | it decays | it compounds |
| Can you read it | the notes yes, the index no | all of it, it's just files |
-The structure you and the agent author (folders, titles, backlinks, a one-line purpose per folder) *is* the index. No second copy, nothing to keep in sync. The agent retrieves across it with [agentic search](../reference/agentic-search.mdx) — searching, grepping, and following backlinks over your live files, no vector database — and you teach it conventions with [skills](../features/skills.mdx) authored in the same editor as your docs.
+The structure you and the agent author (folders, titles, backlinks, a one-line purpose per folder) *is* the index. No second copy, nothing to keep in sync. The agent retrieves across it with [agentic search](../reference/agentic-search.mdx) — searching, grepping, and following backlinks over your live files, no vector database — and you teach it conventions with [skills](../features/skills/index.mdx) authored in the same editor as your docs.
The rest of this guide builds one end to end. The pattern is Andrej Karpathy's, from [his April 2026 gist on LLM-curated wikis](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f). OpenKnowledge ships the **Knowledge base** starter pack as a direct implementation, with one extension Karpathy doesn't formalize: **the wiki layer is split** into `research/` (provisional work stored as `status: draft`) and `articles/` (canonical knowledge stored as `status: stable`), with the `consolidate` procedure as the explicit promotion step, so premature canonicalization becomes a thing you opt into rather than something that drifts in.
@@ -162,7 +162,7 @@ You'll get `external-sources/`, `research/`, `articles/`, the three matching tem
The starter-pack picker is idempotent (safe to re-run on the same project).
<Callout type="info" title="Seeding also installs skills">
- `ok seed --pack knowledge-base` (or the desktop starter-pack picker) installs three project skills: `knowledge-base`, `research-with-sources`, and `consolidate-notes`. They carry the layer discipline and provisional-to-canonical promotion described below; the platform skill carries the `ingest` procedure. Each lands as a real `SKILL.md` in your agent editors' skills dirs (`.claude/skills`, `.cursor/skills`, …), versioned with your repo — one canonical copy mirrored into each editor already set up for the project. See [Skills](../features/skills.mdx) and [what OpenKnowledge writes to disk](../reference/what-open-knowledge-writes.mdx).
+ `ok seed --pack knowledge-base` (or the desktop starter-pack picker) installs three project skills: `knowledge-base`, `research-with-sources`, and `consolidate-notes`. They carry the layer discipline and provisional-to-canonical promotion described below; the platform skill carries the `ingest` procedure. Each lands as a real `SKILL.md` in your agent editors' skills dirs (`.claude/skills`, `.cursor/skills`, …), versioned with your repo — one canonical copy mirrored into each editor already set up for the project. See [Skills Studio](../features/skills/index.mdx) and [what OpenKnowledge writes to disk](../reference/what-open-knowledge-writes.mdx).
</Callout>
### 3. Confirm your agent host is wired
diff --git a/docs/content/workflows/plain-notes.mdx b/docs/content/workflows/plain-notes.mdx
index 1816ff374..d2e2cc10d 100644
--- a/docs/content/workflows/plain-notes.mdx
+++ b/docs/content/workflows/plain-notes.mdx
@@ -70,7 +70,7 @@ ok seed --pack plain-notes
The pack creates `notes/` and `daily/` at the project root (no subfolder), each with its `.ok/frontmatter.yml` guidance and template. That's the whole footprint — minimal on purpose.
<Callout type="info" title="Seeding also installs a skill">
- `ok seed --pack plain-notes` installs the **Plain notes** project skill into your agent editors (Claude Code, Cursor, Codex, OpenCode). It's the "how to work here" guidance that gives the agent the linking habit and the daily-chain behavior — read automatically, and editable like any other doc. It lands as a real `SKILL.md` committed to your repo in your project's skills directory (`.agents/skills/` when you have one, otherwise your editor's), copied into the skills directory of each editor already set up for the project. The copies refresh from the source until you hand-edit one. See [Skills](../features/skills.mdx) and [what OpenKnowledge writes to disk](../reference/what-open-knowledge-writes.mdx).
+ `ok seed --pack plain-notes` installs the **Plain notes** project skill into your agent editors (Claude Code, Cursor, Codex, OpenCode). It's the "how to work here" guidance that gives the agent the linking habit and the daily-chain behavior — read automatically, and editable like any other doc. It lands as a real `SKILL.md` committed to your repo in your project's skills directory (`.agents/skills/` when you have one, otherwise your editor's), copied into the skills directory of each editor already set up for the project. The copies refresh from the source until you hand-edit one. See [Skills Studio](../features/skills/index.mdx) and [what OpenKnowledge writes to disk](../reference/what-open-knowledge-writes.mdx).
</Callout>
## Cadence
@@ -87,5 +87,5 @@ The pack creates `notes/` and `daily/` at the project root (no subfolder), each
- **[LLM wiki workflow](./karpathy-llm-wiki.mdx).** When your notes become source-grounded research, this is the pack to graduate to.
- **[Writing pipeline workflow](./writing-pipeline.mdx).** When your notes grow into essays or newsletters, this pack adds ideas → drafts → published stage gates.
- **[Core Concepts](../reference/core-concepts.md).** Links, backlinks, and the well-connected graph that make the emergent structure visible.
-- **[Skills](../features/skills.mdx).** What the installed pack skill is, and how to edit it.
+- **[Skills Studio](../features/skills/index.mdx).** What the installed pack skill is, and how to edit it.
- **[Claude Code](../integrations/claude-code.mdx)**, **[Cursor](../integrations/cursor.mdx)**, **[Codex](../integrations/codex.mdx)**, **[OpenCode](../integrations/opencode.mdx).** MCP-capable agent hosts.
diff --git a/docs/content/workflows/software-lifecycle.mdx b/docs/content/workflows/software-lifecycle.mdx
index b5033be33..0c1c04614 100644
--- a/docs/content/workflows/software-lifecycle.mdx
+++ b/docs/content/workflows/software-lifecycle.mdx
@@ -92,7 +92,7 @@ your-project/
Each folder carries an `.ok/frontmatter.yml` description the agent reads on every directory listing, plus its templates under `.ok/templates/`. That description is where the workflow lives — so the agent knows an accepted proposal graduates to `decisions/`, that ADRs freeze once accepted, and that a new decision superseding an old one links back via `Supersedes:`.
<Callout type="info" title="Seeding also installs a skill">
- `ok seed --pack software-lifecycle` installs the **Software lifecycle** project skill into your agent editors (Claude Code, Cursor, Codex, OpenCode). It's the "how to work here" guidance behind the behaviors below — the status flows, the `Supersedes:` scanning, the postmortem follow-ups — read automatically, and editable like any other doc. It lands as a real `SKILL.md` in your repo, in your project's skills directory (`.agents/skills/` when you have one, otherwise your editor's), copied into the skills directory of each editor already set up for the project. The copies refresh from the source until you hand-edit one. See [Skills](../features/skills.mdx) and [what OpenKnowledge writes to disk](../reference/what-open-knowledge-writes.mdx).
+ `ok seed --pack software-lifecycle` installs the **Software lifecycle** project skill into your agent editors (Claude Code, Cursor, Codex, OpenCode). It's the "how to work here" guidance behind the behaviors below — the status flows, the `Supersedes:` scanning, the postmortem follow-ups — read automatically, and editable like any other doc. It lands as a real `SKILL.md` in your repo, in your project's skills directory (`.agents/skills/` when you have one, otherwise your editor's), copied into the skills directory of each editor already set up for the project. The copies refresh from the source until you hand-edit one. See [Skills Studio](../features/skills/index.mdx) and [what OpenKnowledge writes to disk](../reference/what-open-knowledge-writes.mdx).
</Callout>
## What the agent does for you
diff --git a/docs/content/workflows/worldbuilding.mdx b/docs/content/workflows/worldbuilding.mdx
index 9eca6bb91..ea4c9b675 100644
--- a/docs/content/workflows/worldbuilding.mdx
+++ b/docs/content/workflows/worldbuilding.mdx
@@ -88,7 +88,7 @@ your-project/
Each folder's `.ok/frontmatter.yml` teaches the agent that entity type and what belongs there, so the guidance never clutters the entries themselves.
<Callout type="info" title="Seeding also installs a skill">
- `ok seed --pack worldbuilding` installs the **Worldbuilding** project skill into your agent editors (Claude Code, Cursor, Codex, OpenCode). It's the "how to work here" guidance behind the auto-stub and contradiction-flagging behaviors — read automatically, and editable like any other doc. It lands as one real `SKILL.md` in your project's skills directory (`.agents/skills/` when you have one, otherwise your editor's), committed to your repo and copied into the skills directory of each editor already set up for the project. The copies refresh from the source until you hand-edit one. See [Skills](../features/skills.mdx) and [what OpenKnowledge writes to disk](../reference/what-open-knowledge-writes.mdx).
+ `ok seed --pack worldbuilding` installs the **Worldbuilding** project skill into your agent editors (Claude Code, Cursor, Codex, OpenCode). It's the "how to work here" guidance behind the auto-stub and contradiction-flagging behaviors — read automatically, and editable like any other doc. It lands as one real `SKILL.md` in your project's skills directory (`.agents/skills/` when you have one, otherwise your editor's), committed to your repo and copied into the skills directory of each editor already set up for the project. The copies refresh from the source until you hand-edit one. See [Skills Studio](../features/skills/index.mdx) and [what OpenKnowledge writes to disk](../reference/what-open-knowledge-writes.mdx).
</Callout>
## Cadence
diff --git a/docs/content/workflows/writing-pipeline.mdx b/docs/content/workflows/writing-pipeline.mdx
index 059daa079..4fb82e6e0 100644
--- a/docs/content/workflows/writing-pipeline.mdx
+++ b/docs/content/workflows/writing-pipeline.mdx
@@ -86,7 +86,7 @@ your-project/
Each folder carries its `.ok/frontmatter.yml` guidance and templates. If a draft needs research notes, the agent creates `drafts/<slug>/research/` on demand rather than cluttering the top level.
<Callout type="info" title="Seeding also installs a skill">
- `ok seed --pack writing-pipeline` installs the **Writing pipeline** project skill into your agent editors (Claude Code, Cursor, Codex, OpenCode). It's the "how to work here" guidance behind the behaviors below — the stage promotions, the idle-draft nudges, the publish-time URL fill — read automatically, and editable like any other doc. It lands as a single `SKILL.md` in your project's skills directory (`.agents/skills/` when you have one, otherwise your editor's), committed to your repo and copied into the skills directory of each editor already set up for the project. The copies refresh from the source until you hand-edit one. See [Skills](../features/skills.mdx) and [what OpenKnowledge writes to disk](../reference/what-open-knowledge-writes.mdx).
+ `ok seed --pack writing-pipeline` installs the **Writing pipeline** project skill into your agent editors (Claude Code, Cursor, Codex, OpenCode). It's the "how to work here" guidance behind the behaviors below — the stage promotions, the idle-draft nudges, the publish-time URL fill — read automatically, and editable like any other doc. It lands as a single `SKILL.md` in your project's skills directory (`.agents/skills/` when you have one, otherwise your editor's), committed to your repo and copied into the skills directory of each editor already set up for the project. The copies refresh from the source until you hand-edit one. See [Skills Studio](../features/skills/index.mdx) and [what OpenKnowledge writes to disk](../reference/what-open-knowledge-writes.mdx).
</Callout>
## What the agent does for you
diff --git a/docs/public/images/skills-studio/explore-skills.png b/docs/public/images/skills-studio/explore-skills.png
new file mode 100644
index 000000000..dca157a45
Binary files /dev/null and b/docs/public/images/skills-studio/explore-skills.png differ
diff --git a/docs/public/images/skills-studio/install-destinations.png b/docs/public/images/skills-studio/install-destinations.png
new file mode 100644
index 000000000..38ad7028c
Binary files /dev/null and b/docs/public/images/skills-studio/install-destinations.png differ
diff --git a/docs/public/images/skills-studio/skill-editor.png b/docs/public/images/skills-studio/skill-editor.png
new file mode 100644
index 000000000..7295dbf62
Binary files /dev/null and b/docs/public/images/skills-studio/skill-editor.png differ
diff --git a/docs/public/images/skills-studio/skills-settings.png b/docs/public/images/skills-studio/skills-settings.png
new file mode 100644
index 000000000..2bc187e4f
Binary files /dev/null and b/docs/public/images/skills-studio/skills-settings.png differ
diff --git a/docs/src/lib/markdown-fidelity.real-source.test.ts b/docs/src/lib/markdown-fidelity.real-source.test.ts
index 508ddbeca..5c43e7276 100644
--- a/docs/src/lib/markdown-fidelity.real-source.test.ts
+++ b/docs/src/lib/markdown-fidelity.real-source.test.ts
@@ -1,11 +1,27 @@
+import remarkGfm from 'remark-gfm';
+import remarkParse from 'remark-parse';
+import { unified } from 'unified';
+import { visit } from 'unist-util-visit';
import { describe, expect, test } from 'vitest';
import { getLLMText } from '@/lib/get-llm-text';
import type { FidelityViolation } from '@/lib/markdown-fidelity.test-helper';
import { markdownFidelityViolations } from '@/lib/markdown-fidelity.test-helper';
+import { absoluteSiteUrl, SITE_URL } from '@/lib/site';
import { source } from '@/lib/source';
const pages = source.getPages();
+function hrefsIn(markdown: string): string[] {
+ const tree = unified().use(remarkParse).use(remarkGfm).parse(markdown);
+ const urls: string[] = [];
+ visit(tree, (node) => {
+ if (node.type === 'link' || node.type === 'image' || node.type === 'definition') {
+ urls.push(node.url);
+ }
+ });
+ return urls;
+}
+
describe('every page the real loader hands to the Markdown pipeline', () => {
test('is a census, so a broken content glob cannot vacuously pass this suite', () => {
expect(pages.length).toBeGreaterThan(50);
@@ -18,6 +34,20 @@ describe('every page the real loader hands to the Markdown pipeline', () => {
}
expect(violations.map((violation) => violation.message)).toEqual([]);
});
+
+ test('resolves every docs href to a page the loader actually serves', async () => {
+ const pageUrls = new Set(pages.map((page) => absoluteSiteUrl(page.url)));
+ const failures: string[] = [];
+ for (const page of pages) {
+ for (const href of hrefsIn(await getLLMText(page))) {
+ const target = href.split(/[#?]/)[0] ?? href;
+ if (target.startsWith(`${SITE_URL}/docs/`) && !pageUrls.has(target)) {
+ failures.push(`${page.url}: resolved docs href is not a page (${target})`);
+ }
+ }
+ }
+ expect(failures).toEqual([]);
+ });
});
describe('the real loader derives a page from its file', () => {
diff --git a/docs/src/lib/mdx-serializer-registry.test.ts b/docs/src/lib/mdx-serializer-registry.test.ts
index b1f0106c7..cbc873f34 100644
--- a/docs/src/lib/mdx-serializer-registry.test.ts
+++ b/docs/src/lib/mdx-serializer-registry.test.ts
@@ -1,3 +1,6 @@
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
import remarkGfm from 'remark-gfm';
import remarkMdx from 'remark-mdx';
import remarkParse from 'remark-parse';
@@ -141,6 +144,12 @@ describe('inputs the registry refuses rather than serializes wrong', () => {
);
});
+ test('an Image becomes a markdown image, not a plain link', () => {
+ expect(serialize('<Image src="/images/x.png" alt="A skill" />')).toBe(
+ '![A skill](https://openknowledge.ai/images/x.png)',
+ );
+ });
+
test('names the absent case differently from the unreadable one', () => {
expect(() => serialize('<img alt="Editor" />')).toThrow('<img> has no `src`');
});
@@ -349,6 +358,21 @@ describe('the docs corpus through the real registry', () => {
expect(output.size).toBe(pages.length);
});
+ test('every <Image src> in the corpus resolves to a file under public/', () => {
+ const PUBLIC_DIR = fileURLToPath(new URL('../../public/', import.meta.url));
+ const missing: string[] = [];
+ let seen = 0;
+ for (const page of pages) {
+ for (const match of page.source.matchAll(/<Image\b[^>]*\bsrc="([^"]+)"/g)) {
+ const src = match[1];
+ seen += 1;
+ if (!existsSync(path.join(PUBLIC_DIR, src))) missing.push(`${page.slug}: ${src}`);
+ }
+ }
+ expect(seen).toBeGreaterThan(0);
+ expect(missing).toEqual([]);
+ });
+
test('no page leaks a JSX element into the Markdown it serves', () => {
const leaks: string[] = [];
for (const [slug, md] of output) {
diff --git a/docs/src/lib/mdx-serializer.test.ts b/docs/src/lib/mdx-serializer.test.ts
index 59b5ea8c6..3747392e0 100644
--- a/docs/src/lib/mdx-serializer.test.ts
+++ b/docs/src/lib/mdx-serializer.test.ts
@@ -197,6 +197,26 @@ describe('link rewriting', () => {
'https://openknowledge.ai/docs/get-started/quickstart#section',
],
['an image', '![a](/screenshots/x.png)', 'https://openknowledge.ai/screenshots/x.png'],
+ [
+ 'an extensionless route named index',
+ '[a](/api/index?q=1#item)',
+ 'https://openknowledge.ai/api/index?q=1#item',
+ ],
+ [
+ 'a folder index, which fumadocs serves at the folder URL',
+ '[a](../features/skills/index.mdx)',
+ 'https://openknowledge.ai/docs/features/skills',
+ ],
+ [
+ 'a fragment on a folder index',
+ '[a](./skills/index.mdx#where-to-find-skills-studio)',
+ 'https://openknowledge.ai/docs/get-started/skills#where-to-find-skills-studio',
+ ],
+ [
+ 'a folder index named from inside its own folder',
+ '[a](./index.mdx)',
+ 'https://openknowledge.ai/docs/get-started',
+ ],
])('absolutises %s', (_label, source, expected) => {
expect(body(source)).toContain(`(${expected})`);
});
@@ -301,6 +321,7 @@ describe('componentNames', () => {
describe('the docs content corpus', () => {
const CONTENT_ROOT = fileURLToPath(new URL('../../content/', import.meta.url));
+ const DOCS_ORIGIN = 'https://openknowledge.ai';
const FLATTEN_EVERY_COMPONENT = new Proxy(
{},
{
@@ -349,6 +370,7 @@ describe('the docs content corpus', () => {
test('serializes every page with no parse failures and no source-form links', async () => {
const failures: string[] = [];
+ const pageUrls = new Set(files.map(pageUrlFor));
await Promise.all(
files.map(async (file) => {
@@ -370,6 +392,10 @@ describe('the docs content corpus', () => {
if (/\.mdx($|[#?])/.test(href)) {
failures.push(`${rel}: source-form .mdx href survived (${href})`);
}
+ const target = href.split(/[#?]/)[0] ?? href;
+ if (target.startsWith(`${DOCS_ORIGIN}/docs/`) && !pageUrls.has(target)) {
+ failures.push(`${rel}: resolved docs href is not a page (${target})`);
+ }
}
}),
);
diff --git a/docs/src/lib/mdx-serializer.ts b/docs/src/lib/mdx-serializer.ts
index ed123aa66..3ee194ae2 100644
--- a/docs/src/lib/mdx-serializer.ts
+++ b/docs/src/lib/mdx-serializer.ts
@@ -57,6 +57,7 @@ const FRONTMATTER_BLOCK = /^---[ \t]*\r?\n(?:([\s\S]*?)\r?\n)?---[ \t]*(?:\r?\n|
const ABSOLUTE_URL = /^[a-zA-Z][a-zA-Z0-9+.-]*:|^\/\//;
const SOURCE_EXTENSION = /\.mdx?$/;
+const FOLDER_INDEX = /(^|\/)index$/;
const NON_PROSE_TYPES = new Set(['mdxjsEsm', 'mdxFlowExpression', 'mdxTextExpression']);
@@ -203,7 +204,13 @@ function absolutise(url: string, base: URL): string {
const suffixAt = url.search(/[#?]/);
const path = suffixAt === -1 ? url : url.slice(0, suffixAt);
const suffix = suffixAt === -1 ? '' : url.slice(suffixAt);
- return new URL(path.replace(SOURCE_EXTENSION, '') + suffix, base).href;
+ const target = path.replace(SOURCE_EXTENSION, '');
+ if (!SOURCE_EXTENSION.test(path) || !FOLDER_INDEX.test(target)) {
+ return new URL(target + suffix, base).href;
+ }
+ const folder = new URL(target.replace(FOLDER_INDEX, '$1./'), base);
+ folder.pathname = folder.pathname.replace(/(.)\/$/, '$1');
+ return folder.href + suffix;
}
function transformChildren(