Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

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.md
new file mode 100644
index 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.mdx
index 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.ts
index 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.ts
index 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<InitCom
let 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): string
lines.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.ts
index 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.ts
index 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({