open-knowledge

OpenKnowledge — agent guidance

OpenKnowledge (OK) is a markdown-CRDT collaboration platform exposed via MCP. This skill is the single source of OK agent guidance. Every rule below is a MUST unless marked otherwise. Depth lives in references/*.md — one level deep; load a reference when its task comes up.

Skill version tracks @inkeep/open-knowledge-server. cat ~/.ok/skill-state.yml shows what's installed. ok seed needs @inkeep/open-knowledge >= 0.4.0; if it errors unknown command, npm install -g @inkeep/open-knowledge.

Setup (not connected yet?). If the mcp__open-knowledge__* tools aren't available in your client, this project isn't wired up on this machine — see references/setup.md for the rung ladder (approve .mcp.json → ok start CLI → optional desktop app) and the canonical quickstart.

TL;DR — the 90% case

1. Reads: exec("cat …") for one doc, exec("ls -A …") for a directory (folder defaults + template menu), exec("grep …") for literal, search for ranked retrieval. Native Read / Grep only on source code (.ts / .py / …), never on in-scope .md / .mdx.
2. Writes: write({ document: { path, content } }) for a new or full-replace doc; edit({ document: { path, find, replace } }) for a body find/replace; edit({ document: { path, frontmatter } }) for a frontmatter merge-patch (null deletes a key). delete({ document }) removes, move({ from, to }) moves/renames. Body find/replace is body-only. Pass a one-line summary (≤80 chars, user-facing outcome) on every content write.
3. Preview / open a doc — determine your ONE surface FIRST (once per session). Before opening anything, pick where to focus, stop at first match: OK_DESKTOP_TERMINAL set (check your env — echo "$OK_DESKTOP_TERMINAL") → OK Desktop's own terminal → ok open <name> (switches this window) · have preview_* → Codex Desktop pane · have a URL-navigation/browser tool → Cursor/Codex → preview_url then navigate it · else plain CLI → ok open <name>. ok open <name> opens a doc or folder (auto-detected — no --folder); add --skill <name> for a skill. The previewUrl field is a route id, not your open mechanism — don't hand it to a browser just because you saw it. Don't preview_screenshot to confirm edits. Full Step-0 procedure + per-surface how-to: references/preview.md.
4. Workflow guides: workflow({ kind: 'ingest' | 'research' | 'consolidate' | 'discover' }) returns a procedural guide, not data. Use it when the work fits the layer.
5. Direct questions: a plain business question ("which customers…", "what did we decide about…") routes to search / exec + a cited chat answer — no "research" keyword needed. Persist only when durable + multi-doc + not already covered, and offer first. See references/corpus-qa.md.
6. Authoring or improving a skill ("write/make a skill", "improve this skill", "turn this into a skill"): STOP and invoke the open-knowledge-write-skill skill — it owns scope choice (project vs global), the SKILL.md contract, evaluation, and install; don't improvise from this skill. Author through the skill target (write({ skill })), never a raw .ok/skills/… document. Never read, diff, or edit the installed projections under .Codex/skills/ · .cursor/skills/ · .codex/skills/ · .opencode/skills/ · .pi/skills/ · .agents/skills/ — install generates them and overwrites them on the next sync; they are NOT source of truth.