Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

fix(ok): stop in-place edits on other-checkout skills (PRD-7803) (#3213)

tim-inkeep0a893219bc66
diff --git a/packages/app/src/components/SkillPreviewTab.tsx b/packages/app/src/components/SkillPreviewTab.tsx
index 35606694f..903c47b71 100644
--- a/packages/app/src/components/SkillPreviewTab.tsx
+++ b/packages/app/src/components/SkillPreviewTab.tsx
@@ -31,7 +31,9 @@ import { discoverSkillsInSource, fetchSkillDetail } from '@/lib/skills-api';
interface Props {
/** `explore` = a skills.sh catalog entry; `detected` = a skill found in another
- * tool; `builtin` = one of OK's own shipped skills (read-only, nothing to import). */
+ * tool; `builtin` = one of OK's own shipped skills (read-only, nothing to import);
+ * `foreign` = a skill found in another tool but stored outside the open project,
+ * so the one action is a copy IN rather than an in-place edit. */
flavor: SkillPreviewFlavor;
/** skills.sh source identifier for Explore, or a local directory for Detected. */
source: string;
@@ -171,6 +173,10 @@ export function SkillPreviewTab({
: null;
const detected = flavor === 'detected';
const builtin = flavor === 'builtin';
+ // Lives outside the open project (parent checkout of a linked worktree, or any
+ // other tree): read-only here, and the action copies it IN rather than editing
+ // a file this project does not own.
+ const foreign = flavor === 'foreign';
const targetScope: SkillScope = level ?? 'project';
// Explore and plugin-copy previews install through the shared per-agent menu.
// Import is implied on the first destination choice, so opening/cancelling the
@@ -195,7 +201,8 @@ export function SkillPreviewTab({
// (which only tracks ITS own import-then-place cycle) never sees it.
const [bulkInstalledName, setBulkInstalledName] = useState<string | null>(null);
const landedName = previewInstall.importedName ?? bulkInstalledName;
- const importedNow = (flavor === 'explore' || pluginInfo !== null) && landedName !== null;
+ const importedNow =
+ (flavor === 'explore' || foreign || pluginInfo !== null) && landedName !== null;
useEffect(() => {
if (!importedNow || redirectedRef.current) return;
redirectedRef.current = true;
@@ -231,6 +238,14 @@ export function SkillPreviewTab({
<strong className="font-medium text-foreground">{pluginInfo.plugin}</strong> plugin
{pluginVersion} — read-only. {boldHarness} replaces plugin files on update.
</Trans>
+ ) : foreign ? (
+ // Names the CHECKOUT, not the scope: scope reads identically for a skill
+ // that works here and one that does not, so quoting it misleads.
+ <Trans>
+ {boldName} lives outside this project, at{' '}
+ <strong className="font-medium text-foreground">{source}</strong> — agents running here can't
+ load it. Copy it in to edit.
+ </Trans>
) : detected ? (
// No action: a detected skill is edited in place from the sidebar.
<Trans>
@@ -276,17 +291,29 @@ export function SkillPreviewTab({
<Button
size="sm"
disabled={previewInstall.toggles.installing}
- data-testid={pluginInfo ? 'skill-preview-edit-a-copy' : undefined}
+ data-testid={
+ pluginInfo
+ ? 'skill-preview-edit-a-copy'
+ : foreign
+ ? 'skill-preview-copy-in'
+ : undefined
+ }
>
{previewInstall.toggles.installing ? (
- pluginInfo ? (
+ pluginInfo || foreign ? (
<Trans>Copying</Trans>
) : (
<Trans>Installing</Trans>
)
) : (
<>
- {pluginInfo ? <Trans>Edit a copy</Trans> : <Trans>Install</Trans>}
+ {pluginInfo ? (
+ <Trans>Edit a copy</Trans>
+ ) : foreign ? (
+ <Trans>Copy in</Trans>
+ ) : (
+ <Trans>Install</Trans>
+ )}
<ChevronDown className="size-4 opacity-60" aria-hidden />
</>
)}
diff --git a/packages/app/src/components/SkillsSidebarSection.tsx b/packages/app/src/components/SkillsSidebarSection.tsx
index 8d5783aea..e2e742998 100644
--- a/packages/app/src/components/SkillsSidebarSection.tsx
+++ b/packages/app/src/components/SkillsSidebarSection.tsx
@@ -367,13 +367,20 @@ export function SkillsSidebarSection({ skillsMode = false }: { skillsMode?: bool
const source = skillDir(s.files.skillMd);
ensureDetectedFiles(s, source);
const rel = sub && sub !== SKILL_MD_PATH ? sub : undefined;
- // A Claude PLUGIN-CACHE resident is vendor-managed, versioned state — a
- // plugin update clobbers any edit, so the editable in-place buffer is a
- // trap there. Open the read-only detected preview instead (Adopt copies
- // it to a real location the user owns).
- if (s.provenance.plugin !== undefined) {
+ // Two ways the editable in-place buffer is a trap, both answered by the
+ // read-only preview whose one action is a copy the user owns:
+ // - a Claude PLUGIN-CACHE resident is vendor-managed, versioned state, so
+ // a plugin update clobbers any edit;
+ // - a skill OUTSIDE the open project is only listed because worktree
+ // enumeration resolves to the parent checkout, so an edit would land in
+ // a different checkout on a different branch.
+ // Provenance answers only the first. Locality is a separate axis and gets a
+ // separate flavor — a non-plugin skill must not be dressed up as a plugin.
+ const trapped =
+ s.provenance.plugin !== undefined ? 'detected' : s.outsideProject ? 'foreign' : null;
+ if (trapped !== null) {
openPreviewReplacing({
- flavor: 'detected',
+ flavor: trapped,
source,
name: s.name,
subtitle: s.sourceHarness ?? '',
diff --git a/packages/app/src/editor/editor-tabs.ts b/packages/app/src/editor/editor-tabs.ts
index 35fcd0420..fcb67407d 100644
--- a/packages/app/src/editor/editor-tabs.ts
+++ b/packages/app/src/editor/editor-tabs.ts
@@ -162,8 +162,8 @@ export function skillPreviewTabId(target: SkillPreviewHashTarget): string {
/**
* Find an already-open preview tab for the SAME LOCAL skill, keyed by
- * flavor + name + level and IGNORING the volatile `source` path. Both
- * local-path flavors move under you: a built-in's bundle path can differ
+ * flavor + name + level and IGNORING the volatile `source` path. Every
+ * local-path flavor moves under you: a built-in's bundle path can differ
* between skills-list refetches, and a detected skill's path carries the
* PLUGIN VERSION (`…/plugins/cache/<marketplace>/<plugin>/1.2.679/skills/<name>`)
* or moves when its installed copy is deleted and it is re-detected at its
@@ -180,7 +180,7 @@ export function skillPreviewTabId(target: SkillPreviewHashTarget): string {
*/
export function findLocalSkillPreviewTabId(
openTabs: readonly string[],
- flavor: Extract<SkillPreviewFlavor, 'builtin' | 'detected'>,
+ flavor: Extract<SkillPreviewFlavor, 'builtin' | 'detected' | 'foreign'>,
name: string,
scope: SkillScope,
): string | null {
diff --git a/packages/app/src/lib/doc-hash.ts b/packages/app/src/lib/doc-hash.ts
index 27f384e60..32c43ad8d 100644
--- a/packages/app/src/lib/doc-hash.ts
+++ b/packages/app/src/lib/doc-hash.ts
@@ -209,13 +209,14 @@ export function skillsFromHash(hash: string): boolean {
* skill, opened before it exists as a project doc — so its hash carries the
* import coordinates the preview + Manage need rather than a doc name. `flavor`
* selects the acquire path (`explore` = skills.sh `owner/repo`; `detected` = a
- * skill found in another tool, managed by name + harness). Each coordinate is
+ * skill found in another tool, managed by name + harness; `foreign` = the same
+ * but living outside the open project, where the one action is a copy IN). Each coordinate is
* one percent-encoded segment (source/subtitle may themselves contain `/`).
*/
const SKILL_PREVIEW_HASH_PREFIX = '#/__skill-preview__/';
/** The skill-preview surfaces, single-sourced. Add a flavor here and every
* hash/tab-id validator + target type picks it up. */
-const SKILL_PREVIEW_FLAVORS = ['explore', 'detected', 'builtin'] as const;
+const SKILL_PREVIEW_FLAVORS = ['explore', 'detected', 'builtin', 'foreign'] as const;
export type SkillPreviewFlavor = (typeof SKILL_PREVIEW_FLAVORS)[number];
/** Type-guard for an untrusted flavor (from a `window.location` hash or a
* persisted, hand-editable tab id). */
diff --git a/packages/app/src/locales/en/messages.json b/packages/app/src/locales/en/messages.json
index 1ac6fd9be..98f207c1a 100644
--- a/packages/app/src/locales/en/messages.json
+++ b/packages/app/src/locales/en/messages.json
@@ -2039,6 +2039,7 @@
"X8kjQX": ["Re-authenticate with GitHub"],
"X9VpsP": ["Loading folder contents"],
"XAyxsa": ["Check out remote branch"],
+ "XBgr2S": ["Copy in"],
"XDzAnp": ["Opens in a new tab"],
"XH30C4": ["document"],
"XIltnd": ["A skill named \"", ["trimmed"], "\" already exists here"],
@@ -3829,6 +3830,12 @@
"yg_6wQ": ["Search failed. Try again."],
"yh5-4s": ["Click to add and fill them in"],
"yhI6P0": ["Moved \"", ["0"], "\" to ", ["1"]],
+ "yhYv9j": [
+ ["boldName"],
+ " lives outside this project, at <0>",
+ ["source"],
+ "</0> — agents running here can't load it. Copy it in to edit."
+ ],
"yhdqox": [
"Installed — ok is available in external terminals. Unchecking removes it; OpenKnowledge's built-in terminal and AI tools keep working."
],
diff --git a/packages/app/src/locales/en/messages.po b/packages/app/src/locales/en/messages.po
index 802832df7..fd2c2ad7d 100644
--- a/packages/app/src/locales/en/messages.po
+++ b/packages/app/src/locales/en/messages.po
@@ -406,6 +406,10 @@ msgstr "{behind} behind origin"
msgid "{boldName} is part of the <0>{0}</0> plugin{pluginVersion} — read-only. {boldHarness} replaces plugin files on update."
msgstr "{boldName} is part of the <0>{0}</0> plugin{pluginVersion} — read-only. {boldHarness} replaces plugin files on update."
+#: src/components/SkillPreviewTab.tsx
+msgid "{boldName} lives outside this project, at <0>{source}</0> — agents running here can't load it. Copy it in to edit."
+msgstr "{boldName} lives outside this project, at <0>{source}</0> — agents running here can't load it. Copy it in to edit."
+
#: src/components/EditorFooter.tsx
msgid "{chars, plural, one {char} other {chars}}"
msgstr "{chars, plural, one {char} other {chars}}"
@@ -2763,6 +2767,10 @@ msgstr "Copy full path"
msgid "Copy full path, No workspace"
msgstr "Copy full path, No workspace"
+#: src/components/SkillPreviewTab.tsx
+msgid "Copy in"
+msgstr "Copy in"
+
#: src/components/AppMenubar.tsx
#: src/components/FileTargetMenuItems.tsx
msgid "Copy path"
diff --git a/packages/app/src/locales/pseudo/messages.json b/packages/app/src/locales/pseudo/messages.json
index d710eb134..ad61de440 100644
--- a/packages/app/src/locales/pseudo/messages.json
+++ b/packages/app/src/locales/pseudo/messages.json
@@ -2039,6 +2039,7 @@
"X8kjQX": ["Ŕē-àũţĥēńţĩćàţē ŵĩţĥ ĜĩţĤũƀ"],
"X9VpsP": ["Ĺōàďĩńĝ ƒōĺďēŕ ćōńţēńţś"],
"XAyxsa": ["Ćĥēćķ ōũţ ŕēḿōţē ƀŕàńćĥ"],
+ "XBgr2S": ["Ćōƥŷ ĩń"],
"XDzAnp": ["Ōƥēńś ĩń à ńēŵ ţàƀ"],
"XH30C4": ["ďōćũḿēńţ"],
"XIltnd": ["À śķĩĺĺ ńàḿēď \"", ["trimmed"], "\" àĺŕēàďŷ ēxĩśţś ĥēŕē"],
@@ -3829,6 +3830,12 @@
"yg_6wQ": ["Śēàŕćĥ ƒàĩĺēď. Ţŕŷ àĝàĩń."],
"yh5-4s": ["Ćĺĩćķ ţō àďď àńď ƒĩĺĺ ţĥēḿ ĩń"],
"yhI6P0": ["Ḿōvēď \"", ["0"], "\" ţō ", ["1"]],
+ "yhYv9j": [
+ ["boldName"],
+ " ĺĩvēś ōũţśĩďē ţĥĩś ƥŕōĴēćţ, àţ <0>",
+ ["source"],
+ "</0> — àĝēńţś ŕũńńĩńĝ ĥēŕē ćàń'ţ ĺōàď ĩţ. Ćōƥŷ ĩţ ĩń ţō ēďĩţ."
+ ],
"yhdqox": [
"Ĩńśţàĺĺēď — ōķ ĩś àvàĩĺàƀĺē ĩń ēxţēŕńàĺ ţēŕḿĩńàĺś. Ũńćĥēćķĩńĝ ŕēḿōvēś ĩţ; ŌƥēńĶńōŵĺēďĝē'ś ƀũĩĺţ-ĩń ţēŕḿĩńàĺ àńď ÀĨ ţōōĺś ķēēƥ ŵōŕķĩńĝ."
],
diff --git a/packages/app/src/locales/pseudo/messages.po b/packages/app/src/locales/pseudo/messages.po
index 00eb49d23..a5b192b19 100644
--- a/packages/app/src/locales/pseudo/messages.po
+++ b/packages/app/src/locales/pseudo/messages.po
@@ -406,6 +406,10 @@ msgstr ""
msgid "{boldName} is part of the <0>{0}</0> plugin{pluginVersion} — read-only. {boldHarness} replaces plugin files on update."
msgstr ""
+#: src/components/SkillPreviewTab.tsx
+msgid "{boldName} lives outside this project, at <0>{source}</0> — agents running here can't load it. Copy it in to edit."
+msgstr ""
+
#: src/components/EditorFooter.tsx
msgid "{chars, plural, one {char} other {chars}}"
msgstr ""
@@ -2759,6 +2763,10 @@ msgstr ""
msgid "Copy full path, No workspace"
msgstr ""
+#: src/components/SkillPreviewTab.tsx
+msgid "Copy in"
+msgstr ""
+
#: src/components/AppMenubar.tsx
#: src/components/FileTargetMenuItems.tsx
msgid "Copy path"
diff --git a/packages/app/tests/integration/skills-in-place-list.test.ts b/packages/app/tests/integration/skills-in-place-list.test.ts
index b6b651210..8d0189fc7 100644
--- a/packages/app/tests/integration/skills-in-place-list.test.ts
+++ b/packages/app/tests/integration/skills-in-place-list.test.ts
@@ -3,6 +3,7 @@ import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { afterEach, beforeEach, describe, expect, test } from 'vitest';
import { createTestServer, pollUntil, type TestServer } from './test-harness.ts';
+import { createLinkedWorktree } from './worktree-test-harness.ts';
/**
* In-place editor-dir skills surface as first-class `/api/skills`
@@ -1365,3 +1366,69 @@ describe('folder-level verbs via PUT /api/skill-targets (slice 2)', () => {
expect(res.status).toBe(400);
});
});
+
+/**
+ * The `outsideProject` stamp on `/api/skills/installed`. The pure predicate is
+ * unit-tested in `core/skills-catalog/scope.test.ts`; what only a booted server
+ * can pin is WHICH directory the handler measures against. Three candidates sit
+ * at that call site and two are wrong:
+ * - `identity` — resolves a linked worktree to its parent, which makes the
+ * comparison vacuous: the enumerated skills are always "inside" it;
+ * - `contentDir` — under `content.dir: docs` this is a SUBDIRECTORY of the
+ * project, so every project skill in the user's OWN checkout reads foreign.
+ * Only `projectDir ?? contentDir`, the open project root, is correct, and each
+ * test below fails on exactly one of the wrong two.
+ *
+ * Skills go under `.claude/skills` (an EDITOR project root). `.agents` is the
+ * vendor-neutral hub, deliberately not an editor id, so `projectHarnessHomes`
+ * does not scan it and a skill placed there is never enumerated at all.
+ */
+describe('outsideProject stamp on /api/skills/installed', () => {
+ let server: TestServer | undefined;
+ const trash: string[] = [];
+
+ type Installed = { skills: Array<{ name: string; outsideProject?: boolean }> };
+ const fetchInstalled = async (): Promise<Installed> => {
+ const res = await fetch(`http://127.0.0.1:${(server as TestServer).port}/api/skills/installed`);
+ expect(res.status).toBe(200);
+ return (await res.json()) as Installed;
+ };
+
+ afterEach(async () => {
+ await server?.cleanup();
+ server = undefined;
+ for (const d of trash.splice(0)) rmSync(d, { recursive: true, force: true });
+ });
+
+ test('does NOT flag a project skill in the user own checkout under content.dir', async () => {
+ // `content.dir: docs`. The skill sits at <projectRoot>/.claude/skills/x —
+ // inside the project the user has open, but OUTSIDE contentDir. Measuring
+ // against contentDir flags it; measuring against the project root does not.
+ const projectRoot = mkdtempSync(join(tmpdir(), 'ok-outside-proj-'));
+ trash.push(projectRoot);
+ const docsDir = join(projectRoot, 'docs');
+ mkdirSync(docsDir, { recursive: true });
+ writeSkill(projectRoot, '.claude/skills/homegrown', '# Homegrown');
+
+ server = await createTestServer({ contentDir: docsDir, projectDir: projectRoot });
+
+ const found = (await fetchInstalled()).skills.find((s) => s.name === 'homegrown');
+ expect(found).toBeDefined();
+ expect(found?.outsideProject).toBeUndefined();
+ });
+
+ test('flags a project skill that lives in the parent checkout of a linked worktree', async () => {
+ // The shape this feature exists for. A REAL linked worktree is required:
+ // `resolveProjectIdentity` only diverges from its input when `.git` is a
+ // pointer file, and that divergence is what surfaces the parent's skills here.
+ const wt = createLinkedWorktree({ prefix: 'ok-outside-wt', seedOkScaffold: true });
+ trash.push(wt.repoRoot, wt.worktreePath);
+ writeSkill(wt.repoRoot, '.claude/skills/fromparent', '# From the parent checkout');
+
+ server = await createTestServer({ contentDir: wt.worktreePath });
+
+ const found = (await fetchInstalled()).skills.find((s) => s.name === 'fromparent');
+ expect(found).toBeDefined();
+ expect(found?.outsideProject).toBe(true);
+ });
+});
diff --git a/packages/app/tests/integration/test-harness.ts b/packages/app/tests/integration/test-harness.ts
index 9d4bd5259..b2a1b6fc3 100644
--- a/packages/app/tests/integration/test-harness.ts
+++ b/packages/app/tests/integration/test-harness.ts
@@ -165,9 +165,11 @@ export interface CreateTestServerOptions {
*/
ephemeral?: boolean;
/**
- * Explicit projectDir for the split-directory (ephemeral) shape. Defaults to
- * a throwaway tmpdir the harness creates and removes. Only meaningful with
- * `ephemeral: true`.
+ * Explicit projectDir, distinct from `contentDir`. Two shapes need it: the
+ * ephemeral single-file mode (where it is a throwaway the harness creates and
+ * removes when not supplied), and the ordinary `content.dir: docs` layout,
+ * where `contentDir` is a SUBDIRECTORY of a real project root. Independent of
+ * `ephemeral` — a split directory pair does not imply "no project".
*/
projectDir?: string;
/**
@@ -239,9 +241,11 @@ export async function createTestServer(options: CreateTestServerOptions = {}): P
// throwaway projectDir distinct from contentDir (the user's real dir). The
// harness creates + removes it unless the caller supplies one.
const createdProjectDir = ephemeral && options.projectDir === undefined;
- const projectDir = ephemeral
- ? realpathSync(options.projectDir ?? mkdtempSync(join(tmpdir(), 'ok-ephemeral-test-')))
- : contentDir;
+ const projectDir = options.projectDir
+ ? realpathSync(options.projectDir)
+ : ephemeral
+ ? realpathSync(mkdtempSync(join(tmpdir(), 'ok-ephemeral-test-')))
+ : contentDir;
if (!ephemeral) {
// Ensure test-doc.md exists (persistence expects it for initial load).
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index 93bc7ff26..1f1d417e2 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -1673,6 +1673,7 @@ export {
export {
catalogRawScopeToOkScope,
isDetectedSkillInProject,
+ isSkillOutsideOpenProject,
} from './skills-catalog/scope.ts';
export {
parseSkillsShCatalogSource,
diff --git a/packages/core/src/skills-catalog/schema.ts b/packages/core/src/skills-catalog/schema.ts
index abd4aec26..e74584c15 100644
--- a/packages/core/src/skills-catalog/schema.ts
+++ b/packages/core/src/skills-catalog/schema.ts
@@ -82,6 +82,14 @@ export const CatalogSkillSchema = z.looseObject({
home: z.string(),
provenance: SkillProvenanceSchema,
inert: SkillInertSchema,
+ /**
+ * True when `home` sits outside the OPEN project. Enumeration resolves a
+ * linked worktree to its parent checkout, so a parent's skills are listed
+ * here even though no file of theirs exists in the open tree. Only the server
+ * can decide this — it alone holds `contentDir` beside the resolved identity
+ * — so it is stamped there rather than derived by a client.
+ */
+ outsideProject: z.boolean().optional(),
});
export type CatalogSkill = z.infer<typeof CatalogSkillSchema>;
diff --git a/packages/core/src/skills-catalog/scope.test.ts b/packages/core/src/skills-catalog/scope.test.ts
index d02778116..9e5f4df9c 100644
--- a/packages/core/src/skills-catalog/scope.test.ts
+++ b/packages/core/src/skills-catalog/scope.test.ts
@@ -1,6 +1,10 @@
import { describe, expect, it } from 'vitest';
import type { SkillProvenance } from './schema.ts';
-import { catalogRawScopeToOkScope, isDetectedSkillInProject } from './scope.ts';
+import {
+ catalogRawScopeToOkScope,
+ isDetectedSkillInProject,
+ isSkillOutsideOpenProject,
+} from './scope.ts';
describe('catalogRawScopeToOkScope', () => {
it('maps Claude project-bound scopes to project', () => {
@@ -68,3 +72,75 @@ describe('isDetectedSkillInProject', () => {
).toBe(false);
});
});
+
+describe('isSkillOutsideOpenProject', () => {
+ const prov = (p: Partial<SkillProvenance>): SkillProvenance => p;
+ // The worktree shape: the OPEN tree is the linked worktree, while enumeration
+ // resolved identity to the parent checkout that actually holds the files.
+ const WORKTREE = '/Users/me/inkeep/wt-blog';
+ const PARENT = '/Users/me/inkeep/agents-private';
+
+ it('flags a project skill whose files live in another checkout', () => {
+ expect(
+ isSkillOutsideOpenProject(
+ prov({ scope: 'project', projectPath: PARENT }),
+ `${PARENT}/.codex/skills/stories`,
+ WORKTREE,
+ ),
+ ).toBe(true);
+ });
+
+ it('clears a project skill inside the open tree', () => {
+ expect(
+ isSkillOutsideOpenProject(
+ prov({ scope: 'project', projectPath: WORKTREE }),
+ `${WORKTREE}/.agents/skills/consolidate-notes`,
+ WORKTREE,
+ ),
+ ).toBe(false);
+ });
+
+ // The regression this guards: a global skill sits outside contentDir BY
+ // DEFINITION, so a locality-only test would condemn every global row and
+ // send working skills down the read-only copy-in path.
+ it('never flags a global skill, however far outside it sits', () => {
+ for (const scope of ['user', 'something-else', undefined]) {
+ expect(
+ isSkillOutsideOpenProject(prov({ scope }), '/Users/me/.claude/skills/x', WORKTREE),
+ ).toBe(false);
+ }
+ });
+
+ it('flags a sibling that merely shares a path prefix, and clears a trailing slash', () => {
+ expect(
+ isSkillOutsideOpenProject(
+ prov({ scope: 'project' }),
+ `${WORKTREE}-other/.codex/skills/x`,
+ WORKTREE,
+ ),
+ ).toBe(true);
+ expect(
+ isSkillOutsideOpenProject(
+ prov({ scope: 'project' }),
+ `${WORKTREE}/.codex/skills/x`,
+ `${WORKTREE}/`,
+ ),
+ ).toBe(false);
+ });
+
+ it('clears a skill nested deeper inside the open tree', () => {
+ expect(
+ isSkillOutsideOpenProject(
+ prov({ scope: 'project' }),
+ `${WORKTREE}/subdir/.codex/skills/x`,
+ WORKTREE,
+ ),
+ ).toBe(false);
+ });
+
+ it('is inert when the open tree is unknown', () => {
+ expect(
+ isSkillOutsideOpenProject(prov({ scope: 'project' }), '/anywhere/skills/x', undefined),
+ ).toBe(false);
+ });
+});
diff --git a/packages/core/src/skills-catalog/scope.ts b/packages/core/src/skills-catalog/scope.ts
index 6272945ac..f8af1026e 100644
--- a/packages/core/src/skills-catalog/scope.ts
+++ b/packages/core/src/skills-catalog/scope.ts
@@ -13,6 +13,9 @@
* - `isDetectedSkillInProject` decides whether a detected skill belongs to the
* open project at all — the server drops the ones that don't before the
* client ever buckets them.
+ * - `isSkillOutsideOpenProject` decides whether a skill that DOES belong is
+ * nonetheless stored outside the open tree, where editing it in place would
+ * write to a different checkout.
*
* Pure + browser-safe (no `node:*`) so both the client sidebar and the server
* endpoint share one source of truth.
@@ -64,3 +67,38 @@ export function isDetectedSkillInProject(
if (owner === undefined || projectDir === undefined) return true;
return samePath(owner, projectDir);
}
+
+/**
+ * Does this skill belong to the open project but live OUTSIDE its tree?
+ *
+ * Enumeration resolves a linked worktree to its parent checkout so the parent's
+ * project-scoped installs still match (see `isDetectedSkillInProject`). The
+ * cost is that a skill can pass that test while none of its files exist in the
+ * tree the user has open — editing it in place then writes to a different
+ * checkout, on a different branch. `contentDir` is the OPEN tree, never the
+ * resolved identity; passing the identity makes this vacuously false.
+ *
+ * PROJECT-bound only. A global skill sits at `~/.claude/skills/…`, outside
+ * `contentDir` by definition, and loads from every project — testing locality
+ * alone would condemn every global row.
+ *
+ * ponytail: string prefix, matching `samePath` above — both operands are
+ * already-absolute dirs. Realpath both at the server boundary if a symlinked
+ * project root ever needs to match.
+ *
+ * The `h !== c` conjunct is unreachable for today's callers (a skill `home` is
+ * always a directory NESTED under a harness root, never the project root
+ * itself) but is kept so the predicate answers "outside" correctly for any
+ * input rather than only for well-formed ones.
+ */
+export function isSkillOutsideOpenProject(
+ provenance: SkillProvenance,
+ home: string,
+ contentDir: string | undefined,
+): boolean {
+ if (contentDir === undefined) return false;
+ if (catalogRawScopeToOkScope(provenance.scope) !== 'project') return false;
+ const h = home.replace(/\/+$/, '');
+ const c = contentDir.replace(/\/+$/, '');
+ return h !== c && !h.startsWith(`${c}/`);
+}
diff --git a/packages/server/src/api-extension.ts b/packages/server/src/api-extension.ts
index 64af002bb..9348988a4 100644
--- a/packages/server/src/api-extension.ts
+++ b/packages/server/src/api-extension.ts
@@ -106,6 +106,7 @@ import {
isManagedArtifactDocName,
isOpenKnowledgeSkillsSource,
isSkillInstallTarget,
+ isSkillOutsideOpenProject,
LEGACY_SKILL_STORE_ROOT,
LINKABLE_ASSET_EXTENSIONS,
type LifecycleStatus,
@@ -7135,13 +7136,31 @@ export function createApiExtension(
const globalInPlaceNames = new Set(scanGlobalInPlaceSkills(skillsHome).map((s) => s.name));
const result = {
...catalog,
- skills: catalog.skills.filter(
- (s) =>
- isDetectedSkillInProject(s.provenance, identity) &&
- !(s.provenance.scope === 'project'
- ? inPlaceNames.has(s.name)
- : globalInPlaceNames.has(s.name)),
- ),
+ skills: catalog.skills
+ .filter(
+ (s) =>
+ isDetectedSkillInProject(s.provenance, identity) &&
+ !(s.provenance.scope === 'project'
+ ? inPlaceNames.has(s.name)
+ : globalInPlaceNames.has(s.name)),
+ )
+ // `identity` is the PARENT checkout for a linked worktree, so a skill
+ // can match the project while living in a tree the user does not have
+ // open. Stamp that so the client can refuse an in-place edit that would
+ // land in another checkout on another branch.
+ //
+ // The reference is the OPEN PROJECT ROOT — `projectDir ?? contentDir`,
+ // the same expression `identity` is derived from but WITHOUT the
+ // worktree→parent resolution. Not `identity` (that resolution makes the
+ // test vacuously false), and not `contentDir`: under `content.dir: docs`
+ // contentDir is `<projectDir>/docs` while harness skill dirs sit at
+ // `<projectDir>/.codex/skills/…`, so every project skill in the user's
+ // OWN checkout would be flagged foreign.
+ .map((s) =>
+ isSkillOutsideOpenProject(s.provenance, s.home, projectDir ?? contentDir)
+ ? { ...s, outsideProject: true }
+ : s,
+ ),
};
successResponse(res, 200, SkillsInstalledSuccessSchema, result, {
handler: 'skills-installed',