Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
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.mdxnew file mode 100644index 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.mdxnew file mode 100644index 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.mdxindex 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 uStart 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.mdxnew file mode 100644index 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.mdxindex 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.mdxnew file mode 100644index 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.mdxdeleted file mode 100644index 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.jsonindex 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.mdxindex 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 byOpenKnowledge 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.mdxnew file mode 100644index 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.mdxnew file mode 100644index 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.mdxnew file mode 100644index 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.mdxindex 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 summarExpand **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; cOpen 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.tsindex 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.pngnew file mode 100644index 000000000..7d73e5cfbBinary files /dev/null and b/docs/public/images/skills-studio/add-skill-upload.png differdiff --git a/docs/public/images/skills-studio/explore-preview.png b/docs/public/images/skills-studio/explore-preview.pngnew file mode 100644index 000000000..b4cca3482Binary files /dev/null and b/docs/public/images/skills-studio/explore-preview.png differdiff --git a/docs/public/images/skills-studio/settings-project-skills.png b/docs/public/images/skills-studio/settings-project-skills.pngnew file mode 100644index 000000000..babd62562Binary files /dev/null and b/docs/public/images/skills-studio/settings-project-skills.png differdiff --git a/docs/public/images/skills-studio/settings-share-folders.png b/docs/public/images/skills-studio/settings-share-folders.pngnew file mode 100644index 000000000..0b7f710b8Binary files /dev/null and b/docs/public/images/skills-studio/settings-share-folders.png differdiff --git a/docs/public/images/skills-studio/settings-user-skills.png b/docs/public/images/skills-studio/settings-user-skills.pngnew file mode 100644index 000000000..e427697b0Binary files /dev/null and b/docs/public/images/skills-studio/settings-user-skills.png differdiff --git a/docs/public/images/skills-studio/skill-in-repo.png b/docs/public/images/skills-studio/skill-in-repo.pngnew file mode 100644index 000000000..118673015Binary files /dev/null and b/docs/public/images/skills-studio/skill-in-repo.png differdiff --git a/docs/public/images/skills-studio/skills-dock.png b/docs/public/images/skills-studio/skills-dock.pngnew file mode 100644index 000000000..8dd204be1Binary files /dev/null and b/docs/public/images/skills-studio/skills-dock.png differdiff --git a/docs/public/images/skills-studio/skills-settings.png b/docs/public/images/skills-studio/skills-settings.pngdeleted file mode 100644index 2bc187e4f..000000000Binary files a/docs/public/images/skills-studio/skills-settings.png and /dev/null differdiff --git a/docs/src/lib/mdx-serializer-registry.ts b/docs/src/lib/mdx-serializer-registry.tsindex 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.tsindex 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'],