Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

Name user-global skills correctly in ok init summary (PRD-8958) (#5794)

Andrew Mikofalvy01a32862cd24
diff --git a/.changeset/init-user-global-skill-summary.md b/.changeset/init-user-global-skill-summary.md
new file mode 100644
index 000000000..bd7f03238
--- /dev/null
+++ b/.changeset/init-user-global-skill-summary.md
@@ -0,0 +1,5 @@
+---
+"@inkeep/open-knowledge": patch
+---
+
+`ok init` now names each user-global skill correctly in its summary and shows how to add starter content even with `--no-mcp`.
diff --git a/docs/content/features/skills/reference.mdx b/docs/content/features/skills/reference.mdx
index ecb60fc08..1c87bfe1f 100644
--- a/docs/content/features/skills/reference.mdx
+++ b/docs/content/features/skills/reference.mdx
@@ -49,7 +49,7 @@ ok init --no-skills
| `ok skills import <source>` | Import from skills.sh, a repository, a git URL, or a local path. |
| `ok seed --pack <id>` | Install a starter pack's skills. |
| `ok init --skills discovery,write-skill` | Select built-ins during setup; the default is discovery. |
-| `ok init --no-skills` | Skip skill installation for this setup run. |
+| `ok init --no-skills` | Skip the user-global skills for this setup run; the project-local `open-knowledge` skill is still written. |
See the [CLI reference](../../reference/cli.mdx) for all flags.
diff --git a/docs/content/reference/cli.mdx b/docs/content/reference/cli.mdx
index 8b3345b8a..43ae1c46c 100644
--- a/docs/content/reference/cli.mdx
+++ b/docs/content/reference/cli.mdx
@@ -52,6 +52,8 @@ One server on one port serves everything — the editor, the API, the MCP endpoi
`ok start` also takes `-p/--port` and `--bind` to pick the address, `--idle-shutdown` (`off` or a duration like `30m`) to control when an unused server exits, `--only server` to run without the editor UI, and `--mode app` to hand off to the desktop app instead of running a server in the terminal (with the desktop app installed).
+The browser needs no flag: `ok start` always runs the browser server unless you pass `--mode app`. Bare `ok`, with no subcommand, opens the desktop app when it is installed and otherwise runs the same browser server; it also runs the browser server when its output is not an interactive terminal, over SSH, or on Linux without `DISPLAY` or `WAYLAND_DISPLAY`, unless `OK_FORCE_DESKTOP=1` is set. Set `OK_FORCE_BROWSER=1` to make bare `ok` always run the browser server.
+
Idle shutdown is on by default at 30 minutes — a server with no connected clients exits so it doesn't linger. If you keep a session open for a long time without interacting, pass `--idle-shutdown off` (or a longer duration) to keep it running.
For a complete list of every file OpenKnowledge creates or changes — during install, at runtime, and in the desktop app — see [What OpenKnowledge writes to your system](/docs/reference/what-open-knowledge-writes).
diff --git a/docs/content/reference/configuration.mdx b/docs/content/reference/configuration.mdx
index 16d9ba5cf..8f182fc46 100644
--- a/docs/content/reference/configuration.mdx
+++ b/docs/content/reference/configuration.mdx
@@ -119,6 +119,8 @@ Most users never set these — the schema settings above cover the common cases.
| `HOST` | Server bind host. The `--bind` flag wins over this. |
| `PORT` | Server bind port. The `--port` flag wins over this. |
| `OK_MCP_AUTOSTART` | Set to `0` to stop MCP tool calls from auto-starting the project's OpenKnowledge server; tools error until you run `ok start` |
+| `OK_FORCE_BROWSER` | Set to `1` so bare `ok` runs the browser server instead of opening the installed desktop app. `ok start` without `--mode app` runs the browser server either way, and `ok start --mode app` refuses to run while it is set. |
+| `OK_FORCE_DESKTOP` | Set to `1` so bare `ok` and `ok start --mode app` open the installed desktop app even when output is not an interactive terminal, over SSH, or on Linux without a display. `OK_FORCE_BROWSER=1` takes precedence. |
| `OK_LOG_LEVEL` | Log verbosity (`info`, `debug`, `trace`). Falls back to `LOG_LEVEL` if unset. |
**Advanced / operator:**
diff --git a/docs/content/reference/what-open-knowledge-writes.mdx b/docs/content/reference/what-open-knowledge-writes.mdx
index cacf1817a..835dbe1a3 100644
--- a/docs/content/reference/what-open-knowledge-writes.mdx
+++ b/docs/content/reference/what-open-knowledge-writes.mdx
@@ -273,9 +273,9 @@ On Windows, Claude Desktop and OpenCode configs live under `%APPDATA%\Claude\` a
`ok init` also installs `open-knowledge-discovery` (the same skill first launch sets up — pass `--skills discovery,write-skill` to add the authoring skill too), honoring any prior consent choice, and, for a project it is setting up for the first time, adds the OpenKnowledge paths to `.git/info/exclude` so `.ok/` stays off your remote. Pass `--shared` to commit it instead. Re-running `ok init` on a project you already set up keeps that project's current choice. Switch modes later with `ok config-sharing share` / `unshare` (`unshare` refuses if an OK config file is already tracked); `ok config-sharing status` prints the current mode and the excluded paths.
<Callout type="info" title="Controlling it">
- - `--no-mcp` — scaffold `.ok/` only; register nothing with any editor.
+ - `--no-mcp` — register nothing in any editor's MCP config. `ok init` still scaffolds `.ok/` and writes the project-local `open-knowledge` skill; GitHub Copilot's copy is written only when Copilot already has an OpenKnowledge MCP entry.
- `--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 on this run; `--skills discovery,write-skill` — install only the named bundles. **Default installs `discovery` only**, matching what the desktop's first launch sets up; `write-skill` is opt-in here and in **Settings → Skills Studio**. Installing is recorded and honored by the desktop app too; skipping is not recorded, so it never affects another project.
+ - `--no-skills` — install no user-global skills on this run; `--skills discovery,write-skill` — install only the named bundles. **Default installs `discovery` only**, matching what the desktop's first launch sets up; `write-skill` is opt-in here and in **Settings → Skills Studio**. Installing is recorded and honored by the desktop app too; skipping is not recorded, so it never affects another project. Neither flag affects the project-local `open-knowledge` skill, which is still written.
- `--shared` (vs `--local-only`) — commit `.ok/` rather than keeping it out of git.
</Callout>
@@ -383,6 +383,8 @@ Bridge setup requires a project directory it can resolve and access, and refuses
| The `postinstall` skill install (CLI) | `npm install --ignore-scripts` |
| The shell-config `PATH` block (macOS and Linux app) | Uncheck "Add the `ok` command to your terminal" in the first-launch dialog |
| All editor MCP registration in `ok init` | `ok init --no-mcp` |
+| User-global skills in `ok init` | `ok init --no-skills` |
+| The project-local `open-knowledge` skill | Not skippable at `ok init`, even with `--no-mcp` or `--no-skills`; `ok deinit` removes it |
| User-level (vs project) MCP writes | `ok init --scope project` |
| Committing `.ok/` to git | Off by default for a new project; `ok init --shared` commits it instead |
| The repair sweeps and the desktop app's shell / `PATH` changes | `OK_RECLAIM_DISABLE=1` (also delete the managed block from your shell config to remove the `PATH` entry) |
diff --git a/docs/content/remote-control/methods/docker.mdx b/docs/content/remote-control/methods/docker.mdx
index 55b972225..c75095b1d 100644
--- a/docs/content/remote-control/methods/docker.mdx
+++ b/docs/content/remote-control/methods/docker.mdx
@@ -54,7 +54,7 @@ ENTRYPOINT ["/usr/local/bin/entrypoint.sh"]
The entrypoint is the container's boot script. It runs every time the container starts. `ok start` needs an initialized project, but no one is inside the container to run `ok init`. The script handles this automatically. The first boot initializes the project on the empty volume. Later boots find `.ok/` and start the server directly. Official database images use the same pattern for empty data directories.
-The `--no-mcp --no-skills` flags only skip local agent configuration and skill files that the container does not need. The server still provides its `/mcp` endpoint.
+The `--no-mcp --no-skills` flags skip the editor MCP registration and the user-global skills, which the container does not need. `ok init` still writes the project-local `open-knowledge` skill, and the server still provides its `/mcp` endpoint.
```sh title="entrypoint.sh"
#!/bin/sh
diff --git a/packages/cli/src/commands/init.test.ts b/packages/cli/src/commands/init.test.ts
index 2e1b33bcd..b23bff588 100644
--- a/packages/cli/src/commands/init.test.ts
+++ b/packages/cli/src/commands/init.test.ts
@@ -955,7 +955,8 @@ describe('runInit', () => {
});
expect(result.skillInstall).toBe('installed');
const output = formatInitResult(result, testDir);
- expect(output).toContain('User-global skill:');
+ expect(output).toContain('User-global skills:');
+ expect(output).toContain('open-knowledge-discovery');
expect(output).toContain('installed for');
expect(output).not.toContain('detected agent hosts');
});
@@ -985,7 +986,7 @@ describe('runInit', () => {
});
expect(result.skillInstall).toBe('skip-current');
const output = formatInitResult(result, testDir);
- expect(output).toContain('User-global skill:');
+ expect(output).toContain('User-global skills:');
expect(output).toContain('already installed at current version');
});
@@ -1109,6 +1110,70 @@ describe('runInit', () => {
const output = formatInitResult(result, testDir);
expect(output).toContain('install failed');
});
+
+ const userGlobalSection = (output: string): string => {
+ const start = output.indexOf('User-global skills:');
+ expect(start).toBeGreaterThanOrEqual(0);
+ const rest = output.slice(start);
+ const end = rest.indexOf('\n\n');
+ return end === -1 ? rest : rest.slice(0, end);
+ };
+
+ it('--no-skills never names the project skill as the user-global skill it skipped', async () => {
+ const result = await runInitForTest({
+ skills: false,
+ editors: ['cursor'],
+ installUserSkill: async () => 'installed',
+ });
+ const output = formatInitResult(result, testDir);
+ expect(output).toContain('.cursor/skills/open-knowledge/SKILL.md');
+ const section = userGlobalSection(output);
+ expect(section).toContain('--no-skills');
+ expect(section).not.toMatch(/\bopen-knowledge\b(?!-)/);
+ expect(section).toContain('project-local');
+ });
+
+ it('an unrecognized --skills id is reported as such, not as --no-skills', async () => {
+ const result = await runInitForTest({
+ skills: 'discovry',
+ installUserSkill: async () => 'installed',
+ });
+ expect(result.skillInstall).toBe('declined');
+ const section = userGlobalSection(formatInitResult(result, testDir));
+ expect(section).not.toContain('--no-skills');
+ expect(section).toContain('discovry');
+ expect(section).toContain('discovery, write-skill');
+ });
+
+ it('reports each bundle by its own name and outcome when outcomes differ', async () => {
+ const result = await runInitForTest({
+ skills: 'discovery,write-skill',
+ installUserSkill: async (opts) =>
+ opts?.bundleId === 'discovery' ? 'skip-current' : 'installed',
+ });
+ const section = userGlobalSection(formatInitResult(result, testDir));
+ const lines = section.split('\n');
+ const discovery = lines.find((l) => l.includes('open-knowledge-discovery'));
+ const writeSkill = lines.find((l) => l.includes('open-knowledge-write-skill'));
+ expect(discovery).toContain('already installed at current version');
+ expect(discovery).not.toContain('installed for');
+ expect(writeSkill).toContain('installed for');
+ expect(discovery?.indexOf('already installed')).toBe(writeSkill?.indexOf('installed for'));
+ expect(section).not.toMatch(/\bopen-knowledge\b(?!-)/);
+ });
+
+ it('names only the failing bundle as failed', async () => {
+ const result = await runInitForTest({
+ skills: 'discovery,write-skill',
+ installUserSkill: async (opts) =>
+ opts?.bundleId === 'write-skill' ? 'failed' : 'installed',
+ });
+ const lines = userGlobalSection(formatInitResult(result, testDir)).split('\n');
+ expect(lines.find((l) => l.includes('open-knowledge-discovery'))).not.toContain('failed');
+ expect(lines.find((l) => l.includes('open-knowledge-write-skill'))).toContain(
+ 'install failed',
+ );
+ });
});
describe('content preview in init output', () => {
@@ -1568,6 +1633,34 @@ describe('runInit', () => {
expect(matches).toHaveLength(1);
});
+ it('--no-mcp still shows how to add starter content, without the editor steps', async () => {
+ const result = await runInitForTest({ mcp: false });
+ const output = formatInitResult(result, testDir);
+ expect(output).toContain('ok seed --list-packs');
+ expect(output).toContain('scaffold an empty repo');
+ expect(output).not.toContain('Open your editor');
+ expect(output).not.toContain('Approve the MCP server');
+ });
+
+ it('does not suggest ok seed when content scaffolding failed', async () => {
+ writeFileSync(join(testDir, '.ok'), 'not a directory\n', 'utf-8');
+ const result = await runInitForTest({ editors: ['claude'] });
+ expect(result.contentScaffoldFailed).toBe(true);
+ const output = formatInitResult(result, testDir);
+ expect(output).toContain('Content scaffolding failed');
+ expect(output).not.toContain('ok seed');
+ expect(output).not.toMatch(/\n\n$/);
+ });
+
+ it('keeps the editor next steps when content scaffolding failed', async () => {
+ const result = await runInitForTest({ editors: ['claude'] });
+ const output = formatInitResult({ ...result, contentScaffoldFailed: true }, testDir);
+ expect(output).toContain('Open your editor');
+ expect(output).toContain('Approve the MCP server');
+ expect(output).toContain(' 3. Ask your agent');
+ expect(output).not.toContain('ok seed');
+ });
+
const allocOutsideTestDir = (suffix: string): string =>
resolve(
tmpdir(),
diff --git a/packages/cli/src/commands/init.ts b/packages/cli/src/commands/init.ts
index 64e10e297..b3d640673 100644
--- a/packages/cli/src/commands/init.ts
+++ b/packages/cli/src/commands/init.ts
@@ -649,6 +649,8 @@ interface InitCommandResult {
legacyProjectConfigs: ProjectConfigResult[];
projectSkills: ProjectSkillResult[];
skillInstall?: InstallUserSkillResult | 'declined';
+ skillBundles?: readonly { bundleId: BundleId; result: InstallUserSkillResult }[];
+ skillsRequested?: string | boolean;
skillHosts?: readonly string[];
preview?: PreviewResult;
didGitInit: boolean;
@@ -1319,11 +1321,13 @@ export async function runInit(options: InitCommandOptions = {}): Promise<InitCom
let anyFailed = false;
let anySkipped = false;
let anyNoHosts = false;
+ const skillBundles: { bundleId: BundleId; result: InstallUserSkillResult }[] = [];
for (const id of USER_GLOBAL_BUNDLE_IDS) {
if (!enabledBundles.has(id)) continue;
await writeBundleDecision(skillHome, BUNDLE_SKILL_NAME[id], true).catch(() => {});
anyEnabled = true;
const result = await installSkill({ home: options.home, bundleId: id, force: true });
+ skillBundles.push({ bundleId: id, result });
if (result === 'installed') anyInstalled = true;
else if (result === 'failed') anyFailed = true;
else if (result === 'no-hosts') anyNoHosts = true;
@@ -1369,6 +1373,8 @@ export async function runInit(options: InitCommandOptions = {}): Promise<InitCom
projectSkills: projectSkillResults,
legacyProjectConfigs,
skillInstall,
+ skillBundles,
+ skillsRequested: options.skills,
skillHosts,
didGitInit: gitResult.didInit,
rootGitignoreCreated,
@@ -1655,44 +1661,63 @@ export function formatInitResult(result: InitCommandResult, cwd: string): string
);
}
- if (result.skillInstall) {
+ if (result.skillInstall === 'declined') {
lines.push('');
- lines.push(accent('User-global skill:'));
- switch (result.skillInstall) {
- case 'installed': {
- const hostLabels = (result.skillHosts ?? []).map(
- (id) => EDITOR_LABELS[id as EditorId] ?? id,
- );
- const target = hostLabels.length > 0 ? hostLabels.join(', ') : 'the shared ~/.agents store';
- lines.push(` open-knowledge ${success(`installed for ${target}`)}`);
- lines.push(
- ` ${dim('Counted on skills.sh (skill name + source repo, once per machine).')}`,
- );
- lines.push(` ${dim('Opt out: DO_NOT_TRACK=1, or Settings → User → Preferences.')}`);
- break;
+ lines.push(accent('User-global skills:'));
+ if (typeof result.skillsRequested === 'string') {
+ lines.push(
+ ` ${dim(`none installed — --skills "${result.skillsRequested}" names no known skill bundle (known: ${USER_GLOBAL_BUNDLE_IDS.join(', ')})`)}`,
+ );
+ lines.push(` ${dim('No user-global skill was installed or removed.')}`);
+ } else {
+ lines.push(` ${dim('none installed — skipped for this run (--no-skills)')}`);
+ lines.push(` ${dim('No user-global skill was installed or removed; any already on this')}`);
+ lines.push(` ${dim('machine are untouched. Run init without the flag to install them:')}`);
+ lines.push(` ${dim(' ok init')}`);
+ lines.push(
+ ` ${dim('--no-skills covers user-global skills only, not project-local skills.')}`,
+ );
+ }
+ } else if (result.skillInstall) {
+ lines.push('');
+ lines.push(accent('User-global skills:'));
+ const bundles = result.skillBundles ?? [];
+ const nameWidth = Math.max(0, ...bundles.map((b) => BUNDLE_SKILL_NAME[b.bundleId].length));
+ for (const bundle of bundles) {
+ const name = BUNDLE_SKILL_NAME[bundle.bundleId].padEnd(nameWidth);
+ switch (bundle.result) {
+ case 'installed': {
+ const hostLabels = (result.skillHosts ?? []).map(
+ (id) => EDITOR_LABELS[id as EditorId] ?? id,
+ );
+ const target =
+ hostLabels.length > 0 ? hostLabels.join(', ') : 'the shared ~/.agents store';
+ lines.push(` ${name} ${success(`installed for ${target}`)}`);
+ break;
+ }
+ case 'skip-current':
+ lines.push(` ${name} ${success('already installed at current version')}`);
+ break;
+ case 'no-hosts':
+ lines.push(
+ ` ${name} ${dim('skipped — no supported agent host detected in your home directory')}`,
+ );
+ break;
+ case 'failed':
+ lines.push(` ${warning(`${name} install failed`)}`);
+ break;
+ default: {
+ const _exhaustive: never = bundle.result;
+ void _exhaustive;
+ }
}
- case 'skip-current':
- lines.push(` open-knowledge ${success('already installed at current version')}`);
- break;
- case 'declined':
- lines.push(` open-knowledge ${dim('skipped for this run (--no-skills)')}`);
- lines.push(
- ` ${dim('Nothing was installed or removed. Any built-in skills already on this')}`,
- );
- lines.push(` ${dim('machine are untouched. Run init without the flag to install them:')}`);
- lines.push(` ${dim(' ok init')}`);
- break;
- case 'no-hosts':
- lines.push(
- ` open-knowledge ${dim('skipped — no supported agent host detected in your home directory')}`,
- );
- break;
- case 'failed':
- lines.push(
- ` ${warning('open-knowledge install failed — MCP still configured; retry with:')}`,
- );
- lines.push(` ${warning(' ok repair-skills')}`);
- break;
+ }
+ if (bundles.some((b) => b.result === 'installed')) {
+ lines.push(` ${dim('Counted on skills.sh (skill name + source repo, once per machine).')}`);
+ lines.push(` ${dim('Opt out: DO_NOT_TRACK=1, or Settings → User → Preferences.')}`);
+ }
+ if (bundles.some((b) => b.result === 'failed')) {
+ lines.push(` ${warning('Retry with: ok repair-skills')}`);
}
}
@@ -1743,6 +1768,10 @@ export function formatInitResult(result: InitCommandResult, cwd: string): string
lines.push('');
lines.push(...formatSharingOutcome(result.sharing, cwd));
+ const seedLines = (indent: string): string[] => [
+ `${indent}- ${info('ok seed --list-packs')} — browse the starter packs`,
+ `${indent}- ${info('ok seed')} — scaffold an empty repo`,
+ ];
if (anyWritten) {
const seen = new Set<EditorId>();
const configuredLabels = result.editors
@@ -1754,11 +1783,21 @@ export function formatInitResult(result: InitCommandResult, cwd: string): string
lines.push(`${success('✓')} ${accent('Next steps:')}`);
lines.push(` 1. Open your editor (${info(configuredLabels.join(' / '))})`);
lines.push(' 2. Approve the MCP server when prompted');
- lines.push(' 3. (Optional) scaffold the starter knowledge-base structure:');
- lines.push(` - ${info('ok seed --list-packs')} — browse the starter packs`);
- lines.push(` - ${info('ok seed')} — scaffold an empty repo`);
- lines.push(' 4. Ask your agent to capture a source, research a topic, or build a wiki —');
+ let step = 3;
+ if (!result.contentScaffoldFailed) {
+ lines.push(` ${step++}. (Optional) scaffold the starter knowledge-base structure:`);
+ lines.push(...seedLines(' '));
+ }
+ lines.push(
+ ` ${step}. Ask your agent to capture a source, research a topic, or build a wiki —`,
+ );
lines.push(' the procedures ship as skills alongside the MCP tools.');
+ } else if (!result.contentScaffoldFailed) {
+ lines.push('');
+ lines.push(
+ `${accent('Next steps:')} (optional) scaffold the starter knowledge-base structure:`,
+ );
+ lines.push(...seedLines(' '));
}
return lines.join('\n');