Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
AI & knowledge

Open Knowledge

Beautiful, AI-native markdown editor and LLM Wiki

inkeep · AI review on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

npx skills add inkeep/open-knowledge

About this skill


name: open-knowledge description: "Authoritative agent-runtime contract for working inside an OpenKnowledge project — a markdown-CRDT knowledge base exposed over MCP. Use whenever reading, listing, searching, editing, or linting any .md or .mdx file in the project, and before any mcp__open-knowledge__* tool call (exec, search, write, edit, lint, and the rest). Installed by ok init, so its presence means this is an OpenKnowledge project and it governs every markdown file here. Covers the read/write tool surface, grounding and linking rules, folder/template conventions, the live browser preview, and the rule that OK's MCP tools — never native file tools — handle in-scope markdown." compatibility: "Any agent host with the OpenKnowledge MCP server configured; ok init wires the agents it detects on your machine. Some steps shell out to the ok CLI. Hosts that take an uploaded skill bundle instead of reading a project directory (Claude Desktop, Cowork, claude.ai) are covered by ok cowork." metadata: author: "Inkeep" repository: "https://github.com/inkeep/open-knowledge-skills"

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). Stop at first match: OK_DESKTOP_TERMINAL or OK_HOSTED_AGENT set → you're inside OpenKnowledge (desktop terminal / in-app agent panel) → ok open <name> (switches the window the user is already looking at); never paste a localhost URL into your reply here · in-app browser (Claude Code Desktop's Browser pane, Cursor, Codex) → preview_url, then open/navigate it to the doc · else plain CLI → ok open <name>. ok open <name> opens a doc or folder (auto-detected); --skill <name> for a skill. The previewUrl field is a route id, not your open mechanism. Don't preview_screenshot to confirm edits. Full Step-0 procedure + per-surface how-to: references/preview.md.
  4. Knowledge layers: capturing a source (ingest), synthesizing findings (research), promoting a decision (consolidate) — procedures, not tool calls; there is no ingest tool. Ingest ships here (references/ingest-and-sources.md); research + consolidate come with the knowledge-base pack. Layer model + packs: references/starter-packs.md.
  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/improve a skill", "turn this into a skill"): STOP and invoke /open-knowledge-write-skill for scope (project/global), contract, evaluation, and install. Author through write({ skill }), never a document path. Skills are real folders under editor skills/ dirs (.claude · .cursor · .codex · .github · .opencode · .pi · .agents): one source plus managed copies/symlinks. Read/edit via skills and edit({ skill }) — they route to the source. Never hand-edit a non-source copy: managed copies refresh from the source; editing one forks it and stops refresh.

Tool index — 21 tools (router; the MCP tool descriptions carry each tool's full contract)

  • Reads — exec (primary; read-only cat/ls/grep/… plus frontmatter/backlink/history enrichment; one command or one pipe, not a shell), search (ranked BM25 + recency), history (doc versions), links (kind: backlinks|forward|dead|orphans|hubs|suggest, or an array for one call), skills (search + read: query → skills.sh; omit name to LIST managed (Project + Global); name READs one — by name+scope, never path), config (resolved config), palette (authoring forms + html preview starters + theme tokens; palette({ components }) for JSX schemas), preview_url (browser preview URL on demand), share_link (GitHub-substrate share URL; read-only, errors without a GitHub remote), lint (markdown-lint violations: document for one doc, omit for the project; fix: true with document auto-fixes fixable rules in place — attributed, live in the preview; the rest need edit/write), audit (every lint violation + broken internal link in one read-only report, by source file with lines; path scopes; for link VALIDATION use this, not links; caveats in references/linking.md). **Read ran
Read the complete source ↗