Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

feat(open-knowledge): surface built-in open-knowledge skill read-only in Skills UI (#2664)

Andrew Mikofalvyb27391041542
diff --git a/.changeset/skill-open-knowledge-readonly-visibility.md b/.changeset/skill-open-knowledge-readonly-visibility.md
new file mode 100644
index 000000000..272d69646
--- /dev/null
+++ b/.changeset/skill-open-knowledge-readonly-visibility.md
@@ -0,0 +1,10 @@
+---
+"@inkeep/open-knowledge": minor
+---
+
+Surface OpenKnowledge's built-in `open-knowledge` project skill in the Skills UI
+as a read-only, "Managed by OpenKnowledge" entry. It was previously hidden, so
+you could not see what your agents actually load. You can now open and read its
+SKILL.md (and references) from the Skills sidebar and Settings; edit, rename,
+delete, and install are disabled in the UI, and the skill write/rename/delete
+APIs refuse mutations to the reserved built-in skills (defense in depth).
diff --git a/packages/app/src/components/SkillRow.tsx b/packages/app/src/components/SkillRow.tsx
index a9a9cbe71..c510843fc 100644
--- a/packages/app/src/components/SkillRow.tsx
+++ b/packages/app/src/components/SkillRow.tsx
@@ -1,6 +1,6 @@
import type { SkillsListEntry } from '@inkeep/open-knowledge-core';
import { Trans, useLingui } from '@lingui/react/macro';
-import { DownloadCloud, MoreVertical } from 'lucide-react';
+import { DownloadCloud, Lock, MoreVertical } from 'lucide-react';
import { OpenInAgentMenu } from '@/components/handoff/OpenInAgentMenu';
import { buildSkillHandoffInput } from '@/components/handoff/useHandoffDispatch';
import { SkillStateBadge } from '@/components/SkillStateBadge';
@@ -66,7 +66,14 @@ export function SkillRow({
>
<span className="flex w-full items-center gap-2">
<code className="truncate font-mono font-medium">{skill.name}</code>
- <SkillStateBadge installed={skill.installed} className="text-2xs" />
+ {skill.managed ? (
+ <Badge variant="gray" className="gap-1 text-2xs" title={t`Managed by OpenKnowledge`}>
+ <Lock className="size-3" aria-hidden />
+ <Trans>Managed</Trans>
+ </Badge>
+ ) : (
+ <SkillStateBadge installed={skill.installed} className="text-2xs" />
+ )}
</span>
{skill.description ? (
<span className="block w-full truncate text-sm text-muted-foreground">
@@ -93,39 +100,45 @@ export function SkillRow({
<span className="shrink-0 self-center opacity-0 group-hover:opacity-100 focus-within:opacity-100 data-[state=open]:opacity-100">
<OpenInAgentMenu input={handoffInput} />
</span>
- <Button
- type="button"
- variant="ghost"
- size="sm"
- className="shrink-0 self-center font-mono uppercase opacity-0 group-hover:opacity-100 focus-visible:opacity-100"
- onClick={onInstall}
- disabled={installing}
- data-testid={`skill-install-${skill.name}`}
- >
- <DownloadCloud className="size-3.5" aria-hidden />
- {skill.installed ? <Trans>Installed</Trans> : <Trans>Install</Trans>}
- </Button>
- <DropdownMenu>
- <DropdownMenuTrigger asChild>
+ {/* A managed built-in skill is read-only: no Install button, no
+ edit/uninstall/delete menu. The row body still opens it to read. */}
+ {skill.managed ? null : (
+ <>
<Button
+ type="button"
variant="ghost"
- size="icon"
- className="size-7 shrink-0 self-center opacity-0 group-hover:opacity-100 focus-visible:opacity-100 data-[state=open]:opacity-100"
- aria-label={t`Actions for ${skill.name}`}
+ size="sm"
+ className="shrink-0 self-center font-mono uppercase opacity-0 group-hover:opacity-100 focus-visible:opacity-100"
+ onClick={onInstall}
+ disabled={installing}
+ data-testid={`skill-install-${skill.name}`}
>
- <MoreVertical className="size-4" aria-hidden />
+ <DownloadCloud className="size-3.5" aria-hidden />
+ {skill.installed ? <Trans>Installed</Trans> : <Trans>Install</Trans>}
</Button>
- </DropdownMenuTrigger>
- <DropdownMenuContent align="end" className="min-w-52">
- {/* Install stays a dedicated button on this row, so the menu omits it. */}
- <SkillActionMenuItems
- skill={skill}
- onEdit={onEdit}
- onUninstall={onUninstall}
- onDelete={onDelete}
- />
- </DropdownMenuContent>
- </DropdownMenu>
+ <DropdownMenu>
+ <DropdownMenuTrigger asChild>
+ <Button
+ variant="ghost"
+ size="icon"
+ className="size-7 shrink-0 self-center opacity-0 group-hover:opacity-100 focus-visible:opacity-100 data-[state=open]:opacity-100"
+ aria-label={t`Actions for ${skill.name}`}
+ >
+ <MoreVertical className="size-4" aria-hidden />
+ </Button>
+ </DropdownMenuTrigger>
+ <DropdownMenuContent align="end" className="min-w-52">
+ {/* Install stays a dedicated button on this row, so the menu omits it. */}
+ <SkillActionMenuItems
+ skill={skill}
+ onEdit={onEdit}
+ onUninstall={onUninstall}
+ onDelete={onDelete}
+ />
+ </DropdownMenuContent>
+ </DropdownMenu>
+ </>
+ )}
</li>
);
}
diff --git a/packages/app/src/components/SkillsSidebarSection.tsx b/packages/app/src/components/SkillsSidebarSection.tsx
index e42472e55..4f6649eaa 100644
--- a/packages/app/src/components/SkillsSidebarSection.tsx
+++ b/packages/app/src/components/SkillsSidebarSection.tsx
@@ -5,6 +5,7 @@ import {
FileCode,
FileText,
Hexagon,
+ Lock,
MoreHorizontal,
Plus,
RefreshCw,
@@ -239,7 +240,16 @@ function SkillFolderItem({
<RefreshCw className="size-3 text-primary" aria-label={t`Update available`} />
</span>
) : null}
- <SkillStateBadge installed={skill.installed} subtle className="shrink-0" />
+ {skill.managed ? (
+ <span title={t`Managed by OpenKnowledge (read-only)`} className="flex items-center">
+ <Lock
+ className="size-3 text-muted-foreground"
+ aria-label={t`Managed by OpenKnowledge (read-only)`}
+ />
+ </span>
+ ) : (
+ <SkillStateBadge installed={skill.installed} subtle className="shrink-0" />
+ )}
</span>
</SidebarMenuButton>
</CollapsibleTrigger>
@@ -332,13 +342,8 @@ function SkillFolderContents({ skill }: { skill: SkillsListEntry }) {
// a global skill (its files live under `~/.ok/skills/`, outside the project),
// so routing those through the asset path 404'd; the skill-file target reads
// the right store per scope.
- function openFile(filePath: string) {
- const dot = filePath.lastIndexOf('.');
- const ext = dot >= 0 ? filePath.slice(dot + 1).toLowerCase() : '';
- if (skill.scope === 'project' && (ext === 'md' || ext === 'mdx')) {
- openProjectDoc(projectSkillFilePath(skill.name, filePath.replace(/\.mdx?$/i, '')));
- return;
- }
+ // Open ANY skill file (incl. `SKILL.md`) in the read-only bundle-file viewer.
+ function openReadonlyFile(filePath: string) {
const target = {
kind: 'skill-file' as const,
target: `${skill.scope}/${skill.name}/${filePath}`,
@@ -352,6 +357,22 @@ function SkillFolderContents({ skill }: { skill: SkillsListEntry }) {
);
}
+ function openFile(filePath: string) {
+ // A managed built-in skill (`open-knowledge`) has no editable content doc, so
+ // every file, including `.md` references, opens read-only.
+ if (skill.managed) {
+ openReadonlyFile(filePath);
+ return;
+ }
+ const dot = filePath.lastIndexOf('.');
+ const ext = dot >= 0 ? filePath.slice(dot + 1).toLowerCase() : '';
+ if (skill.scope === 'project' && (ext === 'md' || ext === 'mdx')) {
+ openProjectDoc(projectSkillFilePath(skill.name, filePath.replace(/\.mdx?$/i, '')));
+ return;
+ }
+ openReadonlyFile(filePath);
+ }
+
useEffect(() => {
let active = true;
const load = () => {
@@ -386,9 +407,11 @@ function SkillFolderContents({ skill }: { skill: SkillsListEntry }) {
<SidebarMenuSubButton
size="sm"
onClick={() =>
- skill.scope === 'project'
- ? openProjectDoc(projectSkillContentDocName(skill.name))
- : openManagedArtifactTab(skillLiveDocName(skill.scope, skill.name))
+ skill.managed
+ ? openReadonlyFile('SKILL.md')
+ : skill.scope === 'project'
+ ? openProjectDoc(projectSkillContentDocName(skill.name))
+ : openManagedArtifactTab(skillLiveDocName(skill.scope, skill.name))
}
className="text-[11px]"
>
diff --git a/packages/app/src/components/settings/SkillsManagerSection.dom.test.tsx b/packages/app/src/components/settings/SkillsManagerSection.dom.test.tsx
index bde5bd086..8377f9527 100644
--- a/packages/app/src/components/settings/SkillsManagerSection.dom.test.tsx
+++ b/packages/app/src/components/settings/SkillsManagerSection.dom.test.tsx
@@ -136,4 +136,30 @@ describe('SkillsManagerSection', () => {
render(<SkillsManagerSection />);
await waitFor(() => expect(screen.getByTestId('settings-skills-error')).toBeDefined());
});
+
+ test('a managed built-in skill renders read-only: no Install, no actions menu, "Managed" label', async () => {
+ mockSkillsResponse({
+ skills: [
+ {
+ name: 'open-knowledge',
+ description: 'The OpenKnowledge project skill.',
+ scope: 'project',
+ path: '.claude/skills/open-knowledge/SKILL.md',
+ installed: true,
+ hosts: ['claude'],
+ managed: true,
+ },
+ ],
+ truncated: false,
+ });
+
+ render(<SkillsManagerSection />);
+
+ const row = await waitFor(() => screen.getByTestId('skill-row-open-knowledge'));
+ // Labeled as managed / read-only.
+ expect(row.textContent).toContain('Managed');
+ // No mutation affordances: no Install button, no 3-dot actions menu.
+ expect(screen.queryByTestId('skill-install-open-knowledge')).toBeNull();
+ expect(screen.queryByRole('button', { name: 'Actions for open-knowledge' })).toBeNull();
+ });
});
diff --git a/packages/app/src/components/settings/SkillsManagerSection.tsx b/packages/app/src/components/settings/SkillsManagerSection.tsx
index 83e58cc29..95fae278c 100644
--- a/packages/app/src/components/settings/SkillsManagerSection.tsx
+++ b/packages/app/src/components/settings/SkillsManagerSection.tsx
@@ -10,7 +10,7 @@ import { Button } from '@/components/ui/button';
import { Skeleton } from '@/components/ui/skeleton';
import { useSkills } from '@/hooks/use-skills';
import { skillLiveDocName } from '@/lib/managed-artifact-doc-name';
-import { openManagedArtifactTab } from '@/lib/open-managed-artifact-tab';
+import { openManagedArtifactTab, openSkillFileTab } from '@/lib/open-managed-artifact-tab';
import { SKILL_SCOPE_ORDER, useSkillScopeLabels } from '@/lib/skill-scope';
import { useSettingsRoute } from '@/lib/use-settings-route';
@@ -64,8 +64,14 @@ export function SkillsManagerSection() {
// editing a skill is editing a document (the tab + sidebar + chrome are the
// doc shell). Setting the artifact hash also closes Settings (it's hash-driven),
// so the explicit close() is a belt-and-suspenders no-op once the hash flips.
- function openSkillTab(scope: SkillScope, name: string) {
- openManagedArtifactTab(skillLiveDocName(scope, name));
+ // A managed built-in skill (`open-knowledge`) has no editable content doc, so
+ // its `SKILL.md` opens in the read-only bundle-file viewer instead.
+ function openSkillTab(skill: Pick<SkillsListEntry, 'scope' | 'name' | 'managed'>) {
+ if (skill.managed) {
+ openSkillFileTab({ scope: skill.scope, name: skill.name, path: 'SKILL.md' });
+ } else {
+ openManagedArtifactTab(skillLiveDocName(skill.scope, skill.name));
+ }
settingsRoute.close();
}
@@ -131,7 +137,7 @@ export function SkillsManagerSection() {
scope={scope}
skills={skills}
installingName={actions.installingName}
- onEdit={(skill) => openSkillTab(skill.scope, skill.name)}
+ onEdit={(skill) => openSkillTab(skill)}
onDelete={actions.requestDelete}
onInstall={actions.install}
onUninstall={actions.uninstall}
@@ -146,7 +152,7 @@ export function SkillsManagerSection() {
defaultScope="project"
open={newSkillOpen}
onOpenChange={setNewSkillOpen}
- onCreated={({ scope, name }) => openSkillTab(scope, name)}
+ onCreated={({ scope, name }) => openSkillTab({ scope, name })}
/>
</section>
);
diff --git a/packages/app/src/components/skill-actions.tsx b/packages/app/src/components/skill-actions.tsx
index a06389e09..f3dfcdcf0 100644
--- a/packages/app/src/components/skill-actions.tsx
+++ b/packages/app/src/components/skill-actions.tsx
@@ -9,6 +9,7 @@ import {
CopyPlus,
DownloadCloud,
FolderOpen,
+ Lock,
Pencil,
PencilLine,
PowerOff,
@@ -28,6 +29,7 @@ import { SkillRenameDialog } from '@/components/SkillRenameDialog';
import { SkillUpdateDialog } from '@/components/SkillUpdateDialog';
import {
DropdownMenuItem,
+ DropdownMenuLabel,
DropdownMenuSeparator,
DropdownMenuSub,
DropdownMenuSubContent,
@@ -286,6 +288,49 @@ export function SkillContextMenuItems({
}
}
+ // OK's built-in `open-knowledge` skill is managed + read-only: offer only the
+ // non-mutating actions (reveal / open-in-agent / copy path). No Duplicate,
+ // Rename, Install, Uninstall, or Delete, since editing it isn't possible.
+ if (skill.managed) {
+ return (
+ <>
+ <DropdownMenuLabel className="flex items-center gap-1.5 text-muted-foreground">
+ <Lock className="size-3" aria-hidden />
+ <Trans>Managed by OpenKnowledge</Trans>
+ </DropdownMenuLabel>
+ <DropdownMenuSeparator />
+ {bridge && absolutePath ? (
+ <DropdownMenuItem onSelect={() => void bridge.shell.showItemInFolder(absolutePath)}>
+ <FolderOpen aria-hidden />
+ <Trans>Reveal in Finder</Trans>
+ </DropdownMenuItem>
+ ) : null}
+ <OpenInAgentContextSubmenu
+ input={buildSkillHandoffInput({ skillName: skill.name, scope: skill.scope, workspace })}
+ installStates={installStates}
+ isElectronHost={bridge != null}
+ dispatch={dispatch}
+ />
+ <DropdownMenuSub>
+ <DropdownMenuSubTrigger>
+ <Copy aria-hidden />
+ <Trans>Copy Path</Trans>
+ </DropdownMenuSubTrigger>
+ <DropdownMenuSubContent>
+ {absolutePath ? (
+ <DropdownMenuItem onSelect={() => void copy(absolutePath)}>
+ <Trans>Full Path</Trans>
+ </DropdownMenuItem>
+ ) : null}
+ <DropdownMenuItem onSelect={() => void copy(skill.path)}>
+ <Trans>Relative Path</Trans>
+ </DropdownMenuItem>
+ </DropdownMenuSubContent>
+ </DropdownMenuSub>
+ </>
+ );
+ }
+
return (
<>
{bridge && absolutePath ? (
diff --git a/packages/app/src/lib/open-managed-artifact-tab.ts b/packages/app/src/lib/open-managed-artifact-tab.ts
index 0a773f7d6..5ad853d30 100644
--- a/packages/app/src/lib/open-managed-artifact-tab.ts
+++ b/packages/app/src/lib/open-managed-artifact-tab.ts
@@ -1,4 +1,4 @@
-import { hashFromDocName } from '@/lib/doc-hash';
+import { hashFromDocName, hashFromSkillFile, type SkillFileHashTarget } from '@/lib/doc-hash';
/**
* Open a managed-artifact doc (skill/template) as the ACTIVE editor tab.
@@ -17,3 +17,16 @@ export function openManagedArtifactTab(docName: string): void {
const hash = hashFromDocName(docName);
if (window.location.hash !== hash) window.location.hash = hash;
}
+
+/**
+ * Open a skill bundle file (`SKILL.md` / `references/**` / `scripts/**`) in the
+ * READ-ONLY viewer, by the same hash-nav mechanism as {@link openManagedArtifactTab}.
+ * Used for OK's built-in `open-knowledge` skill (managed, read-only): it has no
+ * editable CRDT content doc, so its `SKILL.md` opens through the scope-aware
+ * `/api/skill-file` viewer rather than the editor.
+ */
+export function openSkillFileTab(target: SkillFileHashTarget): void {
+ if (typeof window === 'undefined') return;
+ const hash = hashFromSkillFile(target);
+ if (window.location.hash !== hash) window.location.hash = hash;
+}
diff --git a/packages/app/src/locales/en/messages.json b/packages/app/src/locales/en/messages.json
index 6eefa9923..3633924c3 100644
--- a/packages/app/src/locales/en/messages.json
+++ b/packages/app/src/locales/en/messages.json
@@ -1314,6 +1314,7 @@
"U2pMtf": ["tag-name"],
"U3IvM5": ["Full guide"],
"U5Spo9": ["Content directory must be inside the project"],
+ "U7HJ4y": ["Managed by OpenKnowledge (read-only)"],
"U8CD-l": ["Copy full path, No workspace"],
"UBv8UK": ["Delete Permanently"],
"UDFrWm": ["Checking GitHub connection..."],
@@ -1379,6 +1380,7 @@
"VFQXPl": [
"External link previews show a card with the site name, page title, and description when you hover a link."
],
+ "VITWk5": ["Managed by OpenKnowledge"],
"VIwCaD": ["Entry"],
"VM7H66": ["This file is binary and can't be shown as text."],
"VNgKZz": ["Advanced settings"],
@@ -2585,6 +2587,7 @@
"wVa83H": ["Couldn't create the report"],
"wXO4Tg": [["hrs"], "h ago"],
"w_Sphq": ["Attachments"],
+ "waFx9W": ["Managed"],
"wbv9xO": ["Create new project"],
"wbwHYD": ["Enable sync"],
"wccmX0": [
diff --git a/packages/app/src/locales/en/messages.po b/packages/app/src/locales/en/messages.po
index 3b12ad6ee..a1080e491 100644
--- a/packages/app/src/locales/en/messages.po
+++ b/packages/app/src/locales/en/messages.po
@@ -4530,6 +4530,19 @@ msgstr "Manage hidden files in Settings → Ignore patterns."
msgid "Manage the GitHub account OpenKnowledge uses to browse and sync your repositories."
msgstr "Manage the GitHub account OpenKnowledge uses to browse and sync your repositories."
+#: src/components/SkillRow.tsx
+msgid "Managed"
+msgstr "Managed"
+
+#: src/components/skill-actions.tsx
+#: src/components/SkillRow.tsx
+msgid "Managed by OpenKnowledge"
+msgstr "Managed by OpenKnowledge"
+
+#: src/components/SkillsSidebarSection.tsx
+msgid "Managed by OpenKnowledge (read-only)"
+msgstr "Managed by OpenKnowledge (read-only)"
+
#: src/components/settings/AiToolsSection.tsx
msgid "Managing AI tools is unavailable in this build."
msgstr "Managing AI tools is unavailable in this build."
diff --git a/packages/app/src/locales/pseudo/messages.json b/packages/app/src/locales/pseudo/messages.json
index 54cabc030..649769fe6 100644
--- a/packages/app/src/locales/pseudo/messages.json
+++ b/packages/app/src/locales/pseudo/messages.json
@@ -1314,6 +1314,7 @@
"U2pMtf": ["ţàĝ-ńàḿē"],
"U3IvM5": ["Ƒũĺĺ ĝũĩďē"],
"U5Spo9": ["Ćōńţēńţ ďĩŕēćţōŕŷ ḿũśţ ƀē ĩńśĩďē ţĥē ƥŕōĴēćţ"],
+ "U7HJ4y": ["Ḿàńàĝēď ƀŷ ŌƥēńĶńōŵĺēďĝē (ŕēàď-ōńĺŷ)"],
"U8CD-l": ["Ćōƥŷ ƒũĺĺ ƥàţĥ, Ńō ŵōŕķśƥàćē"],
"UBv8UK": ["Ďēĺēţē Ƥēŕḿàńēńţĺŷ"],
"UDFrWm": ["Ćĥēćķĩńĝ ĜĩţĤũƀ ćōńńēćţĩōń..."],
@@ -1379,6 +1380,7 @@
"VFQXPl": [
"Ēxţēŕńàĺ ĺĩńķ ƥŕēvĩēŵś śĥōŵ à ćàŕď ŵĩţĥ ţĥē śĩţē ńàḿē, ƥàĝē ţĩţĺē, àńď ďēśćŕĩƥţĩōń ŵĥēń ŷōũ ĥōvēŕ à ĺĩńķ."
],
+ "VITWk5": ["Ḿàńàĝēď ƀŷ ŌƥēńĶńōŵĺēďĝē"],
"VIwCaD": ["Ēńţŕŷ"],
"VM7H66": ["Ţĥĩś ƒĩĺē ĩś ƀĩńàŕŷ àńď ćàń'ţ ƀē śĥōŵń àś ţēxţ."],
"VNgKZz": ["Àďvàńćēď śēţţĩńĝś"],
@@ -2585,6 +2587,7 @@
"wVa83H": ["Ćōũĺďń'ţ ćŕēàţē ţĥē ŕēƥōŕţ"],
"wXO4Tg": [["hrs"], "ĥ àĝō"],
"w_Sphq": ["Àţţàćĥḿēńţś"],
+ "waFx9W": ["Ḿàńàĝēď"],
"wbv9xO": ["Ćŕēàţē ńēŵ ƥŕōĴēćţ"],
"wbwHYD": ["Ēńàƀĺē śŷńć"],
"wccmX0": [
diff --git a/packages/app/src/locales/pseudo/messages.po b/packages/app/src/locales/pseudo/messages.po
index 09f58f11a..65f505957 100644
--- a/packages/app/src/locales/pseudo/messages.po
+++ b/packages/app/src/locales/pseudo/messages.po
@@ -4525,6 +4525,19 @@ msgstr ""
msgid "Manage the GitHub account OpenKnowledge uses to browse and sync your repositories."
msgstr ""
+#: src/components/SkillRow.tsx
+msgid "Managed"
+msgstr ""
+
+#: src/components/skill-actions.tsx
+#: src/components/SkillRow.tsx
+msgid "Managed by OpenKnowledge"
+msgstr ""
+
+#: src/components/SkillsSidebarSection.tsx
+msgid "Managed by OpenKnowledge (read-only)"
+msgstr ""
+
#: src/components/settings/AiToolsSection.tsx
msgid "Managing AI tools is unavailable in this build."
msgstr ""
diff --git a/packages/app/tests/integration/api-error-envelope/skill-builtin-readonly.test.ts b/packages/app/tests/integration/api-error-envelope/skill-builtin-readonly.test.ts
new file mode 100644
index 000000000..59570430a
--- /dev/null
+++ b/packages/app/tests/integration/api-error-envelope/skill-builtin-readonly.test.ts
@@ -0,0 +1,163 @@
+/**
+ * Integration coverage for OK's built-in `open-knowledge` project skill being
+ * surfaced READ-ONLY through the skills API.
+ *
+ * The built-in skill is force-installed into the editor host dirs
+ * (`.claude/skills/open-knowledge/`), NOT `.ok/skills`, so it is normally
+ * invisible to the Skills UI. These tests write a fake on-disk projection into
+ * the harness's project dir and assert:
+ * - `GET /api/skills` lists it as a `managed` entry (installed, host = claude).
+ * - `GET /api/skill` + `GET /api/skill-file` serve its SKILL.md + references
+ * read-only (from the host dir, not `.ok/skills`).
+ * - every mutation (PUT / POST rename / DELETE / install / PUT file) is refused
+ * with `urn:ok:error:reserved-doc-name` (the defense-in-depth server gate,
+ * independent of the UI hiding those controls).
+ * - a refused DELETE leaves the on-disk file intact.
+ */
+
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import {
+ ProblemDetailsSchema,
+ SkillGetSuccessSchema,
+ SkillsListSuccessSchema,
+} from '@inkeep/open-knowledge-core';
+import { HARNESS_BOOT_TIMEOUT_MS } from '../harness-boot-timeout';
+import { createTestServer, type TestServer } from '../test-harness';
+
+let server: TestServer;
+const base = () => `http://127.0.0.1:${server.port}`;
+
+const SKILL_MD = `---
+name: open-knowledge
+description: The OpenKnowledge project skill agents load for this KB.
+---
+
+# Open Knowledge
+
+Route reads and writes through the MCP tools.
+`;
+const REFERENCE_MD = '# Setup\n\nRun `ok init` first.\n';
+
+let builtinSkillMd: string;
+
+beforeAll(async () => {
+ server = await createTestServer();
+ // Fake the on-disk editor projection the reclaim/init path would install.
+ const dir = join(server.contentDir, '.claude', 'skills', 'open-knowledge');
+ mkdirSync(join(dir, 'references'), { recursive: true });
+ builtinSkillMd = join(dir, 'SKILL.md');
+ writeFileSync(builtinSkillMd, SKILL_MD, 'utf-8');
+ writeFileSync(join(dir, 'references', 'setup.md'), REFERENCE_MD, 'utf-8');
+}, HARNESS_BOOT_TIMEOUT_MS);
+
+afterAll(async () => {
+ await server.cleanup();
+});
+
+describe('built-in open-knowledge skill: read-only surfacing', () => {
+ test('GET /api/skills includes it as a managed entry', async () => {
+ const res = await fetch(`${base()}/api/skills`);
+ expect(res.status).toBe(200);
+ const parsed = SkillsListSuccessSchema.safeParse(await res.json());
+ expect(parsed.success).toBe(true);
+ if (!parsed.success) return;
+ const entry = parsed.data.skills.find((s) => s.name === 'open-knowledge');
+ expect(entry).toBeDefined();
+ expect(entry?.managed).toBe(true);
+ expect(entry?.scope).toBe('project');
+ expect(entry?.installed).toBe(true);
+ expect(entry?.hosts).toContain('claude');
+ expect(entry?.description).toBe('The OpenKnowledge project skill agents load for this KB.');
+ });
+
+ test('GET /api/skill serves its body + references from the host dir', async () => {
+ const res = await fetch(`${base()}/api/skill?name=open-knowledge&scope=project`);
+ expect(res.status).toBe(200);
+ const parsed = SkillGetSuccessSchema.safeParse(await res.json());
+ expect(parsed.success).toBe(true);
+ if (!parsed.success) return;
+ expect(parsed.data.skill.managed).toBe(true);
+ expect(parsed.data.skill.body).toContain('Route reads and writes through the MCP tools.');
+ const ref = parsed.data.skill.files?.find((f) => f.path === 'references/setup.md');
+ expect(ref?.text).toContain('Run `ok init` first.');
+ });
+
+ test('GET /api/skill-file serves SKILL.md read-only (skill-dir root)', async () => {
+ const res = await fetch(
+ `${base()}/api/skill-file?name=open-knowledge&scope=project&path=SKILL.md`,
+ );
+ expect(res.status).toBe(200);
+ const body = (await res.json()) as { text?: string };
+ expect(body.text).toContain('# Open Knowledge');
+ });
+
+ test('GET /api/skill-file serves a reference read-only', async () => {
+ const res = await fetch(
+ `${base()}/api/skill-file?name=open-knowledge&scope=project&path=references/setup.md`,
+ );
+ expect(res.status).toBe(200);
+ const body = (await res.json()) as { text?: string };
+ expect(body.text).toContain('# Setup');
+ });
+
+ const expectReserved = async (res: Response) => {
+ expect(res.status).toBe(400);
+ const parsed = ProblemDetailsSchema.safeParse(await res.json());
+ expect(parsed.success && parsed.data.type).toBe('urn:ok:error:reserved-doc-name');
+ };
+
+ test('PUT /api/skill is refused', async () => {
+ const res = await fetch(`${base()}/api/skill`, {
+ method: 'PUT',
+ headers: { 'Content-Type': 'application/json' },
+ body: JSON.stringify({
+ name: 'open-knowledge',
+ body: 'hijacked',
+ frontmatter: { name: 'open-knowledge', description: 'hijacked' },
+ }),
+ });
+ await expectReserved(res);
+ });
+
+ test('POST /api/skill rename is refused', async () => {
+ const res = await fetch(`${base()}/api/skill`, {
+ method: 'POST',
+ headers: { 'Content-Type': 'application/json' },
+ body: JSON.stringify({ scope: 'project', fromName: 'open-knowledge', toName: 'my-skill' }),
+ });
+ await expectReserved(res);
+ });
+
+ test('POST /api/skill/install is refused', async () => {
+ const res = await fetch(`${base()}/api/skill/install`, {
+ method: 'POST',
+ headers: { 'Content-Type': 'application/json' },
+ body: JSON.stringify({ scope: 'project', name: 'open-knowledge' }),
+ });
+ await expectReserved(res);
+ });
+
+ test('PUT /api/skill-file is refused', async () => {
+ const res = await fetch(`${base()}/api/skill-file`, {
+ method: 'PUT',
+ headers: { 'Content-Type': 'application/json' },
+ body: JSON.stringify({
+ scope: 'project',
+ name: 'open-knowledge',
+ path: 'references/evil.md',
+ content: 'x',
+ }),
+ });
+ await expectReserved(res);
+ });
+
+ test('DELETE /api/skill is refused and leaves the on-disk file intact', async () => {
+ const res = await fetch(`${base()}/api/skill?name=open-knowledge&scope=project`, {
+ method: 'DELETE',
+ });
+ await expectReserved(res);
+ expect(existsSync(builtinSkillMd)).toBe(true);
+ });
+});
diff --git a/packages/core/src/schemas/api/tags-search.ts b/packages/core/src/schemas/api/tags-search.ts
index 959e04133..df1697036 100644
--- a/packages/core/src/schemas/api/tags-search.ts
+++ b/packages/core/src/schemas/api/tags-search.ts
@@ -395,6 +395,11 @@ export const SkillPayloadSchema = z
}),
)
.optional(),
+ /** True for OpenKnowledge's own built-in `open-knowledge*` skills, served
+ * from the on-disk editor projection (`.claude/skills/...`) READ-ONLY. The
+ * UI labels these "Managed by OpenKnowledge" and disables edit/rename/delete;
+ * the write/rename/delete APIs also refuse them (defense in depth). */
+ managed: z.boolean().optional(),
})
.strict() satisfies StandardSchemaV1;
export type SkillPayload = z.infer<typeof SkillPayloadSchema>;
@@ -440,6 +445,11 @@ export const SkillsListEntrySchema = z
installedVersion: z.string().optional(),
bundledVersion: z.string().optional(),
updateAvailable: z.boolean().optional(),
+ /** True for OpenKnowledge's own built-in `open-knowledge*` skills (the ones
+ * projected into editor host dirs, e.g. `.claude/skills/open-knowledge`).
+ * They are READ-ONLY: surfaced so users can see what their agents load, but
+ * edit/rename/delete/install are disabled in the UI and refused by the API. */
+ managed: z.boolean().optional(),
})
.strict() satisfies StandardSchemaV1;
export type SkillsListEntry = z.infer<typeof SkillsListEntrySchema>;
diff --git a/packages/server/src/api-extension.ts b/packages/server/src/api-extension.ts
index 5b4df8aaa..e005ee2c6 100644
--- a/packages/server/src/api-extension.ts
+++ b/packages/server/src/api-extension.ts
@@ -76,6 +76,7 @@ import {
DuplicatePathRequestSchema,
DuplicatePathSuccessSchema,
detectFmRegion,
+ EDITOR_PROJECT_SKILL_ROOT,
type EditorId,
EmbedDetectSuccessSchema,
EmptyRequestSchema,
@@ -378,6 +379,7 @@ import {
computeShareTargetStatus,
SHARE_TARGET_STATUS_HANDLER_TAG,
} from './share/target-status.ts';
+import { BUNDLE_SKILL_NAME, isInternalBundleSkillName } from './skill-bundles.ts';
import { buildAndOpenSkill } from './skill-install.ts';
import { readSkillManagement, writeSkillManagement } from './skill-management.ts';
import {
@@ -14001,6 +14003,102 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {
: resolve(contentDir, '.ok', 'skills');
}
+ // OK's built-in project skill (`open-knowledge`) is NOT authored under
+ // `.ok/skills`; it is force-installed into the editor host dirs
+ // (`.claude/skills/open-knowledge/`, `.cursor/skills/...`, …). Surface it in
+ // the skills index READ-ONLY so users can see exactly what their agents load.
+ const BUILTIN_PROJECT_SKILL_NAME = BUNDLE_SKILL_NAME.project;
+
+ /**
+ * Resolve the on-disk installed copy of the built-in `open-knowledge` project
+ * skill across the editor host dirs, preferring Claude (the first entry in
+ * `PROJECT_SKILL_EDITOR_IDS`). Returns the chosen skill dir + its `SKILL.md` +
+ * every host id it is projected into + the project-relative path, or null when
+ * there is no project or no host copy exists yet.
+ */
+ function resolveBuiltinProjectSkillDir(): {
+ dir: string;
+ skillMd: string;
+ hosts: string[];
+ relPath: string;
+ } | null {
+ if (!projectDir) return null;
+ const hosts: string[] = [];
+ let chosenDir: string | null = null;
+ for (const editorId of PROJECT_SKILL_EDITOR_IDS) {
+ const root = EDITOR_PROJECT_SKILL_ROOT[editorId];
+ if (!root) continue;
+ const dir = resolve(projectDir, ...root.split('/'), BUILTIN_PROJECT_SKILL_NAME);
+ if (!existsSync(resolve(dir, 'SKILL.md'))) continue;
+ hosts.push(editorId);
+ if (chosenDir === null) chosenDir = dir;
+ }
+ if (chosenDir === null) return null;
+ const skillMd = resolve(chosenDir, 'SKILL.md');
+ return {
+ dir: chosenDir,
+ skillMd,
+ hosts,
+ relPath: relative(projectDir, skillMd).split(/[\\/]/).filter(Boolean).join('/'),
+ };
+ }
+
+ /**
+ * The managed, read-only skills-list entry for the built-in `open-knowledge`
+ * project skill, read from its on-disk projection. Returns null when it isn't
+ * installed (no host copy). Marked `managed: true` so the UI labels it and
+ * disables mutation; the write/rename/delete APIs refuse it independently.
+ */
+ function builtinProjectSkillListEntry(): {
+ name: string;
+ description?: string;
+ scope: 'project';
+ path: string;
+ absolutePath: string;
+ installed: boolean;
+ hosts: string[];
+ managed: true;
+ } | null {
+ const resolved = resolveBuiltinProjectSkillDir();
+ if (!resolved) return null;
+ let description: string | undefined;
+ try {
+ const { frontmatter } = parseFrontmatterDoc(readFileSync(resolved.skillMd, 'utf-8'));
+ if (typeof frontmatter.description === 'string') description = frontmatter.description;
+ } catch {
+ // Malformed SKILL.md: still list it (without a description) so it's visible.
+ }
+ return {
+ name: BUILTIN_PROJECT_SKILL_NAME,
+ ...(description !== undefined ? { description } : {}),
+ scope: 'project',
+ path: resolved.relPath,
+ absolutePath: resolved.skillMd,
+ installed: resolved.hosts.length > 0,
+ hosts: resolved.hosts,
+ managed: true,
+ };
+ }
+
+ /**
+ * Refuse a MUTATION (write / rename / delete / install / …) that targets one of
+ * OK's built-in bundle skills (`open-knowledge*`). They are managed by
+ * OpenKnowledge: read-only in both the UI and the API. Returns true (and
+ * writes the error) when `name` is reserved, so callers early-return; the UI
+ * already hides these controls, this is the defense-in-depth server gate.
+ */
+ function rejectReservedBuiltinSkill(name: string, res: ServerResponse, handler: string): boolean {
+ if (!isInternalBundleSkillName(name)) return false;
+ errorResponse(
+ res,
+ 400,
+ 'urn:ok:error:reserved-doc-name',
+ `"${name}" is a built-in skill managed by OpenKnowledge and can't be edited, renamed, or deleted.`,
+ { handler },
+ );
+ return true;
+ }
+
/**
* Build the folder-addressed `__template__/<folderRel>/<name>` CRDT doc name.
* Each path segment is percent-encoded so `parseManagedArtifactName` decodes
@@ -14158,8 +14256,20 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {
// an installed skill — the install handler also drops empty markers.
return { ...skill, installed: hosts.length > 0, hosts, ...update };
});
+ // Append OK's built-in `open-knowledge` project skill (read from its
+ // on-disk editor projection, e.g. `.claude/skills/open-knowledge/`) as a
+ // managed, read-only entry, unless the project already authors a real
+ // `.ok/skills/open-knowledge` (the reserved-name gate normally prevents
+ // this, but a pre-existing one wins to avoid a duplicate row).
+ const builtin = project.skills.some((s) => s.name === BUILTIN_PROJECT_SKILL_NAME)
+ ? null
+ : builtinProjectSkillListEntry();
const enriched = {
- skills: [...enrich(project, projectInstalled), ...enrich(globalSkills, globalInstalled)],
+ skills: [
+ ...enrich(project, projectInstalled),
+ ...enrich(globalSkills, globalInstalled),
+ ...(builtin ? [builtin] : []),
+ ],
truncated: project.truncated || globalSkills.truncated,
};
successResponse(res, 200, SkillsListSuccessSchema, enriched, { handler: 'skills-list' });
@@ -14266,6 +14376,40 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {
if (!validateSkillName(name, res, 'skill-get')) return;
const scope = parseSkillScope(url.searchParams.get('scope'), res, 'skill-get');
if (scope === null) return;
+
+ // The built-in `open-knowledge` project skill lives in the editor host
+ // dirs, not `.ok/skills`, so serve its on-disk installed copy read-only
+ // so the Skills UI can open + display exactly what agents load.
+ if (name === BUILTIN_PROJECT_SKILL_NAME && scope === 'project') {
+ const builtin = resolveBuiltinProjectSkillDir();
+ if (builtin) {
+ const { frontmatter, body } = parseFrontmatterDoc(
+ await readFile(builtin.skillMd, 'utf-8'),
+ );
+ successResponse(
+ res,
+ 200,
+ SkillGetSuccessSchema,
+ {
+ skill: {
+ name,
+ scope,
+ path: builtin.relPath,
+ frontmatter: {
+ name: typeof frontmatter.name === 'string' ? frontmatter.name : name,
+ description:
+ typeof frontmatter.description === 'string' ? frontmatter.description : '',
+ },
+ body,
+ files: readSkillBundledFiles(builtin.dir),
+ managed: true,
+ },
+ },
+ { handler: 'skill-get' },
+ );
+ return;
+ }
+ }
const skillsRoot = resolveSkillsRoot(scope);
const skillMd = resolve(skillsRoot, name, 'SKILL.md');
@@ -14327,6 +14471,7 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {
return;
}
if (!validateSkillName(body.name, res, 'skill-put')) return;
+ if (rejectReservedBuiltinSkill(body.name, res, 'skill-put')) return;
// Compose + validate the SKILL.md bytes server-side (OK
// builds name+description). The body itself is then written through the
@@ -14429,6 +14574,7 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {
const url = new URL(req.url ?? '', 'http://localhost');
const name = url.searchParams.get('name') ?? '';
if (!validateSkillName(name, res, 'skill-delete')) return;
+ if (rejectReservedBuiltinSkill(name, res, 'skill-delete')) return;
const scope = parseSkillScope(url.searchParams.get('scope'), res, 'skill-delete');
if (scope === null) return;
const skillsRoot = resolveSkillsRoot(scope);
@@ -14533,6 +14679,8 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {
}
if (!validateSkillName(body.fromName, res, 'skill-move')) return;
if (!validateSkillName(body.toName, res, 'skill-move')) return;
+ if (rejectReservedBuiltinSkill(body.fromName, res, 'skill-move')) return;
+ if (rejectReservedBuiltinSkill(body.toName, res, 'skill-move')) return;
const skillsRoot = resolveSkillsRoot(body.scope);
// Tear down the live source skill doc (if open) BEFORE the git-mv
@@ -14836,7 +14984,14 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {
const scope = parseSkillScope(url.searchParams.get('scope'), res, 'skill-file-get');
if (scope === null) return;
const rel = url.searchParams.get('path') ?? '';
- const kind = classifySkillFilePath(rel);
+ // Built-in `open-knowledge` project skill: files come from the editor
+ // host dir, and its `SKILL.md` (skill-dir root) is allowed read-only here
+ // so the managed skill's entrypoint opens in the read-only viewer.
+ const builtin =
+ name === BUILTIN_PROJECT_SKILL_NAME && scope === 'project'
+ ? resolveBuiltinProjectSkillDir()
+ : null;
+ const kind = builtin && rel === 'SKILL.md' ? 'reference' : classifySkillFilePath(rel);
if (kind === null) {
errorResponse(
res,
@@ -14847,8 +15002,7 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {
);
return;
}
- const skillsRoot = resolveSkillsRoot(scope);
- const skillDir = resolve(skillsRoot, name);
+ const skillDir = builtin ? builtin.dir : resolve(resolveSkillsRoot(scope), name);
const abs = resolve(skillDir, rel);
if (abs !== skillDir && !abs.startsWith(`${skillDir}${sep}`)) {
errorResponse(
@@ -14937,6 +15091,7 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {
return;
}
if (!validateSkillName(body.name, res, 'skill-file-put')) return;
+ if (rejectReservedBuiltinSkill(body.name, res, 'skill-file-put')) return;
const kind = classifySkillFilePath(body.path);
if (kind === null) {
errorResponse(
@@ -15093,6 +15248,7 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {
const sp = url.searchParams;
const name = sp.get('name') ?? '';
if (!validateSkillName(name, res, 'skill-file-delete')) return;
+ if (rejectReservedBuiltinSkill(name, res, 'skill-file-delete')) return;
const scope = parseSkillScope(sp.get('scope'), res, 'skill-file-delete');
if (scope === null) return;
const rel = (sp.get('path') ?? '').replace(/\\/g, '/');
@@ -15203,6 +15359,7 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {
try {
const skillsRoot = resolveSkillsRoot(body.scope);
if (!validateSkillName(body.name, res, 'skill-install')) return;
+ if (rejectReservedBuiltinSkill(body.name, res, 'skill-install')) return;
// Project skills install into the project's host dirs (require a
// resolved project root); global skills install into the user-global
@@ -15339,6 +15496,7 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {
async (_req, res, body) => {
try {
if (!validateSkillName(body.name, res, 'skill-uninstall')) return;
+ if (rejectReservedBuiltinSkill(body.name, res, 'skill-uninstall')) return;
const base = skillInstallBase(body.scope);
if (!base) {
errorResponse(
@@ -15491,6 +15649,7 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {
return;
}
if (!validateSkillName(body.name, res, 'skill-restore')) return;
+ if (rejectReservedBuiltinSkill(body.name, res, 'skill-restore')) return;
// Global skills are unversioned — there's no prior version to restore.
if (body.scope === 'global') {
errorResponse(
@@ -15603,6 +15762,7 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {
return;
}
if (!validateSkillName(body.name, res, 'skill-update')) return;
+ if (rejectReservedBuiltinSkill(body.name, res, 'skill-update')) return;
// Only starter-pack skills have a bundled source to refresh from.
if (!isPackSkillName(body.name)) {
errorResponse(
diff --git a/packages/server/src/mcp/tools/skills.ts b/packages/server/src/mcp/tools/skills.ts
index 529322c5b..0c5ec40b0 100644
--- a/packages/server/src/mcp/tools/skills.ts
+++ b/packages/server/src/mcp/tools/skills.ts
@@ -10,7 +10,7 @@
* no raw `.ok/skills/...` paths). Read-only; mutation stays with the verb tools.
*/
import { z } from 'zod';
-import { BUNDLE_SKILL_NAME } from '../../skill-bundles.ts';
+import { INTERNAL_BUNDLE_SKILL_NAMES, isInternalBundleSkillName } from '../../skill-bundles.ts';
import {
type ConfigOrResolver,
HOCUSPOCUS_NOT_RUNNING_ERROR,
@@ -36,16 +36,6 @@ function bundleFileKind(path: string): 'reference' | 'script' {
return path.replace(/\\/g, '/').startsWith('scripts/') ? 'script' : 'reference';
}
-/**
- * OK's own shipped bundle skills (`open-knowledge`, `open-knowledge-discovery`,
- * `open-knowledge-write-skill`) are runtime agent skills projected into editor
- * host dirs — they have no `.ok/skills` source and can never be authored as
- * content skills (the reserved-name gate blocks it), so this tool can never
- * READ them. They are addressed by `BUNDLE_SKILL_NAME` here so the set tracks
- * the canonical bundle list.
- */
-const INTERNAL_BUNDLE_SKILL_NAMES = new Set<string>(Object.values(BUNDLE_SKILL_NAME));
-
/**
* Teaching error for a READ aimed at one of OK's built-in skills. Without it,
* an agent told to "load the open-knowledge skill" calls
@@ -194,9 +184,14 @@ export function register(server: ServerInstance, deps: SkillsToolDeps): void {
const rawSkills = Array.isArray((data as { skills?: unknown }).skills)
? ((data as { skills: unknown[] }).skills as Array<Record<string, unknown>>)
: [];
+ // Hide OK's own built-in `open-knowledge*` skills from the LIST: they now
+ // surface in `/api/skills` (managed, read-only) for the editor UI, but
+ // the agent already has them loaded (the READ short-circuit above teaches
+ // that), and LISTing them here would contradict it.
+ const authored = rawSkills.filter((s) => !isInternalBundleSkillName(String(s.name)));
// Project to the tool shape — deliberately DROP `path`/`absolutePath`
// so skills stay addressed by name+scope and `.ok/` is never surfaced.
- const skills = rawSkills.map((s) => ({
+ const skills = authored.map((s) => ({
name: s.name,
scope: s.scope,
...(typeof s.description === 'string' ? { description: s.description } : {}),
diff --git a/packages/server/src/skill-bundles.ts b/packages/server/src/skill-bundles.ts
index 5c7d4fd1a..dafef3ba4 100644
--- a/packages/server/src/skill-bundles.ts
+++ b/packages/server/src/skill-bundles.ts
@@ -29,6 +29,23 @@ export const BUNDLE_SKILL_NAME: Record<BundleId, string> = {
'write-skill': 'open-knowledge-write-skill',
};
+/**
+ * Every install-dir name OK's built-in bundles project into (`open-knowledge`,
+ * `open-knowledge-discovery`, `open-knowledge-write-skill`). These names are
+ * RESERVED: an authored content skill can't take one (the write API rejects it),
+ * the skills HTTP API refuses edit/rename/delete/install against them, and the
+ * MCP `skills` read tool hides them from its list + read. Derived from
+ * `BUNDLE_SKILL_NAME` so the reserved set can't drift from the shipped bundles.
+ */
+export const INTERNAL_BUNDLE_SKILL_NAMES: ReadonlySet<string> = new Set(
+ Object.values(BUNDLE_SKILL_NAME),
+);
+
+/** True when `name` is one of OK's built-in bundle skill names (`open-knowledge*`). */
+export function isInternalBundleSkillName(name: string): boolean {
+ return INTERNAL_BUNDLE_SKILL_NAMES.has(name);
+}
+
/** Canonical ordered bundle id list (= the keys of `BUNDLE_SKILL_NAME`). */
export const BUNDLE_IDS = Object.keys(BUNDLE_SKILL_NAME) as BundleId[];
diff --git a/packages/server/src/skill-reconcile.test.ts b/packages/server/src/skill-reconcile.test.ts
index 481c31932..d811d8e4a 100644
--- a/packages/server/src/skill-reconcile.test.ts
+++ b/packages/server/src/skill-reconcile.test.ts
@@ -340,4 +340,19 @@ describe('reconcileSkillInstalls', () => {
// Still a real dir (copy), not a symlink.
expect(lstatSync(bundle).isSymbolicLink()).toBe(false);
});
+
+ test('leaves EVERY shipped bundle copy untouched, not just open-knowledge', async () => {
+ // The exclusion set is derived from the canonical bundle list, so all three
+ // built-in bundle names are covered. A foreign `open-knowledge-write-skill/`
+ // host dir must NOT be adopted into `.ok/skills/` — that reserved name would
+ // become an authored skill the write API forbids.
+ const bundle = makeEditorCopy('.claude/skills', 'open-knowledge-write-skill', '# Shipped');
+
+ const r = await reconcileSkillInstalls({ projectDir: root, skillsRoot });
+ const all = [...r.adopted, ...r.replaced, ...r.collided, ...r.healed];
+ expect(all.find((a) => a.name === 'open-knowledge-write-skill')).toBeUndefined();
+ // Never projected into .ok/skills, and left as a real dir (not symlinked).
+ expect(existsSync(join(skillsRoot, 'open-knowledge-write-skill'))).toBe(false);
+ expect(lstatSync(bundle).isSymbolicLink()).toBe(false);
+ });
});
diff --git a/packages/server/src/skill-reconcile.ts b/packages/server/src/skill-reconcile.ts
index e6bc833a7..1ab992f35 100644
--- a/packages/server/src/skill-reconcile.ts
+++ b/packages/server/src/skill-reconcile.ts
@@ -67,13 +67,20 @@ import {
} from './fs-traced.ts';
import { readInstalledSkills, recordSkillInstall } from './installed-skills-marker.ts';
import { getLogger } from './logger.ts';
+import { INTERNAL_BUNDLE_SKILL_NAMES } from './skill-bundles.ts';
import { isProjectSkillManaged } from './skill-management.ts';
import { hostSkillsRootEscapes, validateSkillForInstall } from './skill-projection.ts';
const logger = getLogger('skill-reconcile');
-/** OK's shipped bundles — copy-installed, excluded from the reconcile invariant. */
-const SHIPPED_BUNDLE_NAMES = new Set(['open-knowledge', 'open-knowledge-discovery']);
+/**
+ * OK's shipped bundle skills — copy-installed, excluded from the reconcile
+ * sweep. Derived from the canonical bundle list (not a hand-maintained literal)
+ * so it can't drift: a foreign editor-host dir named after a built-in bundle
+ * must never be adopted into `.ok/skills/`, where the reserved name would
+ * become an authored skill the write API forbids.
+ */
+const SHIPPED_BUNDLE_NAMES = INTERNAL_BUNDLE_SKILL_NAMES;
/** Per-editor action recorded for one reconciled entry. */
interface ReconcileAction {