inkeep/open-knowledge

OpenKnowledge — Agenten-Anleitung

OpenKnowledge (OK) ist eine über MCP bereitgestellte Markdown-CRDT-Kollaborationsplattform. Dieser Skill ist die alleinige Quelle für die OK-Agenten-Anleitung. Jede unten stehende Regel ist ein MUSS, sofern nicht anders gekennzeichnet. Tiefe befindet sich in references/*.md — eine Ebene tiefer; lade eine Referenz, wenn ihre Aufgabe anfällt.

Die Skill-Version folgt @inkeep/open-knowledge-server. cat ~/.ok/skill-state.yml zeigt an, was installiert ist. ok seed benötigt @inkeep/open-knowledge >= 0.4.0; bei einem Fehler unknown command, führe npm install -g @inkeep/open-knowledge aus.

Einrichtung (noch nicht verbunden?). Wenn die mcp__open-knowledge__*-Werkzeuge in deinem Client nicht verfügbar sind, ist dieses Projekt auf diesem Rechner nicht eingerichtet — siehe references/setup.md für die Leiter (.mcp.json genehmigen → ok start CLI → optionale Desktop-App) und die kanonische Kurzanleitung.

TL;DR — die 90%-Fälle

1. Lesen: exec("cat …") für ein einzelnes Dokument, exec("ls -A …") für ein Verzeichnis (Ordner-Standardwerte + Vorlagenmenü), exec("grep …") für Literalsuche, search für bewertetes Retrieval. Native Read / Grep nur für Quellcode (.ts / .py / …), niemals für im Geltungsbereich befindliche .md / .mdx.
2. Schreiben: write({ document: { path, content } }) für ein neues oder vollständig ersetztes Dokument; edit({ document: { path, find, replace } }) für eine Textersetzung im Inhalt; edit({ document: { path, frontmatter } }) für einen Merge-Patch der Frontmatters (null löscht einen Schlüssel). delete({ document }) entfernt, move({ from, to }) verschiebt/benennt um. Textersetzung betrifft nur den Inhalt. Übergib bei jedem Inhaltsschreibvorgang eine einzeilige summary (≤80 Zeichen, Benutzer-sichtbares Ergebnis).
3. Vorschau: Jede Lese-/Schreibantwort enthält eine reine Routen-previewUrl (/#/<doc>, ohne Host:Port). Öffne den Browser einmal zu Beginn der Sitzung. Verwende nicht preview_screenshot, um Änderungen zu bestätigen — die Werkzeugantwort ist die Bestätigung. Vollständiger Multi-Host-Vertrag: references/preview.md.
4. Workflow-Anleitungen: workflow({ kind: 'ingest' | 'research' | 'consolidate' | 'discover' }) gibt eine prozedurale Anleitung zurück, keine Daten. Verwende sie, wenn die Arbeit in die Schicht passt.
5. Direkte Fragen: Eine einfache geschäftliche Frage („welche Kunden…“, „was haben wir zu… entschieden“) wird an search / exec + eine zitierte Chat-Antwort weitergeleitet — kein Schlüsselwort „research“ erforderlich. Speichere nur, wenn dauerhaft + mehrere Dokumente + nicht bereits abgedeckt, und biete es zuerst an. Siehe references/corpus-qa.md.
6. Erstellen oder Verbessern eines Skills („einen Skill schreiben/erstellen“, „diesen Skill verbessern“, „dies in einen Skill umwandeln“): STOPPE und rufe den open-knowledge-write-skill-Skill auf — er besitzt die Auswahl des Geltungsbereichs (Projekt vs. global), den SKILL.md-Vertrag, die Bewertung und die Installation; improvisiere nicht von diesem Skill aus. Autorisiere über das skill-Ziel (write({ skill })), niemals über ein rohes .ok/skills/…-Dokument. Lese, diff oder bearbeite niemals die installierten Projektionen unter .claude/skills/ · .cursor/skills/ · .codex/skills/ · .opencode/skills/ · .agents/skills/ — install generiert sie und überschreibt sie beim nächsten Sync; sie sind NICHT die Quelle der Wahrheit.

Werkzeugindex — 19 Werkzeuge (Router; die MCP-Werkzeugbeschreibungen enthalten den vollständigen Vertrag jedes Werkzeugs)

• Lesen — exec (primär; schreibgeschütztes cat/ls/grep/find/head/tail/wc/sort/uniq/cut + Frontmatter-/Backlink-/Verlaufsanreicherung; ein Befehl oder eine Pipe, keine Shell), search (bewertet BM25 + Aktualität), history (Versionen eines Dokuments), links (kind: backlinks|forward|dead|orphans|hubs|suggest oder ein Array für eine einmalige Prüfung), skills (Skills finden + lesen: name weglassen, um ALLE Skills in Projekt + Global AUFZULISTEN; name übergeben, um einen zu LESEN — adressiert durch name+scope, NIEMALS durch Pfad), config (aufgelöste Konfiguration), palette (Markdown-native Autorenformulare + html preview-Starter + Design-Tokens; palette({ components }) für JSX-Schemata), preview_url (Browser-Vorschau-URL auf Anfrage), share_link (Share-Link auf GitHub-Basis; schreibgeschützt, Fehler bei fehlendem GitHub-Remote).
• Schreiben — vier native CRUD-Verben, polymorph über document / folder / template / skill / asset (übergib GENAU EIN Ziel, verschachtelt unter seinem Adressschlüssel): write (erstellen/überschreiben; write({ skill: { name, description, body, scope? } }) autorisiert einen Skill → .ok/skills/<name>/SKILL.md, ein Entwurf bis install), edit (Textersetzung im Inhalt ODER Frontmatter-Merge-Patch; kein Asset), delete (entfernen), move (verschieben/umbenennen, schreibt Verweise um; ein Skill akzeptiert auch scope/toScope, um Projekt↔Global zu verschieben — Verlauf wird zurückgesetzt, erneutes install). Die Ausgabe spiegelt den Zielschlüssel der Eingabe wider; der Vorschau-Envelope (previewUrl, warning) bleibt auf oberster Ebene. Plus install (der Schritt Entwurf → Installiert für einen skill — projiziert ihn in deine Editoren; nach write({ skill }) ausführen), checkpoint (benannte Version) und restore_version (Rückgängigmachen). Das Frontmatter eines Ordners ist offen und nur für sich selbst (wirkt NICHT kaskadierend); Vorlagen sind das, womit neue Dokumente beginnen. Erstellen/Verbessern eines Skills? Rufe open-knowledge-write-skill auf (TL;DR #6), improvisiere nicht.
• Konflikte — conflicts (kind: list|content), resolve_conflict (eine Lösung schreiben + committen; zerstörerisch). Siehe references/conflict-resolution.md.
• Workflow — workflow (kind: ingest|research|consolidate|discover; prozedurale Anleitungen, keine Daten). Siehe references/workflow-guides.md.

Selbstkorrektur bei Fehlgebrauch: Einschränkungen, die JSON Schema nicht ausdrücken kann („genau ein Ziel“, „find benötigt ein replace“, Inhalt-XOR-Frontmatter) geben isError: true mit einer einzeiligen korrigierenden Form zurück. Lies sie und wiederhole mit dieser Form; rate nicht.

Werkzeuge NICHT in OK MCP (die deines Hosts): preview_start, preview_screenshot, WebFetch, WebSearch, natives Read / Grep / Glob / Edit. Die STOP-Regel legt fest, welche du für im Geltungsbereich befindliches Markdown verwenden darfst.

STOP — native Werkzeuge für im Geltungsbereich befindliches .md / .mdx

Leite jedes Lesen und Schreiben von im Geltungsbereich befindlichem Markdown über die MCP-Werkzeuge von OK — niemals über die nativen Dateiwerkzeuge deines Hosts. Natives Edit / sed / direktes Write auf im Geltungsbereich befindlichem Markdown umgeht das CRDT und verliert die Agenten-Zuschreibung im Schatten-Repository; native Lesevorgänge überspringen Frontmatter, Backlinks, Schatten-Repository-Aktivität und Projekt-Git-Verlauf, die OK für jede gefundene Datei zurückgibt. Wenn dieser Arbeitsbereich OpenKnowledge MCP konfiguriert hat, verwende nicht native Dateiwerkzeuge für Markdown-Pfade innerhalb des Inhaltsverzeichnisses. Das Verbot deckt jede gängige Rechtfertigung ab:

• Natives Read / Grep / Glob auf im Geltungsbereich befindlichen .md / .mdx — der ursprüngliche Fall.
• Bash ls / Bash find / Bash cat auf Verzeichnissen, die im Geltungsbereich befindliches Markdown enthalten — verwende exec("ls -A …") / exec("find … -name '*.md'") / exec("cat …"). Native gibt bloße Namen zurück; exec gibt Frontmatter, Backlink-Anzahlen und aktuelle Aktivität zurück. -A zeigt versteckte Einträge (.ok/, .okignore) ohne das ./..-Rauschen.
• Glob-Muster, die auf Markdown abzielen (**/*.md, specs/**, reports/**, docs/**) — verwende exec mit find oder exec("ls -A <dir>").
• Entsendung des Explore-/Allzweck-Subagenten für Markdown-lastige Erkundungen — Subagenten verwenden intern native Werkzeuge und umgehen OK. Führe Markdown-Erkundungen selbst über exec / search durch. Subagenten bleiben für Quellcode-Erkundungen angemessen.
• Natives Read / Grep auf im Geltungsbereich befindlichem Markdown innerhalb von .ok/ — .ok/ ist im Geltungsbereich; behandle seine .md / .mdx wie jede andere Wissensdatenbank-Datei.
• ls / cat / find auf .ok/skills/ zum Entdecken oder Lesen eines Skills — .ok/skills/ ist undurchsichtiger interner Zustand; Skills werden durch name+scope, nicht durch Pfad adressiert. Verwende das skills-Werkzeug (name weglassen, um über Projekt + Global aufzulisten; name übergeben, um einen zu lesen); durchstöbere niemals .ok/skills/...-Pfade.

MCP-Werkzeugsichtbarkeit — exec NICHT zu sehen ist NICHT die Ausstiegsluke. Die MCP-Verkabelung variiert je nach Client (Claude Code, Cursor, Codex, Windsurf, VS Code). Server-Bezeichnungen sind benutzerdefiniert; Werkzeuge erscheinen möglicherweise nicht als Symbole der obersten Ebene namens exec. Wenn OpenKnowledge hier als MCP-Server registriert ist, leite Markdown-Lesevorgänge über seinen exec / search über den dokumentierten MCP-Aufruf deines Clients (einschließlich jeglicher generischer „MCP-Werkzeug aufrufen“-Abläufe). Die Registrierung ist der Test, nicht die Sichtbarkeit auf oberster Ebene.

Deine anfängliche Werkzeugliste ist NICHT erschöpfend — führe eine Werkzeugerkennung durch, bevor du schlussfolgerst, dass das MCP fehlt. Einige Clients (insbesondere Codex) verschieben MCP-Werkzeuge hinter einen trägen tool_search / Werkzeugerkennungsschritt, sodass mcp__open-knowledge__* im anfänglichen Werkzeugsatz fehlt und erst erscheint, nachdem du danach gesucht hast. Das Fehlen in der sichtbaren Liste bedeutet „Ich habe es noch nicht entdeckt“, NICHT „es ist nicht registriert“. Wenn du die Werkzeuge nicht siehst, ist dein erster Schritt, die Werkzeugerkennung / tool_search deines Clients für open-knowledge (oder exec / search / write) auszuführen — schließe nicht aus der anfänglichen Liste auf Nichtverfügbarkeit.

Ausstiegsluke. Natives Read / Grep / Glob auf .md / .mdx ist NUR erlaubt, wenn nach dem Ausführen der Werkzeugerkennung (oben) kein OpenKnowledge MCP-Server für dieses Projekt registriert ist, oder unmittelbar nachdem du tatsächlich einen MCP-Aufruf getätigt hast und dieser fehlgeschlagen ist — beginne dann einen für den Benutzer sichtbaren Satz mit OpenKnowledge MCP nicht verfügbar:. „Nicht registriert“ ist eine Schlussfolgerung, die du erst ziehen darfst, nachdem die Werkzeugerkennung dies ergeben hat — niemals allein aus der anfänglichen Werkzeugliste. Verwende die Luke niemals, weil du den MCP-Pfad deines Clients übersprungen hast, exec nicht als Werkzeug der obersten Ebene gesehen hast, keine Werkzeugerkennung durchgeführt hast oder dir eingeredet hast, der Skill sei nicht notwendig.

Quellcode und Nicht-Markdown-Dateien (.ts, .py, package.json, …): natives Read / Grep / Glob jederzeit.

Lesen — Beispiele

• Eine Datei lesen: exec("cat <path>.md") — Inhalt + vollständige Anreicherung.
• Ein Verzeichnis auflisten: exec("ls -A <dir>") — Frontmatter pro Kind, rekursive Markdown-Anzahlen, zuletzt aktualisiertes Dokument pro Unterverzeichnis, eigene title/description/tags des Ordners + templates_available. Bevorzuge -A gegenüber einfachem ls.
• Literalsuche: exec("grep -rn <term> <dir> | head -5") — Übereinstimmungen + Anreicherung in übereinstimmenden Dateien.
• Bewertete Suche: search({ query }) — Titel-Boost + BM25 für Inhalt + Aktualität; verwende, wenn du das beste Dokument auswählst, nicht wenn du jedes Vorkommen auflistest.

Schreiben

Rufe write / edit auf, sobald du Inhalt hast (leite gemäß der STOP-Regel über MCP weiter).

Speichere inkrementell — die Wissensdatenbank IST dein Prüfpunkt (MUSS). Bei jeder mehrstufigen oder langlaufenden Aufgabe — einer Recherchekampagne, einer multidokumentalen Synthese, einem Stapel von Dokumenten — schreibe abgeschlossene Arbeiten in die Wissensdatenbank, sobald du jede Einheit abschließt: pro Abschnitt, pro Quelle, pro Dokument. Halte niemals fertige Ergebnisse nur in deinem Kontext fest, um auf eine einzige abschließende Schreiboperation am Ende zu warten. Eine Ratenbegrenzung, ein Absturz oder eine Kontextverdichtung in der Mitte der Aufgabe verwirft alles, was noch nicht geschrieben wurde; bereits gespeicherte Arbeit überlebt, und du nimmst die Arbeit wieder auf, indem du das Dokument zurückliest. Erstelle das Zieldokument frühzeitig (Gerüst + Frontmatter), dann bearbeite jeden Abschnitt mit edit, sobald er sich verfestigt.

Übergib bei jedem Inhaltsschreibvorgang eine summary (SOLLTE) — eine einzeilige (≤80 Zeichen), für den Benutzer sichtbare Änderungsnotiz, die zum Zeitleisteneintrag wird. Greife zu visueller Struktur (Callout, mermaid, Tabelle, html preview), wo sie den Punkt besser transportiert als Prosa; rufe palette während des Entwurfs auf. Beratende Schreibwarnungen, MDX-Autorenschaft, Lösch-/Verschiebemechaniken und visuelle Autorenschaft: references/writing.md + references/components-and-visuals.md + references/media-and-assets.md.

Fundierung — jede Tatsachenbehauptung benötigt eine Quelle (MUSS)

Dokumente der Wissensdatenbank sind faktische Artefakte. Jede Behauptung muss nachvollziehbar sein, und die Quelle muss innerhalb der Wissensdatenbank leben, nicht im öffentlichen Web schweben.

• Die Wissensdatenbank ist die Quelle der Wahrheit — geschlossener Kreislauf. Externe Quellen werden nicht durch einen Verweis auf das Live-Web zitiert; sie werden über ingest hereingeholt und dann lokal zitiert. Eine bloße [source](https://...)-URL innerhalb eines Wissensdatenbank-Dokuments ist kein fertiges Zitat — es ist ein TODO, das besagt „diese Quelle muss noch eingepflegt werden.“ Die Kette funktioniert nur, wenn jedes Blatt ein lokales Dokument ist.
• Jede Tatsachenbehauptung MUSS ihre Quelle an der Stelle der Behauptung zitieren. Keine unbegründete Spekulation.
• Webquellen für Wissensdatenbank-Dokumente → rufe die Seite ab (Host WebFetch / WebSearch), dann führe sie als lokales Dokument mit ingest ein, dann zitiere den lokalen Pfad: [Quellenname](./path/to/source.md) (das lokale Dokument trägt die URL in source_url:). Inline [source](URL) ist eine Chat-Möglichkeit, keine Wissensdatenbank-Möglichkeit.
• Selbstabgerufene Zählungen. Wenn DU eine URL abgerufen hast, um eine Behauptung zu untermauern, die in der Wissensdatenbank landet, löst dieser Abruf genau wie das Teilen durch einen Benutzer ingest aus — stufe nicht auf eine Inline-URL-Zitierung herab, nur weil der Abruf agenteninitiiert war.
• Interne Querverweise → Standard-Markdown-Link zum OK-Dokument mit der maßgeblichen Behauptung; dieses Dokument muss seine eigenen Quellen zitieren (Ketten enden in erhaltenen lokalen Dokumenten).
• Wenn du keine Beweise hast: führe eine Websuche durch und führe sie mit ingest ein, ODER markiere inline (TODO: benötigt Quelle), ODER schreibe die Behauptung nicht. Erfinde NICHTS. Unbegründete Spekulation verrottet zu nicht nachvollziehbarem Stammeswissen.

Verlinkung — Standard-Markdown-Links (MUSS)

Verknüpfe jede Nominalphrase, die ein anderes Dokument benennt — [Text](./relative/pfad.md) — und verlinke großzügig. Jeder Link muss zu einem Dokument auflösen, das existiert, wenn du fertig bist (ein Vorwärtsverweis in derselben Bearbeitungsphase, den du später erstellst, ist in Ordnung; für einen, der tatsächlich nicht existieren wird, belasse die Erwähnung als einfachen Text + eine verfolgte Aufgabe). Setze einen Link niemals in Backticks (`[text](./foo.md)` ist ein Fehler) und verwende niemals HTML <a>. Lies brokenLinks bei jeder write/edit-Antwort: [] bedeutet, dass alle Links aufgelöst werden; eine gefüllte Liste nennt jeden defekten href + reason (no-such-doc / no-such-file / unresolvable) — behebe sie in einem folgenden edit. links({ kind: "dead" }) ist die maßgebliche Endzustandsprüfung (die rote Unterstreichung des Editors ist Slug-tolerant und lügt, also vertraue dem Werkzeug). Externe Webquellen sind KEINE Inline-Inhaltslinks (siehe Fundierung). Vollständiges Regelset + die [[Seite]]-Legacy-Notiz: references/linking.md.

Ordner, Frontmatter, Vorlagen

Jedes .md / .mdx benötigt YAML-Frontmatter — title + description erforderlich, tags empfohlen. Zwei opt-in, verschachtelte Ordnermechanismen: Ordner-Frontmatter (<folder>/.ok/frontmatter.yml — die eigenen offenen Eigenschaften des Ordners; nur für sich selbst, kaskadiert NICHT

…

[gekürzt für die Übersetzung]