open-knowledge
Authoritative agent-runtime contract for working inside an OpenKnowledge project — a markdown-CRDT knowledge base exposed over MCP
Install / Use
npx skills add inkeep/open-knowledge --skill projectInstalls into whichever agent you are using.
SKILL.md
Installable skill definition
Quality Score
Category
Content & MediaSupported Platforms
Our assessment of open-knowledge
open-knowledge scores 88/100 on our quality scale, 570th of 1,155 Content & Media skills we index (top 50%).
Its SKILL.md is 20 KB long, well organised into 15 sections and no code examples: a thorough specification that gives an agent plenty to work with.
With 4,309 GitHub stars, it is one of the more widely adopted skills in the catalogue.
Maintenance, license and trust
- The repository was last updated about 2 months ago, so open-knowledge is actively maintained.
- Our last check on 2026-11-01 found the source still online.
- It is released under GPL-3.0, a copyleft license: you can use it, but modified versions you distribute must carry the same license.
- Its trust signals score 100/100, with no cautions. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.
Safety scan
No issues foundOur scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.
AI review by kimi-k2.7-code on 2026-09-29. Automated pattern scan on 2026-09-29. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.
open-knowledge compared with similar skills
All 4 of these similar skills score higher than open-knowledge; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| open-knowledge (this skill)by inkeep | 88 | 4.3k | 53d ago | SKILL.md |
| Agent-Reachby Panniantong | 100 | 112.3k | 8d ago | CLAUDE.md |
| rufloby ruvnet | 100 | 81.9k | today | CLAUDE.md |
| headroomby headroomlabs-ai | 100 | 79.8k | today | CLAUDE.md |
| CowAgentby zhayujie | 100 | 48.0k | today | CLAUDE.md |
Frequently asked questions
- How do I install open-knowledge?
- Run
npx skills add inkeep/open-knowledge --skill open-knowledge. The install tabs above show the steps for each supported agent. - Which AI agents does open-knowledge work with?
- It is written for Universal, as a SKILL.md file. Other agents that read the same format can often use it too.
- Is open-knowledge safe to use?
- Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It is GPL-3.0-licensed and scores 100/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is open-knowledge still maintained?
- The repository was last updated about 2 months ago, so open-knowledge is actively maintained.
Skill content
View source on GitHubname: 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.ymlshows what's installed.ok seedneeds@inkeep/open-knowledge>= 0.4.0; if it errorsunknown 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 — seereferences/setup.mdfor the rung ladder (approve.mcp.json→ok startCLI → optional desktop app) and the canonical quickstart.
TL;DR — the 90% case
- Reads:
exec("cat …")for one doc,exec("ls -A …")for a directory (folder defaults + template menu),exec("grep …")for literal,searchfor ranked retrieval. NativeRead/Greponly on source code (.ts/.py/ …), never on in-scope.md/.mdx. - 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 (nulldeletes a key).delete({ document })removes,move({ from, to })moves/renames. Body find/replace is body-only. Pass a one-linesummary(≤80 chars, user-facing outcome) on every content write. - Preview / open a doc — determine your ONE surface FIRST (once per session). Stop at first match:
OK_DESKTOP_TERMINALorOK_HOSTED_AGENTset → you're inside OpenKnowledge (desktop terminal / in-app agent panel) →ok open <name>(switches the window the user is already looking at); never paste alocalhostURL 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. ThepreviewUrlfield is a route id, not your open mechanism. Don'tpreview_screenshotto confirm edits. Full Step-0 procedure + per-surface how-to:references/preview.md. - Knowledge layers: capturing a source (ingest), synthesizing findings (research), promoting a decision (consolidate) — procedures, not tool calls; there is no
ingesttool. Ingest ships here (references/ingest-and-sources.md); research + consolidate come with theknowledge-basepack. Layer model + packs:references/starter-packs.md. - 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. Seereferences/corpus-qa.md. - Authoring or improving a skill ("write/make/improve a skill", "turn this into a skill"): STOP and invoke
/open-knowledge-write-skillfor scope (project/global), contract, evaluation, and install. Author throughwrite({ skill }), never a document path. Skills are real folders under editorskills/dirs (.claude·.cursor·.codex·.github·.opencode·.pi·.agents): one source plus managed copies/symlinks. Read/edit viaskillsandedit({ 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;cat/ls/grep/… on a read-only filesystem, 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; omitnameto LIST managed (Project + Global);nameREADs one — byname+scope, never path),config(resolved config),palette(authoring forms +html previewstarters + theme tokens;palette({ components })for JSX schemas),preview_url(preview URL on demand),share_link(GitHub-substrate share URL; read-only, errors without a GitHub remote),lint(markdown-lint violations:documentfor one doc, omit for the project;fix: truewithdocumentauto-fixes fixable rules in place — attributed, live in the preview; the rest neededit/write),audit(every lint violation + broken internal link in one report, by source file with lines;pathscopes; for link VALIDATION use this, notlinks; caveats inreferences/linking.md). Readranon successfullint/auditresults: a family absent fromranwas not checked, and[]means no checks were selected. - Writes — four native CRUD verbs, polymorphic over
document/folder/template/skill/asset(pass EXACTLY ONE target, nested under its address key):write(create/overwrite;write({ skill: {…} })authors a skill as a REAL folder at the project's default skill home — live immediately for that folder's agent),edit(body find/replace/frontmatter merge-patch; no asset),delete,move(move/rename, rewrites referrers; a skill also takesscope/toScopefor Project↔Global: history resets, only what the destination level can host re-projects; the rest is removed at source, returned asdroppedLocations(success: re-add withinstall)). Output mirrors the input key; the preview envelope (previewUrl,warning) stays top-level. Plusinstall(WHERE askilllives:add/removelocations additively — editor ids,agents, or custom roots;mode+convertre-form ONLY the locations named;sourcemoves the real folder. The source folder IS the skill — no "uninstall everywhere"; a skill dies only viadelete),import(acquire a skill-dir intoadd's locations; scripts never run),checkpoint(named version), andrestore_version(roll back). A folder's frontmatter is open-shape and self-only (does NOT cascade); templates are what new docs start with. - Conflicts —
conflicts(kind: list|content),resolve_conflict(write a resolution from that conflict'sresolutionOptions; commits only formerge-native; destructive). Seereferences/conflict-resolution.md.
Self-correcting on misuse: constraints JSON Schema can't express ("exactly one target", "find needs a replace", body-XOR-frontmatter) return isError: true with a one-line corrective shape. Read it and retry with that shape; don't guess.
Tools NOT in OK MCP (your host's): preview_start, preview_screenshot, WebFetch, WebSearch, native Read / Grep / Glob / Edit. The STOP rule governs which you may use on in-scope markdown.
STOP — native tools on in-scope .md / .mdx
Route every in-scope markdown read and write through OK's MCP tools — never your host's native file tools. Native Edit / sed / direct Write on in-scope markdown bypasses the CRDT and loses agent attribution in the shadow repo; native reads skip frontmatter, backlinks, shadow-repo activity, and project git history that OK returns for every matched file. When this workspace has OpenKnowledge MCP configured, do not use native file tools on markdown paths inside the content directory. The ban covers every common rationalization:
- Native
Read/Grep/Globon in-scope.md/.mdx— the original case. Bash ls/Bash find/Bash caton dirs containing in-scope markdown — useexec("ls -A …")/exec("find … -name '*.md'")/exec("cat …"). Native returns bare names;execadds frontmatter, backlinks, and recent activity.-Ashows hidden entries without./...- Glob patterns that target markdown —
execexpands file operands (cat specs/*.md); quoted patterns and a command's own pattern (find -name) stay literal. - Dispatching the Explore / general-purpose subagent for markdown-heavy exploration — subagents use native tools internally and bypass OK. Do markdown exploration yourself via
exec/search. Subagents remain appropriate for source-code exploration. - Native
Read/Grepon in-scope markdown inside.ok/—.ok/is in-scope; treat its.md/.mdxlike any other KB file. ls/cat/findon skill folders to discover or read a skill — skills are addressed byname+scope, not by path (a skill can live in any editor dir, the.agents/skills/hub, or a custom root, with copies elsewhere). Use theskillstool.
Not seeing exec is NOT the escape hatch. Wiring, labels, and tool visibility vary by client; some (notably Codex) defer MCP tools behind lazy discovery. Registration is the test, not top-level-symbol visibility — run tool discovery for open-knowledge first. Detail: references/setup.md.
Escape hatch. Native Read / Grep / Glob on .md / .mdx is allowed only when, after running tool discovery (above), no OpenKnowledge MCP server is registered for this project, or immediately after you actually invoked an MCP call and it failed — then begin a user-visible sentence with OpenKnowledge MCP unavailable:. "Not registered" is a conclusion you may only reach after tool discovery turned it up empty — never from the initial tool list alone. Never use the hatch because you skipped your client's MCP path, didn't see exec as a top-level tool, didn't run tool discovery, or rationalized the skill wasn't necessary.
Source code and non-markdown files (.ts, .py, package.json, …): native Read / Grep / Glob always.
Reads — examples
- Read a file:
exec("cat <path>.md")— contents + full enrichment. - List a directory:
exec("ls -A <dir>")— per-child frontmatter, recursive markdown counts, most-recently-updated doc per subdir, the folder's owntitle/description/tags+templates_available. Prefer-Aover plainls. - Literal search:
exec("grep -rn <term> <dir> | head -5")— matches + enrichment on matched files. - Ranked search:
search({ query })— title boost + body BM25 + recency; use when picking the best doc, not when listing every occurrence.
Writing
Call write / edit as soon as you have content (route through MCP per the STOP rule).
Persist incrementally — the knowledge base IS your checkpoint (MUST). On any multi-step or long-running task — a research sweep, a multi-source synthesis, a batch of docs — write completed work to the KB as you finish each unit: per section, per source, per doc. Never hold finished findings only in your context waiting for one final write at the end. A rate limit, crash, or
Truncated for display — read the full file on GitHub.
Related Skills
Agent-Reach
112.3kGive your AI agent eyes to see the entire internet. Read & search Twitter, Reddit, YouTube, GitHub, Bilibili, XiaoHongShu — one CLI, zero API fees.
ruflo
81.9k🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated
headroom
79.8kCompress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.
CowAgent
48.0kOpen-source personal AI assistant & Agent Harness. Plans tasks, runs tools and skills, self-evolves with memory and knowledge. Multi-agent, multi-model, multi-channel. Lightweight, extensible, one-line install.
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
