Skip to content

Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.

feat(accounts): per-account option to share ~/.claude/skills

enes949e869044e6
diff --git a/CLAUDE.md b/CLAUDE.md
index 7bbde2e50..811c53a9b 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -2192,6 +2192,64 @@ else, and its context links must keep classifying across restarts).
both shells call — the desktop passing the canvas skill as its `extra`. A second copy is the
drift this file warns about elsewhere: the Server Edition shipped without the per-account leg
entirely, so a managed account there reported no agent status at all.
+ - **Shared system skills (`shareSystemSkills`, issue #643, OFF by default)** — Claude Code resolves
+ user skills as `join(CLAUDE_CONFIG_DIR ?? ~/.claude, 'skills')` (MEASURED, 2.1.266), so an
+ account dir **replaces** `~/.claude/skills` rather than adding to it and a fresh managed account
+ shows only the skills nodeterm installed (that was #438). The isolation is correct and often the
+ point; this per-account switch (Settings → Accounts) is the way back in.
+ **Each system skill is linked INDIVIDUALLY** (`<accountDir>/skills/<name>` →
+ `~/.claude/skills/<name>`), never the whole `skills` directory, and that choice is what makes
+ everything else safe: `installCanvasSkillInto` writes *into* `<configDir>/skills/`, so a
+ directory-level link would put nodeterm's canvas skill in the user's SYSTEM skills folder, and
+ "turn it off" would have to restore a directory it had first moved aside. Per-skill links keep
+ the account's `skills/` a real directory and make the off-switch a link removal.
+ MEASURED with strace: Claude Code opens a symlinked entry inside `skills/` as a directory and
+ reads its `SKILL.md` exactly like a real sibling — per-skill links are equivalent to the
+ whole-directory link for discovery, not a compromise.
+ - **Ownership is name-anchored**: an entry is ours iff it is a symlink whose target normalizes
+ to exactly `join(systemSkillsDir, <that entry's own name>)`. What ON creates is precisely what
+ OFF removes; a real directory is never ours, whatever its name — so "never delete through the
+ link" is a property of the plan (`core/claude-skill-share-core.ts`, pure + mutation-tested),
+ not a promise about the applier. Removal is `unlink` then `rmdir` (a Windows junction refuses
+ `unlink`); both fail on a real non-empty directory, which is the second line of defence.
+ - **`NODETERM_OWNED_SKILLS` (`manage-nodeterm-canvas`, `get-linked-context`) is never linked and
+ never pruned.** Their presence in an account dir is decided by nodeterm's own installers; if
+ sharing linked them, the off-switch would delete a skill the canvas-control installer had put
+ there and the two owners would fight over the name at every launch.
+ - **The realpath refusal is load-bearing.** The issue's manual workaround
+ (`mv skills skills.bak && ln -s ~/.claude/skills skills`) makes the account's `skills/`
+ RESOLVE to the system one; linking into it would plant links in the user's own folder and let
+ the off-switch delete them from there. The planner compares REAL paths and refuses
+ (`same-directory`), which also covers a linked account whose `configDir` was hand-edited to
+ `~/.claude`.
+ - **Windows uses a directory JUNCTION** (`fs.symlink(target, path, 'junction')`), not the `'dir'`
+ symlink `worktree-shared-paths.ts` must use: a junction needs neither Developer Mode nor
+ elevation, and every target here is an absolute directory — the two conditions it has. On
+ POSIX Node ignores the type. So the feature is available on every desktop platform rather than
+ gated off one.
+ - **The launch sweep re-links but NEVER removes** (`installHooksIntoLocalAccounts`). ON has real
+ work at boot (a skill added to `~/.claude/skills` since the last run; a stale link to prune);
+ OFF is a removal, and ownership here is inferred from a link's SHAPE, which cannot tell our
+ link from an identical hand-made one — and a LINKED account's dir is the user's own
+ `~/.claude-2`, where exactly that is a normal thing to find. Removal therefore happens only
+ through `claude-accounts:set-skill-sharing`, where the intent is explicit. The cost: a
+ settings.json hand-edited to `false` while the app was closed keeps its links until the switch
+ is flipped.
+ - **The switch flips the filesystem FIRST and persists the flag only if that returned** — the
+ flag is what the sweep replays, so a stored `true` whose links were never made would make the
+ switch lie until the next boot. A refusal stores nothing.
+ - **The copy says the edits flow both ways**, because a link is not a copy: editing a shared
+ skill from inside the account edits the machine's own file. A user who reads "share" as "copy"
+ finds that out by losing work. Result sentences are the pure `renderer/lib/skillSharing.ts`.
+ - **Surfaces.** Desktop: full. **Server Edition: full** — the whole implementation is core, so
+ the ws-bridge leg is a real passthrough and the machine the browser is served from is exactly
+ the machine whose `~/.claude/skills` is shared (the canvas skill is not installed there, but
+ its name stays reserved: a reserved name that is never created is inert). **SSH accounts:
+ explicitly out of scope for v1** — their config dir is on the host, so the option would have to
+ link that host's skills over the ControlMaster, with its own generated-shell proof obligation.
+ The switch is DISABLED with that reason (never hidden), and core refuses (`remote-account`) as
+ the backstop for a hand-edited settings.json. **Mobile: N/A** — the phone never mints an
+ account and carries no skills concept.
- **Account-aware readers** — transcript resolution is scoped per account (`transcriptRootFor`
picks the account dir's `projects/`, composite cache key includes `accountId`); the same
threading runs through the session-name poll, restart handoff, and `ChatPanel` (the ⌘M
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 65aef4472..ef06cde55 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -209,6 +209,20 @@ Put the rule in one predicate under `src/shared` and have every mint site ask it
things that follow from it (a node's color, say) from that same call rather than re-deriving the
condition per caller.
+**A feature that creates links owes an ownership rule, and it must be a property of the plan.**
+"Share `~/.claude/skills` with this account" (issue #643) links each system skill into a managed
+account's own `skills/` and removes those links again when switched off — one wrong removal deletes
+somebody's real skills folder. Three habits made it safe and they generalize: link the LEAVES, not
+the containing directory (nodeterm writes its own canvas skill into `<configDir>/skills/`, so a
+directory-level link would have written it into the user's system folder); decide ownership by an
+anchored SHAPE (a symlink at `<name>` pointing at `<system>/<name>`) so what the on-switch creates
+is exactly what the off-switch removes, and a real directory can never qualify; and compare
+REALPATHS before acting, because the hand-made version of the same feature makes the two directories
+one and linking into it would plant links in the folder you are about to clean up. Verify the
+removal against a real filesystem with real symlinks and real content — a mocked `fs` agrees with
+whatever the code believed. And a launch-time sweep may re-create, never delete: ownership inferred
+from shape cannot tell your link from an identical one the user made by hand.
+
**Do not take scrolling away from tmux.** It owns the mouse, the scrollback and the alternate
screen. A previous design moved that into the emulator and failed structurally; `CLAUDE.md` explains
why in detail.
diff --git a/src/core/claude-accounts-service.test.ts b/src/core/claude-accounts-service.test.ts
index e8b668b7b..8dba3f6a4 100644
--- a/src/core/claude-accounts-service.test.ts
+++ b/src/core/claude-accounts-service.test.ts
@@ -38,6 +38,19 @@ vi.mock('./agents/hooks/claude', () => ({
}
}))
+// Same reason as the hook writers above, with one addition: the real applier resolves the SYSTEM
+// skills dir from `os.homedir()`, so an unmocked sweep in this suite would read the developer's own
+// `~/.claude/skills`. Its behaviour is covered against a real filesystem in
+// `claude-skill-share.test.ts`; here we only assert the WIRING (issue #643).
+const shared: { dir: string; enabled: boolean }[] = []
+vi.mock('./claude-skill-share', () => ({
+ EMPTY_SKILL_SHARE: { linked: 0, unlinked: 0, shared: 0, occupied: 0, failed: 0 },
+ applySkillShare: async (dir: string, enabled: boolean) => {
+ shared.push({ dir, enabled })
+ return { linked: enabled ? 2 : 0, unlinked: 0, shared: enabled ? 2 : 0, occupied: 0, failed: 0 }
+ }
+}))
+
let fake: FakePlatform
let userDataDir: string
@@ -47,6 +60,7 @@ const call = (channel: string, ...args: unknown[]): Promise<any> =>
beforeEach(() => {
installed.length = 0
tui.length = 0
+ shared.length = 0
userDataDir = mkdtempSync(path.join(os.tmpdir(), 'nt-accounts-'))
fake = fakePlatform({ userDataDir })
initPlatform(fake)
@@ -57,8 +71,8 @@ afterEach(() => {
rmSync(userDataDir, { recursive: true, force: true })
})
-describe('registerClaudeAccountsIpc — the five channels', () => {
- it('registers exactly the five claude-accounts channels', () => {
+describe('registerClaudeAccountsIpc — the six channels', () => {
+ it('registers exactly the six claude-accounts channels', () => {
registerClaudeAccountsIpc()
expect(Object.keys(fake.handlers).sort()).toEqual(
[
@@ -66,6 +80,7 @@ describe('registerClaudeAccountsIpc — the five channels', () => {
IPC.claudeAccountsCancelWait,
IPC.claudeAccountsLink,
IPC.claudeAccountsRemove,
+ IPC.claudeAccountsSetSkillSharing,
IPC.claudeAccountsWaitLogin
].sort()
)
@@ -186,6 +201,47 @@ describe('installHooksIntoLocalAccounts', () => {
expect(warn).toHaveBeenCalled()
warn.mockRestore()
})
+
+ // Issue #643. The launch sweep re-links (a skill added to ~/.claude/skills since the last run)
+ // and NEVER removes: ownership is inferred from a link's shape, so an OFF pass here could delete
+ // an identical link the user made by hand in their own linked-account dir. Removal happens only
+ // where the user asked for it, in `setSkillSharing`.
+ it('re-links shared skills for local accounts that opted in, and touches no other account', () => {
+ installHooksIntoLocalAccounts([
+ { id: 'aaa', shareSystemSkills: true },
+ { id: 'bbb', host: 'user@example', shareSystemSkills: true },
+ { id: 'ccc' },
+ { id: 'ddd', shareSystemSkills: false }
+ ])
+ expect(shared).toEqual([{ dir: accountConfigDir(userDataDir, 'aaa'), enabled: true }])
+ })
+})
+
+describe('claudeAccounts.setSkillSharing', () => {
+ it('reconciles the account dir and reports what happened', async () => {
+ registerClaudeAccountsIpc()
+ const res = await call(IPC.claudeAccountsSetSkillSharing, 'aaa', true)
+ expect(shared).toEqual([{ dir: accountConfigDir(userDataDir, 'aaa'), enabled: true }])
+ expect(res).toMatchObject({ linked: 2, shared: 2 })
+ })
+
+ // A remote account's config dir is on its HOST; reconciling the local one would link this
+ // machine's skills into a directory the session never reads. v1 refuses instead of guessing.
+ it('refuses a remote (SSH) account and touches no filesystem', async () => {
+ registerClaudeAccountsSource(() => [
+ { id: 'aaa', label: 'r', host: 'user@example', createdAt: 0 } as ClaudeAccount
+ ])
+ registerClaudeAccountsIpc()
+ const res = await call(IPC.claudeAccountsSetSkillSharing, 'aaa', true)
+ expect(res.refused).toBe('remote-account')
+ expect(shared).toEqual([])
+ })
+
+ it('refuses an id that could traverse out of the accounts root', async () => {
+ registerClaudeAccountsIpc()
+ await expect(call(IPC.claudeAccountsSetSkillSharing, '../evil', true)).rejects.toThrow()
+ expect(shared).toEqual([])
+ })
})
// ---- Linked accounts (adopting a config dir the user already drives) -------------------------
diff --git a/src/core/claude-accounts-service.ts b/src/core/claude-accounts-service.ts
index 3c2b6ad65..aaf41a1ed 100644
--- a/src/core/claude-accounts-service.ts
+++ b/src/core/claude-accounts-service.ts
@@ -25,6 +25,7 @@ import {
claudeConfigDirFor,
linkedClaudeConfigDirFor
} from './claude-config-dir'
+import { applySkillShare, EMPTY_SKILL_SHARE } from './claude-skill-share'
import { installClaudeHooksInto, ensureClaudeFullscreenTuiInto } from './agents/hooks/claude'
import { findInLoginPath } from './pty-manager'
import { platform } from './platform'
@@ -251,6 +252,27 @@ export function registerClaudeAccountsIpc(deps: ClaudeAccountsDeps = {}): void {
void ensureClaudeFullscreenTuiInto(configDir)
return { id: randomUUID(), configDir, email }
})
+
+ /**
+ * Turn `~/.claude/skills` sharing on/off for one LOCAL account and reconcile now (issue #643).
+ * The renderer owns the settings flag; this is only the effect.
+ *
+ * **Local accounts only, by construction.** A REMOTE account's config dir lives on its host, so
+ * this would have to link that host's `~/.claude/skills` over the ControlMaster — a generated
+ * shell with its own "never delete through the link" proof obligation, and a separate change.
+ * Rather than silently reconciling the wrong machine's filesystem, an account with a `host`
+ * REFUSES here (the Settings switch is disabled with the reason, so this is the backstop for a
+ * hand-edited settings.json, not the message anyone normally sees).
+ */
+ platform().handle(IPC.claudeAccountsSetSkillSharing, async (id: string, enabled: boolean) => {
+ const remoteAccount = claudeAccountsSnapshot().some((a) => a.id === id && a.host)
+ if (remoteAccount) return { ...EMPTY_SKILL_SHARE, refused: 'remote-account' as const }
+ // `claudeConfigDirFor` validates the id alphabet AND resolves a LINKED account to the user's
+ // own dir — which is the right target: a linked account is an identity like any other, and its
+ // `skills/` is subject to the same isolation. The plan's realpath refusal is what keeps a
+ // hand-edited `configDir` of `~/.claude` from turning this into a self-link.
+ return applySkillShare(claudeConfigDirFor(id), enabled)
+ })
}
/**
@@ -267,7 +289,7 @@ export function registerClaudeAccountsIpc(deps: ClaudeAccountsDeps = {}): void {
* this, or the resolver would hand back a managed dir that does not exist for those rows.
*/
export function installHooksIntoLocalAccounts(
- accounts: readonly { id: string; host?: string }[],
+ accounts: readonly { id: string; host?: string; shareSystemSkills?: boolean }[],
extra?: (configDir: string) => void
): void {
for (const acct of accounts) {
@@ -276,6 +298,19 @@ export function installHooksIntoLocalAccounts(
const configDir = claudeConfigDirFor(acct.id)
installClaudeHooksInto(configDir)
extra?.(configDir)
+ // Shared-skills reconcile (issue #643) — the ON direction ONLY, and that asymmetry is the
+ // safety property. ON has real work to do at every boot: a skill the user added to
+ // `~/.claude/skills` since the last run needs a new link, and one they deleted leaves a
+ // broken entry Claude Code would still try to read. OFF is a REMOVAL, and a launch sweep is
+ // the wrong place to perform one: ownership here is inferred from a link's shape (a link at
+ // `<name>` pointing at `<system>/<name>`), which cannot tell OUR link from an identical one
+ // the user made by hand — and a LINKED account's dir is the user's own `~/.claude-2`, where
+ // exactly that hand-made link is a normal thing to find. So the off-switch removes links
+ // only where intent is explicit (`claude-accounts:set-skill-sharing`). The cost is that a
+ // settings.json edited to `false` while the app was closed leaves its links until the switch
+ // is flipped — links, not data, and visible in the account's own folder.
+ // AFTER `extra`, so the canvas skill's own directory exists before anything looks at it.
+ if (acct.shareSystemSkills) void applySkillShare(configDir, true)
// Off the critical path: it awaits the memoized CLI probe, then writes fail-open. (The
// system ~/.claude is handled by installManagedAgentHooks, which covers both shells.)
void ensureClaudeFullscreenTuiInto(configDir)
diff --git a/src/core/claude-skill-share-core.test.ts b/src/core/claude-skill-share-core.test.ts
new file mode 100644
index 000000000..8f3aed838
--- /dev/null
+++ b/src/core/claude-skill-share-core.test.ts
@@ -0,0 +1,199 @@
+import { describe, expect, it } from 'vitest'
+import {
+ NODETERM_OWNED_SKILLS,
+ normalizeLinkPath,
+ planSkillShare,
+ type SkillDirEntry
+} from './claude-skill-share-core'
+
+const SYS = '/home/u/.claude/skills'
+const ACC = '/home/u/.config/nodeterm/claude-accounts/a1/skills'
+
+/** A system skill directory. */
+const sys = (name: string): SkillDirEntry => ({ name, kind: 'dir' })
+/** A link in the account dir that WE created (name-anchored at the system dir). */
+const ours = (name: string, root = SYS): SkillDirEntry => ({
+ name,
+ kind: 'link',
+ linkTarget: `${root}/${name}`
+})
+
+const plan = (over: Partial<Parameters<typeof planSkillShare>[0]> = {}) =>
+ planSkillShare({
+ enabled: true,
+ systemSkillsDir: SYS,
+ accountSkillsDir: ACC,
+ system: [],
+ account: [],
+ win: false,
+ ...over
+ })
+
+describe('normalizeLinkPath', () => {
+ it('strips the Windows \\\\?\\ device prefix a junction readlink returns', () => {
+ expect(normalizeLinkPath('\\\\?\\C:\\Users\\u\\.claude\\skills\\foo', true)).toBe(
+ 'c:\\users\\u\\.claude\\skills\\foo'
+ )
+ })
+
+ it('strips a trailing separator (junctions come back with one)', () => {
+ expect(normalizeLinkPath('C:\\Users\\u\\skills\\foo\\', true)).toBe('c:\\users\\u\\skills\\foo')
+ expect(normalizeLinkPath('/home/u/skills/foo/', false)).toBe('/home/u/skills/foo')
+ })
+
+ it('never trims a root away', () => {
+ expect(normalizeLinkPath('/', false)).toBe('/')
+ expect(normalizeLinkPath('C:\\', true)).toBe('c:\\')
+ })
+
+ it('case-folds only on Windows', () => {
+ expect(normalizeLinkPath('/home/U/Skills', false)).toBe('/home/U/Skills')
+ expect(normalizeLinkPath('C:\\Skills', true)).toBe('c:\\skills')
+ })
+
+ it('is empty for a missing value (a non-link entry has no target)', () => {
+ expect(normalizeLinkPath(undefined, false)).toBe('')
+ })
+})
+
+describe('planSkillShare — enabled', () => {
+ it('links every system skill the account does not have', () => {
+ const p = plan({ system: [sys('a'), sys('b')] })
+ expect(p.link).toEqual([
+ { name: 'a', target: `${SYS}/a` },
+ { name: 'b', target: `${SYS}/b` }
+ ])
+ expect(p.unlink).toEqual([])
+ })
+
+ it('never links a name nodeterm owns — the canvas skill stays a real local directory', () => {
+ const p = plan({ system: [sys('manage-nodeterm-canvas'), sys('get-linked-context'), sys('a')] })
+ expect(p.link.map((l) => l.name)).toEqual(['a'])
+ expect(p.skipped).toEqual([
+ { name: 'manage-nodeterm-canvas', reason: 'reserved' },
+ { name: 'get-linked-context', reason: 'reserved' }
+ ])
+ expect(NODETERM_OWNED_SKILLS).toContain('manage-nodeterm-canvas')
+ })
+
+ it('skips a system entry that is not a directory (manifest.json, README)', () => {
+ const p = plan({ system: [{ name: 'manifest.json', kind: 'other' }, sys('a')] })
+ expect(p.link.map((l) => l.name)).toEqual(['a'])
+ expect(p.skipped).toEqual([{ name: 'manifest.json', reason: 'not-a-directory' }])
+ })
+
+ it("never overwrites the account's OWN skill of the same name", () => {
+ const p = plan({ system: [sys('a')], account: [{ name: 'a', kind: 'dir' }] })
+ expect(p.link).toEqual([])
+ expect(p.unlink).toEqual([])
+ expect(p.skipped).toEqual([{ name: 'a', reason: 'occupied' }])
+ })
+
+ it("leaves a user's own link alone when it points somewhere else", () => {
+ const p = plan({
+ system: [sys('a')],
+ account: [{ name: 'a', kind: 'link', linkTarget: '/opt/skills/a' }]
+ })
+ expect(p.link).toEqual([])
+ expect(p.unlink).toEqual([])
+ expect(p.skipped).toEqual([{ name: 'a', reason: 'occupied' }])
+ })
+
+ it('is idempotent: an already-correct link is neither relinked nor removed', () => {
+ const p = plan({ system: [sys('a')], account: [ours('a')] })
+ expect(p.link).toEqual([])
+ expect(p.unlink).toEqual([])
+ expect(p.alreadyLinked).toEqual(['a'])
+ })
+
+ it('prunes a link of ours whose system skill is gone', () => {
+ const p = plan({ system: [sys('a')], account: [ours('a'), ours('gone')] })
+ expect(p.unlink).toEqual(['gone'])
+ expect(p.link).toEqual([])
+ })
+
+ it('prunes a link of ours whose name has since become nodeterm-owned', () => {
+ const p = plan({
+ system: [sys('manage-nodeterm-canvas')],
+ account: [ours('manage-nodeterm-canvas')]
+ })
+ expect(p.unlink).toEqual(['manage-nodeterm-canvas'])
+ })
+
+ it('does not prune a real directory, whatever its name', () => {
+ const p = plan({ system: [], account: [{ name: 'mine', kind: 'dir' }] })
+ expect(p.unlink).toEqual([])
+ })
+
+ it('matches a Windows junction target through the \\\\?\\ prefix and case', () => {
+ const p = planSkillShare({
+ enabled: true,
+ systemSkillsDir: 'C:\\Users\\u\\.claude\\skills',
+ accountSkillsDir: 'C:\\Users\\u\\AppData\\Roaming\\nodeterm\\claude-accounts\\a1\\skills',
+ system: [sys('a')],
+ account: [{ name: 'a', kind: 'link', linkTarget: '\\\\?\\C:\\Users\\U\\.claude\\skills\\a\\' }],
+ win: true
+ })
+ expect(p.link).toEqual([])
+ expect(p.alreadyLinked).toEqual(['a'])
+ })
+})
+
+describe('planSkillShare — disabled', () => {
+ it('removes exactly the links it would have created, and nothing else', () => {
+ const p = plan({
+ enabled: false,
+ system: [sys('a')],
+ account: [
+ ours('a'),
+ ours('b'),
+ { name: 'mine', kind: 'dir' },
+ { name: 'elsewhere', kind: 'link', linkTarget: '/opt/skills/elsewhere' },
+ { name: 'manage-nodeterm-canvas', kind: 'dir' }
+ ]
+ })
+ expect(p.unlink).toEqual(['a', 'b'])
+ expect(p.link).toEqual([])
+ })
+
+ it('never removes a real directory even when the system has a skill of that name', () => {
+ const p = plan({ enabled: false, system: [sys('a')], account: [{ name: 'a', kind: 'dir' }] })
+ expect(p.unlink).toEqual([])
+ })
+})
+
+describe('planSkillShare — the same-directory refusal', () => {
+ // The issue's own manual workaround is `ln -s ~/.claude/skills skills`, which makes the account's
+ // skills dir RESOLVE to the system one. Linking into it would plant links in the user's own
+ // folder, and the off-switch would then delete them from there.
+ it('refuses when the account skills dir realpath IS the system one', () => {
+ const p = plan({ accountSkillsDir: SYS, system: [sys('a')], account: [sys('a')] })
+ expect(p).toEqual({ link: [], unlink: [], alreadyLinked: [], skipped: [], refused: 'same-directory' })
+ })
+
+ it('refuses a nested pair in either direction', () => {
+ expect(plan({ accountSkillsDir: `${SYS}/nested`, system: [sys('a')] }).refused).toBe(
+ 'same-directory'
+ )
+ expect(plan({ systemSkillsDir: `${ACC}/nested`, system: [sys('a')] }).refused).toBe(
+ 'same-directory'
+ )
+ })
+
+ it('does NOT refuse a sibling whose path merely shares a prefix', () => {
+ expect(plan({ accountSkillsDir: `${SYS}-other`, system: [sys('a')] }).refused).toBeUndefined()
+ })
+
+ it('refuses on Windows regardless of case', () => {
+ const p = planSkillShare({
+ enabled: false,
+ systemSkillsDir: 'C:\\Users\\u\\.claude\\skills',
+ accountSkillsDir: 'C:\\USERS\\U\\.CLAUDE\\SKILLS',
+ system: [],
+ account: [ours('a', 'C:\\Users\\u\\.claude\\skills')],
+ win: true
+ })
+ expect(p.refused).toBe('same-directory')
+ expect(p.unlink).toEqual([])
+ })
+})
diff --git a/src/core/claude-skill-share-core.ts b/src/core/claude-skill-share-core.ts
new file mode 100644
index 000000000..f2ec505e2
--- /dev/null
+++ b/src/core/claude-skill-share-core.ts
@@ -0,0 +1,181 @@
+// Pure planning for the per-account "Share ~/.claude/skills with this account" option (issue #643).
+//
+// WHY THIS EXISTS. A managed Claude account gets its own config dir, which nodeterm passes as
+// CLAUDE_CONFIG_DIR. Claude Code resolves the user's skills as `join(CLAUDE_CONFIG_DIR ?? ~/.claude,
+// 'skills')` — MEASURED on 2.1.266 — so an account dir REPLACES `~/.claude/skills` wholesale rather
+// than adding to it, and nodeterm installs only its own canvas skill there. That isolation is often
+// the point; this module is the opt-back-in.
+//
+// WHY PER-SKILL LINKS AND NOT ONE LINK FOR THE WHOLE `skills` DIRECTORY. `installCanvasSkillInto`
+// writes `<configDir>/skills/manage-nodeterm-canvas/SKILL.md`. If `<configDir>/skills` were itself a
+// link into `~/.claude/skills`, every one of those writes would land in the user's SYSTEM skills
+// folder, and "turn it back off" would have to restore a directory it had first moved aside — a
+// destructive step on a folder we do not own. Linking each skill INDIVIDUALLY keeps the account's
+// own `skills/` a real directory, keeps the canvas skill local, and makes the off-switch safe by
+// construction: it removes links, and only links, and only ones it can prove it created.
+//
+// MEASURED: Claude Code 2.1.266 treats a symlinked entry inside `<CLAUDE_CONFIG_DIR>/skills/`
+// exactly like a real skill directory — strace shows it opening `skills/<name>` as a directory and
+// reading `skills/<name>/SKILL.md` for the link and for a real sibling identically. So per-skill
+// links are not a compromise; they are equivalent to the whole-directory link for discovery.
+//
+// OWNERSHIP RULE (the one this whole file turns on): an entry in the account's `skills/` is OURS
+// iff it is a symlink whose target normalizes to exactly `join(systemSkillsDir, <that entry's own
+// name>)`. Name-anchored, so what the ON path creates is precisely what the OFF path removes. A
+// real directory is never ours, whatever its name — which is what makes "never delete through the
+// link" a property of the plan rather than a promise about the applier.
+import path from 'path'
+
+/** Skill directory names nodeterm OWNS inside an account config dir. Never linked, never pruned:
+ * their presence is decided by nodeterm's own installers, not by this option. If sharing linked
+ * them, turning it off would delete a skill the canvas-control installer had put there, and the
+ * two owners would fight over the same name every launch. */
+export const NODETERM_OWNED_SKILLS = ['manage-nodeterm-canvas', 'get-linked-context'] as const
+
+/**
+ * One entry of a `skills/` directory, as the caller classified it.
+ * - SYSTEM entries are classified by FOLLOWING (`stat`): `dir` means "a skill we can link to".
+ * - ACCOUNT entries are classified by NOT following (`lstat`): `link` (with `linkTarget`) is the
+ * only kind that can be ours; a `dir` is the account's own skill and is untouchable.
+ * Two classifications, one shape — the planner reads each side for the one fact it needs.
+ */
+export interface SkillDirEntry {
+ name: string
+ kind: 'dir' | 'link' | 'other'
+ /** `readlink` value, for `kind: 'link'` only. */
+ linkTarget?: string
+}
+
+export type SkillSkipReason = 'reserved' | 'not-a-directory' | 'occupied'
+
+export interface SkillSharePlan {
+ /** Links to create: `<accountSkillsDir>/<name>` → `target`. */
+ link: { name: string; target: string }[]
+ /** Names to unlink under `<accountSkillsDir>` — every one of them proven ours. */
+ unlink: string[]
+ /** Links of ours that are ALREADY correct (ON only). Reported rather than left as silence: the
+ * Settings row says how many skills are shared, and "already linked" is most of that number on
+ * every pass after the first. */
+ alreadyLinked: string[]
+ skipped: { name: string; reason: SkillSkipReason }[]
+ /** Set when the two directories are the same one (or nested), and the plan is therefore empty. */
+ refused?: 'same-directory'
+}
+
+/**
+ * Normalize a path for LINK-TARGET comparison. Windows junction targets come back from `readlink`
+ * with the `\\?\` device prefix and frequently a trailing separator, so a raw string compare would
+ * call our own junction "not ours" and leak links the off-switch could never remove.
+ * `win` is a parameter, not a `process.platform` read, so the Windows branch is exercised by the
+ * unit tests on every CI platform.
+ */
+export function normalizeLinkPath(
+ p: string | undefined,
+ win = process.platform === 'win32'
+): string {
+ if (!p) return ''
+ const impl = win ? path.win32 : path.posix
+ let s = impl.normalize(win && p.startsWith('\\\\?\\') ? p.slice(4) : p)
+ // Trailing separators only — never trim a bare root (`/`) or a drive root (`C:\`) into nothing.
+ const trimmed = s.replace(/[\\/]+$/, '')
+ if (trimmed && !trimmed.endsWith(':')) s = trimmed
+ return win ? s.toLowerCase() : s
+}
+
+/** Is `child` the directory `parent` itself, or somewhere inside it? Separator-aware, so the same
+ * call answers for a Windows account dir and a POSIX one. */
+function isAtOrInside(parent: string, child: string, win: boolean): boolean {
+ const p = normalizeLinkPath(parent, win)
+ const c = normalizeLinkPath(child, win)
+ if (!p || !c) return false
+ if (c === p) return true
+ return c.startsWith(p.endsWith(win ? '\\' : '/') ? p : p + (win ? '\\' : '/'))
+}
+
+export interface SkillSharePlanInput {
+ /** The switch: `true` links, `false` removes every link we own. */
+ enabled: boolean
+ /** REALPATH of `~/.claude/skills` (resolved by the caller — see the refusal below). */
+ systemSkillsDir: string
+ /** REALPATH of `<accountConfigDir>/skills`. */
+ accountSkillsDir: string
+ /** Entries of `systemSkillsDir`, classified by following. */
+ system: readonly SkillDirEntry[]
+ /** Entries of `accountSkillsDir`, classified WITHOUT following. */
+ account: readonly SkillDirEntry[]
+ /** Defaults to `NODETERM_OWNED_SKILLS`. */
+ reserved?: readonly string[]
+ /** Windows path semantics. Defaults to this process's platform. */
+ win?: boolean
+}
+
+/**
+ * Decide what to link and what to unlink. Never touches the filesystem, never throws.
+ *
+ * THE REFUSAL IS LOAD-BEARING. The caller passes REALPATHS, so the hand-made version of this
+ * feature — the workaround from the issue, `ln -s ~/.claude/skills skills` — is caught here: the
+ * account's `skills/` then RESOLVES to the system one, and linking into it would write links into
+ * the user's own skills folder and, worse, let the off-switch delete them from there. Same for a
+ * linked account whose `configDir` was hand-edited to `~/.claude`. An empty plan is the answer.
+ */
+export function planSkillShare(input: SkillSharePlanInput): SkillSharePlan {
+ const win = input.win ?? process.platform === 'win32'
+ const reserved = new Set<string>(input.reserved ?? NODETERM_OWNED_SKILLS)
+ const plan: SkillSharePlan = { link: [], unlink: [], alreadyLinked: [], skipped: [] }
+
+ if (
+ isAtOrInside(input.systemSkillsDir, input.accountSkillsDir, win) ||
+ isAtOrInside(input.accountSkillsDir, input.systemSkillsDir, win)
+ ) {
+ return { ...plan, refused: 'same-directory' }
+ }
+
+ const join = (win ? path.win32 : path.posix).join
+ /** The ownership rule, name-anchored: a link at `<name>` pointing at `<systemSkills>/<name>`. */
+ const isOurs = (e: SkillDirEntry): boolean =>
+ e.kind === 'link' &&
+ normalizeLinkPath(e.linkTarget, win) ===
+ normalizeLinkPath(join(input.systemSkillsDir, e.name), win)
+
+ const accountByName = new Map(input.account.map((e) => [e.name, e]))
+
+ if (input.enabled) {
+ for (const sys of input.system) {
+ if (reserved.has(sys.name)) {
+ plan.skipped.push({ name: sys.name, reason: 'reserved' })
+ continue
+ }
+ if (sys.kind !== 'dir') {
+ // `manifest.json` and friends: a skill is a directory. Linking a file would also be the one
+ // shape a Windows junction cannot express.
+ plan.skipped.push({ name: sys.name, reason: 'not-a-directory' })
+ continue
+ }
+ const existing = accountByName.get(sys.name)
+ if (!existing) {
+ plan.link.push({ name: sys.name, target: join(input.systemSkillsDir, sys.name) })
+ continue
+ }
+ if (isOurs(existing)) {
+ plan.alreadyLinked.push(sys.name)
+ continue
+ }
+ // The account already has something by this name that we did not create — its own skill, or a
+ // link of the user's pointing somewhere else. The account's copy wins; we never overwrite.
+ plan.skipped.push({ name: sys.name, reason: 'occupied' })
+ }
+ // PRUNE. A link of ours whose system skill was deleted or renamed is a broken entry Claude Code
+ // would still try to read, and one whose name has since become reserved is a name we now own.
+ const sharable = new Set(
+ input.system.filter((e) => e.kind === 'dir' && !reserved.has(e.name)).map((e) => e.name)
+ )
+ for (const acc of input.account) {
+ if (isOurs(acc) && !sharable.has(acc.name)) plan.unlink.push(acc.name)
+ }
+ return plan
+ }
+
+ // OFF: remove exactly what ON creates, and nothing else.
+ for (const acc of input.account) if (isOurs(acc)) plan.unlink.push(acc.name)
+ return plan
+}
diff --git a/src/core/claude-skill-share.test.ts b/src/core/claude-skill-share.test.ts
new file mode 100644
index 000000000..52ecbfd68
--- /dev/null
+++ b/src/core/claude-skill-share.test.ts
@@ -0,0 +1,185 @@
+// Real-filesystem tests for the shared-skills applier. The whole risk of this feature is that a
+// wrong removal deletes a user's actual skills folder, so these run against real directories, real
+// symlinks and real content — a mocked `fs` would agree with whatever the code believed.
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { promises as fs } from 'fs'
+import os from 'os'
+import path from 'path'
+import { applySkillShare } from './claude-skill-share'
+
+let root = ''
+let sysDir = ''
+let cfgDir = ''
+const accDir = (): string => path.join(cfgDir, 'skills')
+
+async function makeSkill(dir: string, name: string, body = 'x'): Promise<string> {
+ const p = path.join(dir, name)
+ await fs.mkdir(p, { recursive: true })
+ await fs.writeFile(path.join(p, 'SKILL.md'), body)
+ return p
+}
+
+async function entries(dir: string): Promise<string[]> {
+ return (await fs.readdir(dir)).sort()
+}
+
+beforeEach(async () => {
+ root = await fs.mkdtemp(path.join(os.tmpdir(), 'nt-skillshare-'))
+ sysDir = path.join(root, 'home', '.claude', 'skills')
+ cfgDir = path.join(root, 'accounts', 'a1')
+ await fs.mkdir(sysDir, { recursive: true })
+ await fs.mkdir(accDir(), { recursive: true })
+})
+
+afterEach(async () => {
+ await fs.rm(root, { recursive: true, force: true })
+})
+
+describe('applySkillShare — on', () => {
+ it('links the system skills and leaves the canvas skill a real local directory', async () => {
+ await makeSkill(sysDir, 'alpha')
+ await makeSkill(sysDir, 'beta')
+ await makeSkill(sysDir, 'manage-nodeterm-canvas', 'SYSTEM COPY')
+ await makeSkill(accDir(), 'manage-nodeterm-canvas', 'ACCOUNT COPY')
+
+ const res = await applySkillShare(cfgDir, true, { systemDir: sysDir })
+ expect(res).toMatchObject({ linked: 2, unlinked: 0, shared: 2, failed: 0 })
+ expect(await entries(accDir())).toEqual(['alpha', 'beta', 'manage-nodeterm-canvas'])
+
+ // The links resolve to real skills…
+ expect(await fs.readFile(path.join(accDir(), 'alpha', 'SKILL.md'), 'utf8')).toBe('x')
+ // …and the canvas skill is untouched: still a real directory, still the ACCOUNT's copy.
+ expect((await fs.lstat(path.join(accDir(), 'manage-nodeterm-canvas'))).isSymbolicLink()).toBe(
+ false
+ )
+ expect(
+ await fs.readFile(path.join(accDir(), 'manage-nodeterm-canvas', 'SKILL.md'), 'utf8')
+ ).toBe('ACCOUNT COPY')
+ })
+
+ it("does not link a nodeterm-owned name even when the account has no copy of it yet", async () => {
+ // The Server Edition installs no canvas skill, so an account dir legitimately lacks it. The
+ // name is still ours: linking the system copy would put a skill under nodeterm's own name that
+ // the off-switch would then delete out from under the installer.
+ await makeSkill(sysDir, 'manage-nodeterm-canvas', 'SYSTEM COPY')
+ await makeSkill(sysDir, 'get-linked-context')
+ const res = await applySkillShare(cfgDir, true, { systemDir: sysDir })
+ expect(res).toMatchObject({ linked: 0, shared: 0 })
+ expect(await entries(accDir())).toEqual([])
+ })
+
+ it('is idempotent and picks up a skill added to the system dir since the last pass', async () => {
+ await makeSkill(sysDir, 'alpha')
+ expect((await applySkillShare(cfgDir, true, { systemDir: sysDir })).linked).toBe(1)
+
+ const second = await applySkillShare(cfgDir, true, { systemDir: sysDir })
+ expect(second).toMatchObject({ linked: 0, unlinked: 0, shared: 1 })
+
+ await makeSkill(sysDir, 'gamma')
+ const third = await applySkillShare(cfgDir, true, { systemDir: sysDir })
+ expect(third).toMatchObject({ linked: 1, shared: 2 })
+ expect(await entries(accDir())).toEqual(['alpha', 'gamma'])
+ })
+
+ it('prunes a link whose system skill was deleted, without touching the rest', async () => {
+ await makeSkill(sysDir, 'alpha')
+ await makeSkill(sysDir, 'doomed')
+ await applySkillShare(cfgDir, true, { systemDir: sysDir })
+ await fs.rm(path.join(sysDir, 'doomed'), { recursive: true })
+
+ const res = await applySkillShare(cfgDir, true, { systemDir: sysDir })
+ expect(res).toMatchObject({ unlinked: 1, shared: 1 })
+ expect(await entries(accDir())).toEqual(['alpha'])
+ })
+
+ it("never overwrites the account's own skill of the same name", async () => {
+ await makeSkill(sysDir, 'alpha', 'SYSTEM')
+ await makeSkill(accDir(), 'alpha', 'ACCOUNT')
+
+ const res = await applySkillShare(cfgDir, true, { systemDir: sysDir })
+ expect(res).toMatchObject({ linked: 0, occupied: 1 })
+ expect(await fs.readFile(path.join(accDir(), 'alpha', 'SKILL.md'), 'utf8')).toBe('ACCOUNT')
+ })
+
+ it('creates the account skills dir when it does not exist yet', async () => {
+ await fs.rm(accDir(), { recursive: true })
+ await makeSkill(sysDir, 'alpha')
+ expect((await applySkillShare(cfgDir, true, { systemDir: sysDir })).linked).toBe(1)
+ expect(await entries(accDir())).toEqual(['alpha'])
+ })
+
+ it('is a no-op, not a failure, when the machine has no ~/.claude/skills at all', async () => {
+ await fs.rm(sysDir, { recursive: true })
+ const res = await applySkillShare(cfgDir, true, { systemDir: sysDir })
+ expect(res).toMatchObject({ linked: 0, unlinked: 0, failed: 0 })
+ })
+})
+
+describe('applySkillShare — off', () => {
+ it("removes the links and RESTORES the account's own, non-empty skills folder", async () => {
+ await makeSkill(sysDir, 'alpha')
+ await makeSkill(sysDir, 'beta')
+ await makeSkill(accDir(), 'private-skill', 'MINE')
+ await makeSkill(accDir(), 'manage-nodeterm-canvas', 'CANVAS')
+ await applySkillShare(cfgDir, true, { systemDir: sysDir })
+ expect(await entries(accDir())).toEqual([
+ 'alpha',
+ 'beta',
+ 'manage-nodeterm-canvas',
+ 'private-skill'
+ ])
+
+ const res = await applySkillShare(cfgDir, false, { systemDir: sysDir })
+ expect(res).toMatchObject({ unlinked: 2, linked: 0, shared: 0 })
+ expect(await entries(accDir())).toEqual(['manage-nodeterm-canvas', 'private-skill'])
+ expect(await fs.readFile(path.join(accDir(), 'private-skill', 'SKILL.md'), 'utf8')).toBe('MINE')
+ })
+
+ it('NEVER deletes through the link: the system skills survive intact', async () => {
+ await makeSkill(sysDir, 'alpha', 'PRECIOUS')
+ await makeSkill(sysDir, 'beta', 'ALSO PRECIOUS')
+ await applySkillShare(cfgDir, true, { systemDir: sysDir })
+ await applySkillShare(cfgDir, false, { systemDir: sysDir })
+
+ expect(await entries(sysDir)).toEqual(['alpha', 'beta'])
+ expect(await fs.readFile(path.join(sysDir, 'alpha', 'SKILL.md'), 'utf8')).toBe('PRECIOUS')
+ })
+
+ it("leaves a user's own link to somewhere else alone", async () => {
+ const elsewhere = await makeSkill(path.join(root, 'elsewhere'), 'mine')
+ await fs.symlink(elsewhere, path.join(accDir(), 'mine'))
+
+ const res = await applySkillShare(cfgDir, false, { systemDir: sysDir })
+ expect(res.unlinked).toBe(0)
+ expect(await entries(accDir())).toEqual(['mine'])
+ })
+
+ it('is idempotent: a second off pass finds nothing left to remove', async () => {
+ await makeSkill(sysDir, 'alpha')
+ await applySkillShare(cfgDir, true, { systemDir: sysDir })
+ expect((await applySkillShare(cfgDir, false, { systemDir: sysDir })).unlinked).toBe(1)
+ expect((await applySkillShare(cfgDir, false, { systemDir: sysDir })).unlinked).toBe(0)
+ expect(await entries(accDir())).toEqual([])
+ })
+})
+
+describe('applySkillShare — the same-directory refusal', () => {
+ it("refuses when the account's skills/ is itself a link to the system one", async () => {
+ // Exactly the manual workaround from issue #643: `mv skills skills.bak && ln -s ~/.claude/skills skills`.
+ await makeSkill(sysDir, 'alpha', 'PRECIOUS')
+ await fs.rm(accDir(), { recursive: true })
+ await fs.symlink(sysDir, accDir())
+
+ const on = await applySkillShare(cfgDir, true, { systemDir: sysDir })
+ expect(on.refused).toBe('same-directory')
+ expect(on.linked).toBe(0)
+ // Nothing was planted inside the user's own folder…
+ expect(await entries(sysDir)).toEqual(['alpha'])
+
+ const off = await applySkillShare(cfgDir, false, { systemDir: sysDir })
+ expect(off.refused).toBe('same-directory')
+ // …and the off-switch did not reach through the link to delete their skills.
+ expect(await entries(sysDir)).toEqual(['alpha'])
+ expect(await fs.readFile(path.join(sysDir, 'alpha', 'SKILL.md'), 'utf8')).toBe('PRECIOUS')
+ })
+})
diff --git a/src/core/claude-skill-share.ts b/src/core/claude-skill-share.ts
new file mode 100644
index 000000000..913973bd2
--- /dev/null
+++ b/src/core/claude-skill-share.ts
@@ -0,0 +1,218 @@
+// Apply the per-account "Share ~/.claude/skills with this account" plan (issue #643).
+// The decisions live in the pure `claude-skill-share-core.ts`; this file only reads the two
+// directories, hands them over, and performs the link/unlink the plan asked for. It NEVER throws:
+// it runs on the launch sweep beside the hook installers, whose contract is already fail-open, and
+// one unreadable skill directory must not take a boot down.
+//
+// TWO PLATFORM DECISIONS, both deliberate:
+//
+// 1. `type: 'junction'`, not `'dir'`. A Windows directory SYMLINK needs Developer Mode or an
+// elevated process (`worktree-shared-paths.ts` hits exactly that and has to report EPERM);
+// a directory JUNCTION needs neither, and every target here is an absolute directory — the two
+// conditions a junction has. On POSIX Node ignores the type argument and creates an ordinary
+// symlink, so one call serves both platforms and the feature does not have to be declared
+// unavailable on Windows.
+// 2. Removal is `unlink`, then `rmdir` on failure. Windows refuses `unlink` on a directory
+// junction; `rmdir` removes the link itself and never its contents. Both calls are safe on a
+// real directory too: `unlink` fails with EISDIR/EPERM and `rmdir` fails with ENOTEMPTY, so even
+// a plan that somehow named a real skill could not delete it. The plan cannot — every unlink it
+// emits is a proven link — but the applier is not the only thing standing between a user's
+// skills folder and an `rm -rf`, and that is the point.
+import { promises as fs } from 'fs'
+import { homedir } from 'os'
+import path from 'path'
+import type { ClaudeSkillShareResult } from '../shared/types'
+import {
+ NODETERM_OWNED_SKILLS,
+ planSkillShare,
+ type SkillDirEntry,
+ type SkillSharePlan
+} from './claude-skill-share-core'
+
+/** What a shared-skills apply did, for the Settings row and for logs. Never an exception.
+ * Declared in `shared/types` because it crosses the IPC boundary; aliased here so this module's
+ * own callers keep importing it from where the work happens. */
+export type SkillShareResult = ClaudeSkillShareResult
+
+/** "Nothing happened", the shape every refusal and every failure returns. */
+export const EMPTY_SKILL_SHARE: SkillShareResult = {
+ linked: 0,
+ unlinked: 0,
+ shared: 0,
+ occupied: 0,
+ failed: 0
+}
+const EMPTY = EMPTY_SKILL_SHARE
+
+/** The machine's system skills directory (`~/.claude/skills`) — the one this option shares. */
+export function systemSkillsDir(): string {
+ return path.join(homedir(), '.claude', 'skills')
+}
+
+/** `<configDir>/skills` — where Claude Code looks when CLAUDE_CONFIG_DIR is that dir. */
+export function accountSkillsDir(configDir: string): string {
+ return path.join(configDir, 'skills')
+}
+
+/** `realpath`, or the input unchanged when the path does not exist yet. The plan's same-directory
+ * refusal compares REAL paths, so a `skills/` that is itself a link into the system dir (the
+ * issue's manual workaround) is recognised for what it is rather than compared as a string. */
+async function realOrSelf(p: string): Promise<string> {
+ try {
+ return await fs.realpath(p)
+ } catch {
+ return p
+ }
+}
+
+/** Entries of the SYSTEM skills dir, classified by FOLLOWING: a `dir` is a skill we can link to.
+ * A missing directory is an empty list, not a failure — a machine with no user skills is the
+ * ordinary case, and while sharing is ON it still has to drive the stale-link prune. */
+async function readSystemEntries(dir: string): Promise<SkillDirEntry[]> {
+ let names: string[]
+ try {
+ names = await fs.readdir(dir)
+ } catch {
+ return []
+ }
+ const out: SkillDirEntry[] = []
+ for (const name of names) {
+ let kind: SkillDirEntry['kind'] = 'other'
+ try {
+ // stat, not lstat: a user whose `~/.claude/skills/foo` is itself a link to a checked-out
+ // skill repo has a perfectly good skill, and Claude Code reads it as one.
+ if ((await fs.stat(path.join(dir, name))).isDirectory()) kind = 'dir'
+ } catch {
+ kind = 'other' // broken link / vanished — never a link candidate
+ }
+ out.push({ name, kind })
+ }
+ return out
+}
+
+/** Entries of the ACCOUNT skills dir, classified WITHOUT following: only a `link` can be ours. */
+async function readAccountEntries(dir: string): Promise<SkillDirEntry[]> {
+ let names: string[]
+ try {
+ names = await fs.readdir(dir)
+ } catch {
+ return []
+ }
+ const out: SkillDirEntry[] = []
+ for (const name of names) {
+ const p = path.join(dir, name)
+ try {
+ const st = await fs.lstat(p)
+ if (st.isSymbolicLink()) {
+ out.push({ name, kind: 'link', linkTarget: await fs.readlink(p) })
+ } else {
+ out.push({ name, kind: st.isDirectory() ? 'dir' : 'other' })
+ }
+ } catch {
+ // Unreadable: report it as `other`, which the planner can only ever skip. Never as a link —
+ // that is the one classification that authorises a removal.
+ out.push({ name, kind: 'other' })
+ }
+ }
+ return out
+}
+
+/** Remove one link. See the header: `unlink` first, `rmdir` for a Windows junction. */
+async function removeLink(p: string): Promise<void> {
+ try {
+ await fs.unlink(p)
+ } catch (e) {
+ if ((e as NodeJS.ErrnoException).code === 'ENOENT') return
+ await fs.rmdir(p)
+ }
+}
+
+/**
+ * Reconcile one account's shared skills to `enabled`. Idempotent in BOTH directions, which is what
+ * lets the launch sweep call it for every local account on every boot: ON re-links whatever the
+ * user has added to `~/.claude/skills` since (a link is not a copy for the skills that already
+ * exist, but a NEW system skill needs a new link) and prunes the ones whose target is gone; OFF
+ * removes exactly the links ON creates, so a settings.json hand-edited while the app was closed
+ * still converges.
+ */
+export async function applySkillShare(
+ configDir: string,
+ enabled: boolean,
+ opts: {
+ /** The system skills dir. Injected by the tests so they never touch the developer's own
+ * `~/.claude/skills` — this applier CREATES AND REMOVES LINKS, and a suite that ran against a
+ * real home directory would be one bug away from editing it. */
+ systemDir?: string
+ reserved?: readonly string[]
+ } = {}
+): Promise<SkillShareResult> {
+ const reserved = opts.reserved ?? NODETERM_OWNED_SKILLS
+ try {
+ const sysDir = await realOrSelf(opts.systemDir ?? systemSkillsDir())
+ const accDir = accountSkillsDir(configDir)
+ const realAccDir = await realOrSelf(accDir)
+ const [system, account] = await Promise.all([
+ readSystemEntries(sysDir),
+ readAccountEntries(accDir)
+ ])
+ const plan = planSkillShare({
+ enabled,
+ systemSkillsDir: sysDir,
+ accountSkillsDir: realAccDir,
+ system,
+ account,
+ reserved
+ })
+ if (plan.refused) return { ...EMPTY, refused: plan.refused }
+ return await runPlan(accDir, plan, enabled)
+ } catch (e) {
+ console.warn('[skill-share] apply failed', configDir, e)
+ return { ...EMPTY, failed: 1 }
+ }
+}
+
+async function runPlan(
+ accDir: string,
+ plan: SkillSharePlan,
+ enabled: boolean
+): Promise<SkillShareResult> {
+ const res: SkillShareResult = {
+ ...EMPTY,
+ occupied: plan.skipped.filter((s) => s.reason === 'occupied').length
+ }
+ // Unlink FIRST: a stale link and its replacement can share a name (a system skill deleted and
+ // re-created between two sweeps), and `symlink` refuses an existing path.
+ for (const name of plan.unlink) {
+ try {
+ await removeLink(path.join(accDir, name))
+ res.unlinked++
+ } catch (e) {
+ res.failed++
+ console.warn('[skill-share] unlink failed', path.join(accDir, name), e)
+ }
+ }
+ if (plan.link.length) {
+ // Only when there is something to link: an OFF pass must not conjure a `skills/` directory into
+ // an account that never had one (the Server Edition installs no canvas skill, so some accounts
+ // legitimately have none).
+ try {
+ await fs.mkdir(accDir, { recursive: true })
+ } catch {
+ /* the per-link error below reports it */
+ }
+ }
+ for (const { name, target } of plan.link) {
+ try {
+ await fs.symlink(target, path.join(accDir, name), 'junction')
+ res.linked++
+ } catch (e) {
+ res.failed++
+ console.warn('[skill-share] link failed', path.join(accDir, name), e)
+ }
+ }
+ // What is shared AFTER this pass: the links that were already right, plus the ones that actually
+ // succeeded. A failed `symlink` must not inflate the row — the whole point of the number is that
+ // the user can check it against their own folder.
+ res.shared = enabled ? plan.alreadyLinked.length + res.linked : 0
+ return res
+}
diff --git a/src/preload/index.ts b/src/preload/index.ts
index d9354caec..0fbf90097 100644
--- a/src/preload/index.ts
+++ b/src/preload/index.ts
@@ -546,7 +546,9 @@ const api: NodeTerminalApi = {
waitLogin: (id, ctx) => ipcRenderer.invoke(IPC.claudeAccountsWaitLogin, id, ctx),
cancelWaitLogin: (id) => ipcRenderer.invoke(IPC.claudeAccountsCancelWait, id),
remove: (id, ctx) => ipcRenderer.invoke(IPC.claudeAccountsRemove, id, ctx),
- link: (configDir) => ipcRenderer.invoke(IPC.claudeAccountsLink, configDir)
+ link: (configDir) => ipcRenderer.invoke(IPC.claudeAccountsLink, configDir),
+ setSkillSharing: (id, enabled) =>
+ ipcRenderer.invoke(IPC.claudeAccountsSetSkillSharing, id, enabled)
},
codexAccounts: {
add: () => ipcRenderer.invoke(IPC.codexAccountsAdd),
diff --git a/src/renderer/bridge/stubs.ts b/src/renderer/bridge/stubs.ts
index d34f7145a..8b7866a68 100644
--- a/src/renderer/bridge/stubs.ts
+++ b/src/renderer/bridge/stubs.ts
@@ -362,7 +362,8 @@ export function buildStubApi(): Omit<
waitLogin: U('claudeAccounts.waitLogin'),
cancelWaitLogin: U('claudeAccounts.cancelWaitLogin'),
remove: U('claudeAccounts.remove'),
- link: U('claudeAccounts.link')
+ link: U('claudeAccounts.link'),
+ setSkillSharing: U('claudeAccounts.setSkillSharing')
},
codexAccounts: {
add: U('codexAccounts.add'),
diff --git a/src/renderer/bridge/ws-bridge.ts b/src/renderer/bridge/ws-bridge.ts
index 442e9fff5..45b026491 100644
--- a/src/renderer/bridge/ws-bridge.ts
+++ b/src/renderer/bridge/ws-bridge.ts
@@ -27,6 +27,7 @@ import {
type ClaudeCliCaps,
type GrokApi,
type GrokCliCaps,
+ type ClaudeSkillShareResult,
type CodexApi,
type CodexIdentityCaps,
UNKNOWN_CODEX_IDENTITY_CAPS,
@@ -946,7 +947,15 @@ export function buildClaudeAccountsApi(client: RpcClient): Pick<NodeTerminalApi,
id: string
configDir: string
email: string | null
- }>
+ }>,
+ // Real, not a stub: the whole implementation is core, so the machine the browser is served
+ // FROM is exactly the machine whose `~/.claude/skills` the option shares (issue #643).
+ setSkillSharing: (id, enabled) =>
+ client.request(
+ IPC.claudeAccountsSetSkillSharing,
+ id,
+ enabled
+ ) as Promise<ClaudeSkillShareResult>
}
}
}
diff --git a/src/renderer/components/settings/sections/AccountsSection.tsx b/src/renderer/components/settings/sections/AccountsSection.tsx
index 29f022892..52f71a594 100644
--- a/src/renderer/components/settings/sections/AccountsSection.tsx
+++ b/src/renderer/components/settings/sections/AccountsSection.tsx
@@ -1,6 +1,6 @@
import { useEffect, useState } from 'react'
import { IconClose } from '../../icons'
-import type { ClaudeAccount } from '@shared/types'
+import type { ClaudeAccount, ClaudeSkillShareResult } from '@shared/types'
import type { CodexAccount } from '@shared/codex-account'
import { E_UNSUPPORTED } from '@shared/rpc'
import { sshHostKey } from '@shared/ssh'
@@ -23,6 +23,7 @@ import {
} from '../../../lib/codexMachineGroups'
import { configDirLabel, unlinkedConfigDirs } from '../../../lib/accountChip'
import { presentAccount } from '../../../lib/accountPresentation'
+import { skillShareNote } from '../../../lib/skillSharing'
import { codexAccountSelectable } from '../../../canvas/codex-account-switch'
import { AccountIdentityPills } from '../../AccountIdentityPills'
import { ConfirmDialog } from '../../ConfirmDialog'
@@ -30,6 +31,7 @@ import { SettingsSection } from '../SettingsSection'
import { SearchableRow } from '../SearchableRow'
import { Button } from '@renderer/ui/Button'
import { Input } from '@renderer/ui/Input'
+import { Switch } from '@renderer/ui/Switch'
import { cn } from '@renderer/ui/cn'
import { thisMachine, thisMachineCap } from '../../../lib/machineName'
@@ -188,6 +190,61 @@ function AccountColorSwatches({
)
}
+/**
+ * The per-account "Share ~/.claude/skills with this account" switch (issue #643).
+ *
+ * A managed account's config dir REPLACES `~/.claude/skills` rather than adding to it — that is
+ * Claude Code's own `join(CLAUDE_CONFIG_DIR, 'skills')` — so a fresh account shows only the skills
+ * nodeterm installed. The isolation is often the point, which is why this is off by default; this
+ * is the way back in.
+ *
+ * The copy says **edits flow both ways** because they do: each system skill is LINKED, not copied,
+ * so editing one from inside this account edits the machine's copy. A user who reads "share" as
+ * "copy" would find that out by losing work.
+ *
+ * The switch is DISABLED (never hidden) for a remote account, with the reason — a silently missing
+ * control teaches nothing, and an SSH account's skills live on its host, which v1 does not reach.
+ */
+function SkillSharingRow({
+ account,
+ onChange
+}: {
+ account: ClaudeAccount
+ /** Resolves to the line to show under the switch, or null for "nothing worth saying". */
+ onChange: (enabled: boolean) => Promise<string | null>
+}): React.JSX.Element {
+ const [busy, setBusy] = useState(false)
+ const [note, setNote] = useState<string | null>(null)
+ const remote = !!account.host
+ const on = !!account.shareSystemSkills
+ return (
+ <div className="pt-1">
+ <div className="flex items-center gap-2">
+ <Switch
+ checked={on}
+ disabled={remote || busy}
+ ariaLabel={`Share system skills with ${account.label || account.id}`}
+ onChange={(v) => {
+ setBusy(true)
+ setNote(null)
+ void onChange(v)
+ .then(setNote)
+ .catch((e: unknown) => setNote(errorText(e, 'Could not update skill sharing.')))
+ .finally(() => setBusy(false))
+ }}
+ />
+ <span className="text-[12px] text-muted">Share ~/.claude/skills</span>
+ </div>
+ <p className="pt-1 text-[11px] text-muted">
+ {remote
+ ? 'Not available for accounts on an SSH host — their skills live on that machine.'
+ : 'Links this machine’s skills into the account. They are shared, not copied, so an edit from either side changes the same file. Turning this off removes only the links.'}
+ </p>
+ {note ? <p className="pt-1 text-[11px] text-[color:var(--warn)]">{note}</p> : null}
+ </div>
+ )
+}
+
/** Counts nodes bound to an account across every project's SERIALIZED nodes. The active
* project's live React Flow edits since the last commit aren't reflected here, so the count
* can be slightly stale for the active canvas — acceptable for a confirmation warning. */
@@ -250,6 +307,29 @@ export function AccountsSection({ isActive }: { isActive: boolean }): React.JSX.
const setColor = (id: string, color?: string): void =>
applyAccounts((accs) => accs.map((a) => (a.id === id ? { ...a, color } : a)))
+ /**
+ * Flip `~/.claude/skills` sharing for one account (issue #643). The FILESYSTEM is reconciled
+ * first and the flag is persisted only if that call came back — because the flag is what the
+ * launch sweep replays, and a stored `true` whose links were never made would make the switch
+ * lie until the next boot. A REFUSAL is likewise not a state to store: nothing happened, so the
+ * switch stays where it was and the note says why.
+ */
+ const setSkillSharing = async (id: string, enabled: boolean): Promise<string | null> => {
+ let res: ClaudeSkillShareResult
+ try {
+ res = await window.nodeTerminal.claudeAccounts.setSkillSharing(id, enabled)
+ } catch (e) {
+ if (isUnsupported(e)) return 'Sharing skills is not available on this connection.'
+ throw e
+ }
+ if (!res.refused) {
+ applyAccounts((accs) =>
+ accs.map((a) => (a.id === id ? { ...a, shareSystemSkills: enabled } : a))
+ )
+ }
+ return skillShareNote(res, enabled)
+ }
+
// The open project whose SSH host matches a remote account (needed for the ssh context of
// waitLogin / remove). Undefined for local accounts, or when no such project is open.
const projectIdForHost = (host?: string): string | undefined => {
@@ -751,6 +831,10 @@ export function AccountsSection({ isActive }: { isActive: boolean }): React.JSX.
color={account.color}
onPick={(c) => setColor(account.id, c)}
/>
+ <SkillSharingRow
+ account={account}
+ onChange={(v) => setSkillSharing(account.id, v)}
+ />
</div>
<div className="flex shrink-0 items-center gap-2">
{account.pending
diff --git a/src/renderer/lib/skillSharing.test.ts b/src/renderer/lib/skillSharing.test.ts
new file mode 100644
index 000000000..5a98ecb72
--- /dev/null
+++ b/src/renderer/lib/skillSharing.test.ts
@@ -0,0 +1,51 @@
+import { describe, expect, it } from 'vitest'
+import { skillShareNote } from './skillSharing'
+import type { ClaudeSkillShareResult } from '@shared/types'
+
+const res = (over: Partial<ClaudeSkillShareResult> = {}): ClaudeSkillShareResult => ({
+ linked: 0,
+ unlinked: 0,
+ shared: 0,
+ occupied: 0,
+ failed: 0,
+ ...over
+})
+
+describe('skillShareNote', () => {
+ it('says nothing extra for a clean off', () => {
+ expect(skillShareNote(res({ unlinked: 3 }), false)).toBeNull()
+ })
+
+ it('counts what is shared after a clean on', () => {
+ expect(skillShareNote(res({ linked: 4, shared: 4 }), true)).toBe('Sharing 4 skills.')
+ expect(skillShareNote(res({ linked: 1, shared: 1 }), true)).toBe('Sharing 1 skill.')
+ })
+
+ it('distinguishes "on, but the folder is empty" from silence', () => {
+ expect(skillShareNote(res(), true)).toBe('No skills found in ~/.claude/skills.')
+ })
+
+ it('names skills the account already had, which the switch cannot show', () => {
+ expect(skillShareNote(res({ linked: 2, shared: 2, occupied: 1 }), true)).toBe(
+ 'Sharing 2 skills. 1 was skipped — this account already has a skill by that name.'
+ )
+ })
+
+ it('never reports a partial failure as success, in either direction', () => {
+ expect(skillShareNote(res({ linked: 2, shared: 2, failed: 1 }), true)).toBe(
+ '1 skill could not be linked.'
+ )
+ expect(skillShareNote(res({ unlinked: 2, failed: 2 }), false)).toBe(
+ '2 skills could not be unlinked.'
+ )
+ })
+
+ it('explains each refusal rather than reporting nothing', () => {
+ expect(skillShareNote(res({ refused: 'same-directory' }), true)).toContain(
+ 'already points at ~/.claude/skills'
+ )
+ expect(skillShareNote(res({ refused: 'remote-account' }), true)).toContain('SSH host')
+ // A refusal outranks the off-switch's silence: "nothing happened" is exactly what needs saying.
+ expect(skillShareNote(res({ refused: 'same-directory' }), false)).not.toBeNull()
+ })
+})
diff --git a/src/renderer/lib/skillSharing.ts b/src/renderer/lib/skillSharing.ts
new file mode 100644
index 000000000..4135b0214
--- /dev/null
+++ b/src/renderer/lib/skillSharing.ts
@@ -0,0 +1,35 @@
+// What to tell the user after flipping "Share ~/.claude/skills with this account" (issue #643).
+// Pure, so the sentences are unit-tested rather than reasoned about — and because each one names
+// a DIFFERENT fact the user can act on, which is the whole reason the applier returns counts
+// instead of a boolean.
+import type { ClaudeSkillShareResult } from '@shared/types'
+
+/**
+ * `null` = nothing worth saying (the switch itself already said it). A returned string is always
+ * something the user could not have inferred from the switch position: a refusal, a partial
+ * failure, or skills their own account already had under the same name.
+ */
+export function skillShareNote(res: ClaudeSkillShareResult, enabled: boolean): string | null {
+ if (res.refused === 'remote-account') {
+ return 'Accounts on an SSH host keep their own skills — nothing was changed.'
+ }
+ if (res.refused === 'same-directory') {
+ // The manual workaround from the issue: `skills` is already a link to the system folder. Saying
+ // "nothing changed" alone would read as a bug; naming the cause makes it a state to undo.
+ return 'This account’s skills folder already points at ~/.claude/skills, so it is left alone.'
+ }
+ if (res.failed > 0) {
+ // Never silently partial: some links exist and some do not, and only the user can see which.
+ return `${res.failed} ${res.failed === 1 ? 'skill' : 'skills'} could not be ${
+ enabled ? 'linked' : 'unlinked'
+ }.`
+ }
+ if (!enabled) return null
+ if (res.occupied > 0) {
+ return `Sharing ${res.shared} ${res.shared === 1 ? 'skill' : 'skills'}. ${res.occupied} ${
+ res.occupied === 1 ? 'was' : 'were'
+ } skipped — this account already has ${res.occupied === 1 ? 'a skill' : 'skills'} by that name.`
+ }
+ if (res.shared === 0) return 'No skills found in ~/.claude/skills.'
+ return `Sharing ${res.shared} ${res.shared === 1 ? 'skill' : 'skills'}.`
+}
diff --git a/src/shared/ipc.ts b/src/shared/ipc.ts
index fb322ceed..c2020f741 100644
--- a/src/shared/ipc.ts
+++ b/src/shared/ipc.ts
@@ -44,6 +44,7 @@ export const IPC = {
claudeAccountsCancelWait: 'claude-accounts:cancel-wait',
claudeAccountsRemove: 'claude-accounts:remove',
claudeAccountsLink: 'claude-accounts:link',
+ claudeAccountsSetSkillSharing: 'claude-accounts:set-skill-sharing',
// Machine-scoped managed Codex accounts (S6). Add/device-login/removal, plus the three-phase,
// owner-authorized account switch (resume the SAME conversation id, never fork) and the
// source-side leg of moving an idle conversation to an SSH account. See main/codex-accounts.ts.
diff --git a/src/shared/types.ts b/src/shared/types.ts
index 609b10b9c..ee0fa8053 100644
--- a/src/shared/types.ts
+++ b/src/shared/types.ts
@@ -1204,6 +1204,16 @@ export interface ClaudeAccount {
* (settings.json), so it is re-validated at every point of use (absolute, normalized).
*/
configDir?: string
+ /**
+ * Share the machine's system skills (`~/.claude/skills`) with this account (issue #643).
+ * OFF/absent = the isolation Claude Code's own `join(CLAUDE_CONFIG_DIR, 'skills')` gives, which
+ * is the default and often the point. ON = each system skill is LINKED into the account's own
+ * `skills/` individually — the account's directory stays real, nodeterm's own skills keep their
+ * names, and turning it off removes only the links (`core/claude-skill-share.ts`).
+ * Reconciled at launch and whenever the switch is flipped; LOCAL accounts only — a remote (SSH)
+ * account's skills live on its host and are out of scope for v1.
+ */
+ shareSystemSkills?: boolean
createdAt: number
}
@@ -2510,6 +2520,31 @@ export interface ClaudeAccountsApi {
* in yet), and installs the managed status hook into it. Local only — no SSH ctx.
*/
link(configDir: string): Promise<{ id: string; configDir: string; email: string | null }>
+ /**
+ * Turn `~/.claude/skills` sharing on or off for one LOCAL account (issue #643) and reconcile the
+ * filesystem now. Idempotent in both directions; the renderer owns the settings flag and calls
+ * this for the effect. Never throws — the result reports what happened, including `refused`
+ * (the account's `skills/` resolves to the system one) and `failed` (an EPERM, a vanished skill).
+ */
+ setSkillSharing(id: string, enabled: boolean): Promise<ClaudeSkillShareResult>
+}
+
+/** What one `setSkillSharing` / launch reconcile did. Counts, never an exception. */
+export interface ClaudeSkillShareResult {
+ linked: number
+ unlinked: number
+ /** Links of ours present after the call — what the Settings row reports. */
+ shared: number
+ /** System skills not shared because the account has its own entry by that name. */
+ occupied: number
+ failed: number
+ /**
+ * Why nothing was done. `same-directory`: the account's `skills/` resolves to the system one
+ * (a hand-made whole-directory link, or a linked account pointed at `~/.claude`) — linking into
+ * it would plant links in the user's own folder and let the off-switch delete them from there.
+ * `remote-account`: an SSH account, whose skills live on its host (out of scope for v1).
+ */
+ refused?: 'same-directory' | 'remote-account'
}
/**