Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
Make ok init --no-skills a per-invocation skip (PRD-7720) (#3176)
tim-inkeep1c10c0208581
diff --git a/.changeset/no-skills-per-invocation.md b/.changeset/no-skills-per-invocation.mdnew file mode 100644index 000000000..fc9839dec--- /dev/null+++ b/.changeset/no-skills-per-invocation.md@@ -0,0 +1,9 @@+---+"@inkeep/open-knowledge": patch+---++`ok init --no-skills` now only skips installing the built-in skills for that run. It no longer turns them off across your whole machine.++Previously the flag recorded a machine-wide opt-out and deleted the built-in skills from your user-global skill folders, so running it once in a throwaway directory disabled them for every project. The recorded opt-out also persisted, so the desktop and `ok repair-skills` sweeps removed the skills again on every launch — reinstalling them by hand appeared to work until the next launch deleted them.++The flag now installs nothing and records nothing. Skills already on your machine are left alone. If you want to turn the built-in skills off for real, use the Settings toggle or the first-launch prompt, which is where that choice was always meant to live. If you have already been affected, re-enable them from Settings or run `ok init` without the flag.diff --git a/docs/content/reference/what-open-knowledge-writes.mdx b/docs/content/reference/what-open-knowledge-writes.mdxindex 0e028b6fe..7d53c3acb 100644--- a/docs/content/reference/what-open-knowledge-writes.mdx+++ b/docs/content/reference/what-open-knowledge-writes.mdx@@ -145,7 +145,7 @@ Installing `@inkeep/open-knowledge` from npm (or invoking it with `npx`) drops t| `<pkg>/dist/native/` | Bundled native TOML-editing addon, shipped inside the package | Outside-project (package dir) |<Callout type="info" title="Opt out">- Installing the package writes nothing outside its own directory, so there is nothing to opt out of here. The user-global skills are installed by `ok init`, and `ok init --no-skills` declines them.+ Installing the package writes nothing outside its own directory, so there is nothing to opt out of here. The user-global skills are installed by `ok init`, and `ok init --no-skills` skips installing them for that run.</Callout>### `ok init`@@ -190,7 +190,7 @@ With `--scope user` or `both` (the default), `ok init` also registers the `open-| `~/.ok/skill-state.yml` | Records which skill version is installed, so the step is skipped next time | Outside-project (home dir) || `~/.ok/skill-install-events.jsonl` | Append-only local log of skill-install attempts | Outside-project (home dir) |-The install is **non-fatal** (`ok init` still exits 0 if it fails), **version-gated** (a no-op when the current version is already installed), and needs **no network access**. Decline it with `ok init --no-skills`, or choose individual bundles with `--skills <ids>`; the decision is remembered in `~/.ok/skill-state.yml` and honored by every later install path. `ok repair-skills` re-runs it.+The install is **non-fatal** (`ok init` still exits 0 if it fails), **version-gated** (a no-op when the current version is already installed), and needs **no network access**. Skip it for one run with `ok init --no-skills`, or choose individual bundles with `--skills <ids>`. Skipping records nothing and removes nothing, so skills already on the machine are left alone. An installed bundle is remembered in `~/.ok/skill-state.yml` and honored by every later install path; to turn the built-in skills off for good, use the first-launch prompt or the Settings toggle, which record a durable machine-wide choice. `ok repair-skills` re-runs it.Pi is the exception: it has no user-level MCP config (it has no MCP support at all), so its integration is only ever the project-scoped bridge extension above.@@ -201,7 +201,7 @@ On Windows, Claude Desktop and OpenCode configs live under `%APPDATA%\Claude\` a<Callout type="info" title="Controlling it">- `--no-mcp` — scaffold `.ok/` only; register nothing with any editor.- `--scope user | project | both` — where the MCP entry is written. In an interactive terminal, `ok init` prompts for this; scripted/CI runs default to `both`, so pass the flag to constrain them.- - `--no-skills` — install no user-global skills; `--skills discovery,write-skill` — install only the named bundles. Default installs both. The choice is recorded and honored by the desktop app too.+ - `--no-skills` — install no user-global skills on this run; `--skills discovery,write-skill` — install only the named bundles. Default installs both. Installing is recorded and honored by the desktop app too; skipping is not recorded, so it never affects another project.- `--local-only` (vs `--shared`) — keep `.ok/` out of git.</Callout>diff --git a/packages/cli/src/commands/init.test.ts b/packages/cli/src/commands/init.test.tsindex 7115921c9..2dff63217 100644--- a/packages/cli/src/commands/init.test.ts+++ b/packages/cli/src/commands/init.test.ts@@ -13,6 +13,7 @@ import {} from 'node:fs';import { tmpdir } from 'node:os';import { dirname, join, resolve } from 'node:path';+import { resolveBundleEnabled } from '@inkeep/open-knowledge-core';import { readBundleDecision } from '@inkeep/open-knowledge-server';import { afterEach, beforeEach, describe, expect, it } from 'vitest';import { parse as parseYaml } from 'yaml';@@ -1018,7 +1019,10 @@ describe('runInit', () => {expect(await readBundleDecision(fakeHome, 'open-knowledge-write-skill')).toBe(true);});- it('--no-skills installs nothing and records both declined', async () => {+ it('--no-skills installs nothing and records NOTHING', async () => {+ // The flag is a per-invocation skip. Recording a decline here would speak+ // for every project on the machine, since these bundles exist once at+ // `~/.agents/skills/<name>` with no per-project copy.const installed: (string | undefined)[] = [];await runInitForTest({skills: false,@@ -1028,8 +1032,35 @@ describe('runInit', () => {},});expect(installed).toEqual([]);- expect(await readBundleDecision(fakeHome, 'open-knowledge-discovery')).toBe(false);- expect(await readBundleDecision(fakeHome, 'open-knowledge-write-skill')).toBe(false);+ expect(await readBundleDecision(fakeHome, 'open-knowledge-discovery')).toBeNull();+ expect(await readBundleDecision(fakeHome, 'open-knowledge-write-skill')).toBeNull();+ });++ it('--no-skills leaves bundles another project already installed on disk', async () => {+ // The regression: one `--no-skills` in a throwaway directory used to+ // delete the built-ins for every project, then re-delete them on every+ // launch via the recorded decline.+ const central = join(fakeHome, '.agents', 'skills');+ for (const name of ['open-knowledge-discovery', 'open-knowledge-write-skill']) {+ mkdirSync(join(central, name), { recursive: true });+ writeFileSync(join(central, name, 'SKILL.md'), '# Installed earlier\n');+ }++ await runInitForTest({ skills: false, installUserSkill: async () => 'installed' });++ for (const name of ['open-knowledge-discovery', 'open-knowledge-write-skill']) {+ expect(existsSync(join(central, name, 'SKILL.md'))).toBe(true);+ // And no decline recorded, so no sweep re-deletes them later.+ expect(await readBundleDecision(fakeHome, name)).toBeNull();+ }+ });++ it('an unrecorded bundle grandfathers to disk, which is why recording nothing is correct', () => {+ // The policy the fix rests on: absent a decision, both reclaim sweeps+ // follow whatever is on disk. Recording nothing therefore yields the+ // right answer on BOTH sides, without a durable machine-wide write.+ expect(resolveBundleEnabled(null, { installedOnDisk: false })).toBe(false);+ expect(resolveBundleEnabled(null, { installedOnDisk: true })).toBe(true);});it('--skills discovery installs only discovery', async () => {@@ -1043,7 +1074,9 @@ describe('runInit', () => {});expect(installed).toEqual(['discovery']);expect(await readBundleDecision(fakeHome, 'open-knowledge-discovery')).toBe(true);- expect(await readBundleDecision(fakeHome, 'open-knowledge-write-skill')).toBe(false);+ // Not chosen is not the same as declined — the un-selected bundle stays+ // unrecorded so it grandfathers to disk rather than being turned off.+ expect(await readBundleDecision(fakeHome, 'open-knowledge-write-skill')).toBeNull();});it('installs every enabled bundle with force so the shared cli-hosts version key cannot skip the second', async () => {@@ -1066,7 +1099,15 @@ describe('runInit', () => {});expect(result.skillInstall).toBe('declined');const output = formatInitResult(result, testDir);- expect(output).toContain('opted out');+ expect(output).toContain('skipped for this run');+ // Not 'for this project' — the bundles are machine-wide, so when they are+ // already installed nothing is skipped for this project at all.+ expect(output).not.toContain('for this project');+ // The copy must not claim a machine-wide removal the flag no longer does.+ // Matched on the old wording specifically — a bare 'removed' also appears+ // elsewhere in the init summary for unrelated reasons.+ expect(output).not.toContain('machine-wide choice');+ expect(output).not.toContain('stay off for every project');expect(output).not.toContain('already installed at current version');});diff --git a/packages/cli/src/commands/init.ts b/packages/cli/src/commands/init.tsindex 98e13f39c..ff378deda 100644--- a/packages/cli/src/commands/init.ts+++ b/packages/cli/src/commands/init.ts@@ -56,7 +56,6 @@ import { CONFIG_FILENAME, OK_DIR } from '../constants.ts';import { formatPreviewBlock, type PreviewResult } from '../content/preview.ts';import { buildPiExtensionSource, makePiManagedFileEntry } from '../integrations/pi-extension.ts';import { resolveProjectRoot } from '../integrations/resolve-project-root.ts';-import { removeUserGlobalSkillBundle } from '../integrations/skill-teardown.ts';import {assertProjectPathSafe,type ProjectSkillResult,@@ -701,9 +700,10 @@ interface InitCommandOptions {installUserSkill?: (opts?: InstallUserSkillOptions) => Promise<InstallUserSkillResult>;/*** User-global skill opt-in. `undefined` (default) enables every bundle;- * `false` (`--no-skills`) declines all; a comma list (`--skills discovery`)- * enables only the named bundles. The decision is recorded so the desktop /- * CLI reclaim gates never re-install a declined bundle.+ * `false` (`--no-skills`) installs none; a comma list (`--skills discovery`)+ * enables only the named bundles. Only an ENABLED bundle records a decision+ * (`true`); a bundle left out of this run records nothing, so the reclaim+ * gates grandfather it to disk rather than treating it as declined.*/skills?: string | boolean;/** MCP scope: user-level only, project-level only, or both. */@@ -1812,9 +1812,22 @@ export async function runInit(options: InitCommandOptions = {}): Promise<InitCom// @inkeep/open-knowledge-server.// 4. Install the enabled user-global Agent Skills. Per-bundle opt-in- // (`--skills` / `--no-skills`); the decision is recorded so the desktop /- // CLI reclaim gates never re-install a declined bundle. Non-fatal — init- // exits 0 even on install failure; users see a warning + manual-install hint.+ // (`--skills` / `--no-skills`). Non-fatal — init exits 0 even on install+ // failure; users see a warning + manual-install hint.+ //+ // `--no-skills` is a PER-INVOCATION skip: it installs nothing and records+ // nothing. It deliberately does not write a decline, because these bundles+ // exist once per machine (`~/.agents/skills/<name>` + per-host copies) with+ // no per-project copy, so a decline from one project speaks for every other+ // one. `resolveBundleEnabled` grandfathers an unrecorded bundle to disk, so+ // recording nothing already gives the right answer on both sides: a fresh+ // machine stays uninstalled (`null ?? false`), and bundles another project+ // installed stay put (`null ?? true`).+ //+ // The durable machine-wide decline still exists and is deliberately NOT+ // written here — it is a CONSENT record, owned by the first-launch dialog and+ // the per-skill Settings toggle, where the consequence is stated at a moment+ // the user is choosing machine-wide.const installSkill = options.installUserSkill ?? installUserSkill;const skillHome = options.home ?? homedir();const enabledBundles = resolveInitSkillEnablement(options.skills);@@ -1824,24 +1837,18 @@ export async function runInit(options: InitCommandOptions = {}): Promise<InitComlet anySkipped = false;let anyNoHosts = false;for (const id of USER_GLOBAL_BUNDLE_IDS) {- const enabled = enabledBundles.has(id);- await writeBundleDecision(skillHome, BUNDLE_SKILL_NAME[id], enabled).catch(() => {});- if (enabled) {- anyEnabled = true;- // force: the loop shares the `cli-hosts` version key across bundles, so- // one bundle's version write must not satisfy another's skip-current gate.- const result = await installSkill({ home: options.home, bundleId: id, force: true });- if (result === 'installed') anyInstalled = true;- else if (result === 'failed') anyFailed = true;- else if (result === 'no-hosts') anyNoHosts = true;- else anySkipped = true;- } else {- try {- removeUserGlobalSkillBundle(skillHome, id);- } catch {- // Fail-soft — the decline is already recorded; teardown is best-effort.- }- }+ if (!enabledBundles.has(id)) continue; // not selected: install nothing, record nothing+ // Installing IS the affirmative act, so the opt-in is still recorded — it+ // materializes the grandfathered state every later sweep gates on.+ await writeBundleDecision(skillHome, BUNDLE_SKILL_NAME[id], true).catch(() => {});+ anyEnabled = true;+ // force: the loop shares the `cli-hosts` version key across bundles, so+ // one bundle's version write must not satisfy another's skip-current gate.+ const result = await installSkill({ home: options.home, bundleId: id, force: true });+ if (result === 'installed') anyInstalled = true;+ else if (result === 'failed') anyFailed = true;+ else if (result === 'no-hosts') anyNoHosts = true;+ else anySkipped = true;}// Honest summary: a failure (even partial) surfaces the manual-install hint;// declining every skill reports declined, not a false "already installed".@@ -2228,19 +2235,14 @@ export function formatInitResult(result: InitCommandResult, cwd: string): stringlines.push(` open-knowledge ${success('already installed at current version')}`);break;case 'declined':- // NOT "skipped": the decline is recorded against $HOME and the bundles- // are REMOVED from every user-global skill dir, so one `--no-skills` in- // a throwaway project turns them off for every project on the machine.- // Saying so is the whole mitigation — no confirmation prompt, because- // the flag is meant to be scriptable.- lines.push(` open-knowledge ${dim('opted out via --no-skills')}`);- lines.push(- ` ${dim('This is a machine-wide choice: the built-in skills are removed from your')}`,- );+ // Scoped to this run, and the copy says so. The previous wording+ // disclosed a machine-wide removal that the flag no longer performs;+ // leaving it would now describe the opposite of what happened.+ lines.push(` open-knowledge ${dim('skipped for this run (--no-skills)')}`);lines.push(- ` ${dim('user-global skill directories and stay off for every project until you')}`,+ ` ${dim('Nothing was installed or removed. Any built-in skills already on this')}`,);- lines.push(` ${dim('re-enable them by running init again without the flag:')}`);+ lines.push(` ${dim('machine are untouched. Run init without the flag to install them:')}`);lines.push(` ${dim(' ok init')}`);break;case 'no-hosts':diff --git a/packages/cli/src/integrations/skill-teardown.ts b/packages/cli/src/integrations/skill-teardown.tsindex a5cef835c..dc3f70842 100644--- a/packages/cli/src/integrations/skill-teardown.ts+++ b/packages/cli/src/integrations/skill-teardown.ts@@ -411,9 +411,10 @@ export function userGlobalSkillBundleTargets(homeInput: string): SkillBundleTarg/*** Remove ONE user-global bundle's directories (central + every per-host copy)- * from disk. Used by the opt-out paths (dialog decline, `ok init --no-skills`,+ * from disk. Used by the opt-out paths (dialog decline, the Settings toggle,* the reclaim/sweep gate) so an unchecked bundle actually leaves — the exact- * reverse of `installUserBundleToHostDirs`. Tolerant of already-absent dirs+ * reverse of `installUserBundleToHostDirs`. NOT `ok init --no-skills`: that+ * flag is a per-invocation skip and removes nothing. Tolerant of already-absent dirs* (`rmSync` with `force`). Only the specific `open-knowledge-*` dirs, never the* shared `~/.agents/skills` root.*/diff --git a/packages/core/src/skill-state/schema.ts b/packages/core/src/skill-state/schema.tsindex d2b41469e..8293131cb 100644--- a/packages/core/src/skill-state/schema.ts+++ b/packages/core/src/skill-state/schema.ts@@ -107,9 +107,12 @@ const TargetEntrySchema = z.looseObject({/*** Per-bundle opt-in decision. Keyed by a bundle's install NAME (e.g.* `open-knowledge-discovery`), NOT the install target. `enabled: false` is an- * explicit decline recorded via the first-launch consent dialog or `ok init- * --no-skills`; an absent key means "no recorded decision" (grandfather: the- * gate falls back to disk presence). Each leaf `.register()` BEFORE wrappers+ * explicit decline, written only where the user is choosing machine-wide: the+ * first-launch consent dialog and the per-skill Settings toggle. `ok init+ * --no-skills` does NOT write one — it is a per-invocation skip, and a decline+ * from one project would speak for every other project on the machine. An+ * absent key means "no recorded decision" (grandfather: the gate falls back to+ * disk presence). Each leaf `.register()` BEFORE wrappers* per the Zod v4 metadata-binding rule.*/const BundleDecisionEntrySchema = z.looseObject({