open-knowledge-skillsCAUTION

From the repository's own README, as read at the audited commit. Badges and raw HTML are left out.

/plugin marketplace add inkeep/open-knowledge-skills
/plugin install open-knowledge@open-knowledge-skills

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
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).

> **CLI name.** Commands below use Stable's `ok` (`open-knowledge`). OpenKnowledge
> Beta's terminal commands are `ok-beta` (`open-knowledge-beta`), with `~/.ok-beta/`
> in place of `~/.ok/`.

## 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/folder which was never `ok init`'d**. It opens in a throwaway session (a
temp project in the OS temp dir — your repo is never touched, no `.ok/` is
written into it) with the same live preview you get inside a project.

**Never run `ok init` just to view or open a file.** `ok init` turns a repo
into a shared OpenKnowledge project; it is not a prerequisite for opening one
file. Opening a file needs no project, no `.ok/`, and no server already
running — each path below boots the session itself.

When asked to open or preview such a file, **decide by the viewing surface you
actually have** — check the tool, not the host name. Only open a browser when
you genuinely have one; never pop a browser tab on a host that has none.

- **You have an in-app / built-in browser** (Claude Code Desktop's Browser pane, Cursor, Codex, and similar) — this
  is the default: call the **`preview_url` MCP tool** with `file` set to the
  absolute path (it finds, or boots on demand, the session and returns a full
  `url`), then **immediately open that `url` in your in-app browser**. "Open it"
  means navigate your browser — don't just print the URL and stop. This is also
  the only way to view it in a browser when the OK Desktop app is installed
  (`ok open` prefers the Desktop app). Get the URL from `preview_url` only —
  never hunt for it via `ok ps` / `ok status` / `ok start` or a guessed
  port.
- **No in-app browser** (a pure-stdio CLI) — run
  `ok open /abs/path/to/file.md`: it opens the Desktop app when installed, else a
  browser, and boots the session itself. Don't force a browser tab the user
  didn't ask for; `ok open` is the right default here. If `ok` isn't on PATH,
  `npx @inkeep/open-knowledge open /abs/path/to/file.md` does the same.

If the OK MCP server isn't wired into this host there is

CAUTIONgrade C · trust 79/100 Install with care. The audit found things worth knowing before you trust its output.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (2)

**Re-point at the end of a multi-doc workflow; don't claim a doc is on screen unless you put it there.** The one-shot attach (signal 3) opens the preview *once* — later writes do NOT move the pane; it

**Stale-session symptom.** If `edit` returns "Text not found" on text you can verify exists on disk (via `exec("cat ...")`), or `No document at` a path you can `cat` from the content root, the MCP ses

Gates applied: instruction_override, no_behavioural_pass.