discovery

Name: discovery
Author: inkeep

3.1kstars191forks

How to install discovery?

inkeep/open-knowledge/discovery

$npx -y skills add inkeep/open-knowledge --skill discovery

Installs into the current project.

Summary

Read when the user asks what OpenKnowledge is, wants to install it on a repository, wants to share an OpenKnowledge project with collaborators, or asks how ok init / ok cowork / OK Desktop set up a project. Do NOT load to perform OpenKnowledge reads/writes — the runtime guida

Files · 1

View on GitHub

SKILL.md

1	# OpenKnowledge — what it is and how to install it
2
3	OpenKnowledge (OK) is a markdown-CRDT collaboration platform. It turns a
4	directory of `.md` / `.mdx` files into a live, multi-writer knowledge base:
5	agents and humans edit the same documents in real time, every change is
6	attributed, and a browser preview renders edits as they land.
7
8	This skill covers discovery, install, and opening OpenKnowledge files —
9	including single files that are not part of a project (see *Opening a file
10	outside a project* below). It does not carry the in-project read/write
11	runtime contract (the STOP rules for native file tools, the grounding and
12	linking rules, the MCP routing table) — that ships separately as the
13	project-local skill installed by `ok init` (see Working inside a project
14	below).
15
16	## Install OpenKnowledge on a repository
17
18	Run `ok init` from the repository root:
19
20	```bash
21	npx @inkeep/open-knowledge init
22	# or, after a global install:
23	npm install -g @inkeep/open-knowledge
24	ok init
25	```
26
27	`ok init` is the one setup verb. It:
28
29	- scaffolds a `.ok/` directory (project config — `content.dir` defaults to `.`);
30	- wires the OpenKnowledge MCP server into detected editors (Claude Code,
31	Cursor, Codex) — skip with `--no-mcp`;
32	- installs the project-local runtime skill at `.claude/skills/open-knowledge/`
33	and `.cursor/skills/open-knowledge/` so agents working in this repo get the
34	full read/write contract;
35	- ensures the project has a `.git/`.
36
37	Re-run `ok init` any time to refresh wiring and skills to the installed CLI
38	version.
39
40	## Share an OpenKnowledge project with collaborators
41
42	An OK project travels with its repository. To share one:
43
44	1. Commit the `.ok/` directory and the project-local
45	`.claude/skills/open-knowledge/` (and `.cursor/skills/open-knowledge/`)
46	directories along with your `.md` content.
47	2. Collaborators clone the repo and run `ok init` once — that registers the
48	MCP server on their machine and refreshes the project skill.
49	3. Start the editor + preview with `ok start` (or open the project in OK
50	Desktop).
51
52	Collaboration is real-time once two writers have the project open against the
53	same content directory.
54
55	## `ok cowork` — Claude Chat & Cowork
56
57	`ok init`'s editor wiring does not reach Claude Chat or Cowork — those read a
58	separate Skills list inside the Claude Desktop App. Run `ok cowork` to
59	build `openknowledge.skill` and open Claude Desktop so the user can upload it
60	(Customize → Skills → + → Create skill → Upload skill).
61
62	## OK Desktop
63
64	OK Desktop is the standalone macOS app (`@inkeep/open-knowledge-desktop`). It
65	bundles its own CLI, opens a project as an editor + preview window, and keeps
66	the project's MCP wiring and skills current on every launch. Download DMGs
67	from the releases page.
68
69	## Opening a file outside a project
70
71	OpenKnowledge can open a single markdown file that is not part of an OK
72	project — a loose `.md` / `.mdx`, **or a file that lives inside a regular
73	repo/folder which was never `ok init`'d**. It opens in a throwaway session (a
74	temp project in the OS temp dir — your repo is never touched, no `.ok/` is
75	written into it) with the same live preview you get inside a project.
76
77	Never run `ok init` just to view or open a file. `ok init` turns a repo
78	into a shared OpenKnowledge project; it is not a prerequisite for opening one
79	file. Opening a file needs no project, no `.ok/`, and no server already
80	running — each path below boots the session itself.
81
82	When asked to open or preview such a file, **decide by the viewing surface you
83	actually have** — check the tool, not the host name. Only open a browser when
84	you genuinely have one; never pop a browser tab on a host that has none.
85
86	- You have an in-app / built-in browser (Claude Code Desktop's Browser pane, Cursor, Codex, and similar) — this
87	is the default: call the `preview_url` MCP tool with `file` set to the
88	absolute path (it finds, or boots on demand, the session and returns a full
89	`url`), then immediately open that `url` in your in-app browser. "Open it"
90	means navigate your browser — don't just print the URL and stop. This is also
91	the only way to view it in a br

People who liked this also viewed

6 picks

Type

discovery

3.1kstars191forks

View on GitHub

How to install discovery?

inkeep/open-knowledge/discovery

$npx -y skills add inkeep/open-knowledge --skill discovery

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# OpenKnowledge — what it is and how to install it
2
3	OpenKnowledge (OK) is a markdown-CRDT collaboration platform. It turns a
4	directory of `.md` / `.mdx` files into a live, multi-writer knowledge base:
5	agents and humans edit the same documents in real time, every change is
6	attributed, and a browser preview renders edits as they land.
7
8	This skill covers discovery, install, and opening OpenKnowledge files —
9	including single files that are not part of a project (see *Opening a file
10	outside a project* below). It does not carry the in-project read/write
11	runtime contract (the STOP rules for native file tools, the grounding and
12	linking rules, the MCP routing table) — that ships separately as the
13	project-local skill installed by `ok init` (see Working inside a project
14	below).
15
16	## Install OpenKnowledge on a repository
17
18	Run `ok init` from the repository root:
19
20	```bash
21	npx @inkeep/open-knowledge init
22	# or, after a global install:
23	npm install -g @inkeep/open-knowledge
24	ok init
25	```
26
27	`ok init` is the one setup verb. It:
28
29	- scaffolds a `.ok/` directory (project config — `content.dir` defaults to `.`);
30	- wires the OpenKnowledge MCP server into detected editors (Claude Code,
31	Cursor, Codex) — skip with `--no-mcp`;
32	- installs the project-local runtime skill at `.claude/skills/open-knowledge/`
33	and `.cursor/skills/open-knowledge/` so agents working in this repo get the
34	full read/write contract;
35	- ensures the project has a `.git/`.
36
37	Re-run `ok init` any time to refresh wiring and skills to the installed CLI
38	version.
39
40	## Share an OpenKnowledge project with collaborators
41
42	An OK project travels with its repository. To share one:
43
44	1. Commit the `.ok/` directory and the project-local
45	`.claude/skills/open-knowledge/` (and `.cursor/skills/open-knowledge/`)
46	directories along with your `.md` content.
47	2. Collaborators clone the repo and run `ok init` once — that registers the
48	MCP server on their machine and refreshes the project skill.
49	3. Start the editor + preview with `ok start` (or open the project in OK
50	Desktop).
51
52	Collaboration is real-time once two writers have the project open against the
53	same content directory.
54
55	## `ok cowork` — Claude Chat & Cowork
56
57	`ok init`'s editor wiring does not reach Claude Chat or Cowork — those read a
58	separate Skills list inside the Claude Desktop App. Run `ok cowork` to
59	build `openknowledge.skill` and open Claude Desktop so the user can upload it
60	(Customize → Skills → + → Create skill → Upload skill).
61
62	## OK Desktop
63
64	OK Desktop is the standalone macOS app (`@inkeep/open-knowledge-desktop`). It
65	bundles its own CLI, opens a project as an editor + preview window, and keeps
66	the project's MCP wiring and skills current on every launch. Download DMGs
67	from the releases page.
68
69	## Opening a file outside a project
70
71	OpenKnowledge can open a single markdown file that is not part of an OK
72	project — a loose `.md` / `.mdx`, **or a file that lives inside a regular
73	repo/folder which was never `ok init`'d**. It opens in a throwaway session (a
74	temp project in the OS temp dir — your repo is never touched, no `.ok/` is
75	written into it) with the same live preview you get inside a project.
76
77	Never run `ok init` just to view or open a file. `ok init` turns a repo
78	into a shared OpenKnowledge project; it is not a prerequisite for opening one
79	file. Opening a file needs no project, no `.ok/`, and no server already
80	running — each path below boots the session itself.
81
82	When asked to open or preview such a file, **decide by the viewing surface you
83	actually have** — check the tool, not the host name. Only open a browser when
84	you genuinely have one; never pop a browser tab on a host that has none.
85
86	- You have an in-app / built-in browser (Claude Code Desktop's Browser pane, Cursor, Codex, and similar) — this
87	is the default: call the `preview_url` MCP tool with `file` set to the
88	absolute path (it finds, or boots on demand, the session and returns a full
89	`url`), then immediately open that `url` in your in-app browser. "Open it"
90	means navigate your browser — don't just print the URL and stop. This is also
91	the only way to view it in a br

People who liked this also viewed

6 picks

Type