open-knowledge-discovery

The saved excerpt is a snapshot from when this skill was listed. The external source remains the complete and most current version.

---
name: open-knowledge-discovery
description: "Read when the user asks what OpenKnowledge is, wants to install it on a repository, wants to open or preview a single markdown file that is not part of an OpenKnowledge project, wants to share an OpenKnowledge project with collaborators, asks whether OpenKnowledge supports a particular capability, or asks how `ok init` / `ok cowork` / OK Desktop set up a project. Do NOT load to perform OpenKnowledge reads/writes — the runtime guidance for editing markdown inside an initialized OK project ships as a separate project-local skill installed into each detected agent's skills dir (for example `.claude/skills/open-knowledge/`) whenever `ok init` runs."
compatibility: "Any agent host — no MCP server required. Pure discovery + install guidance."
metadata:
  author: "Inkeep"
  repository: "https://github.com/inkeep/open-knowledge-skills"
---
# OpenKnowledge — what it is and how to install it

OpenKnowledge (OK) is a markdown-CRDT collaboration platform. It turns a
directory of `.md` / `.mdx` files into a live, multi-writer knowledge base:
agents and humans edit the same documents in real time, every change is
attributed, and a browser preview renders edits as they land.

This skill covers **discovery, install, and opening OpenKnowledge files** —
including single files that are not part of a project (see *Opening a file
outside a project* below). It does **not** carry the in-project read/write
runtime contract (the STOP rules for native file tools, the grounding and
linking rules, the MCP routing table) — that ships separately as the
project-local skill installed by `ok init` (see *Working inside a project*
below).

## Install OpenKnowledge on a repository

Run `ok init` from the repository root:

```bash
npx @inkeep/open-knowledge init
# or, after a global install:
npm install -g @inkeep/open-knowledge
ok init
```

`ok init` is the one setup verb. It:

- scaffolds a `.ok/` directory (project config — `content.dir` defaults to `.`);
- wires the OpenKnowledge MCP server into the coding agents it detects on this
  machine — skip with `--no-mcp`;
- installs the **project-local runtime skill** into each detected agent's
  skills dir (`<agent-dir>/skills/open-knowledge/`) so agents working in this
  repo get the full read/write contract. OK only writes into agent
  directories that already exist — it never creates one, so nothing appears
  for agents you don't use, and `ok init` says so when it finds none;
- ensures the project has a `.git/`.

Re-run `ok init` any time to refresh wiring and skills to the installed CLI
version.

## Share an OpenKnowledge project with collaborators

An OK project travels with its repository. To share one:

1. Commit the `.ok/` directory and whichever project-local
   `<agent-dir>/skills/open-knowledge/` directories `ok init` created, along
   with your `.md` content.
2. Collaborators clone the repo and run `ok init` once — that registers the
   MCP server on their machine and refreshes the project skill.
3. Start the editor + preview with `ok start` (or open the project in OK
   Desktop).

Collaboration is real-time once two writers have the project open against the
same content directory.

## `ok cowork` — Claude Chat & Cowork

`ok init`'s editor wiring does not reach Claude Chat or Cowork — those read a
separate Skills list inside the Claude Desktop App. Run `ok cowork` to
build `openknowledge.skill` and open Claude Desktop so the user can upload it
(Customize → Skills → + → Create skill → Upload skill).

## OK Desktop

OK Desktop is the standalone macOS app (`@inkeep/open-knowledge-desktop`). It
bundles its own CLI, opens a project as an editor + preview window, and keeps
the project's MCP wiring and skills current on every launch. Download DMGs
from the releases page.

## Opening a file outside a project

OpenKnowledge can open a single markdown file that is **not** part of an OK
project — a loose `.md` / `.mdx`, **or a file that lives inside a regular
repo/f