inkeep/open-knowledge

OpenKnowledge — エージェントガイダンス

OpenKnowledge (OK) は、MCPを介して公開されたMarkdown-CRDTコラボレーションプラットフォームです。このスキルは、OKエージェントガイダンスの唯一の情報源です。以下のルールはすべて、特に明記されていない限り必須（MUST）です。詳細は references/*.md にあります — 深さは1レベルです。関連するタスクが発生したら参照ファイルを読み込んでください。

スキルのバージョンは @inkeep/open-knowledge-server に対応します。cat ~/.ok/skill-state.yml でインストール済みの状態を確認できます。ok seed には @inkeep/open-knowledge >= 0.4.0 が必要です。エラーが発生する場合（unknown command）、npm install -g @inkeep/open-knowledge を実行してください。

セットアップ（まだ接続されていませんか？）。 クライアントで mcp__open-knowledge__* ツールが利用できない場合、このマシンでプロジェクトが設定されていません。セットアップの手順（.mcp.jsonの承認 → ok start CLI → オプションのデスクトップアプリ）および公式クイックスタートについては、references/setup.md を参照してください。

TL;DR — 90%のケース

1. 読み取り： 単一ドキュメントには exec("cat …")、ディレクトリには exec("ls -A …")（フォルダのデフォルト+テンプレートメニュー）、リテラル検索には exec("grep …")、ランキング検索には search を使用します。ネイティブの Read/Grep はソースコード（.ts/.py/…）にのみ使用し、スコープ内の .md/.mdx には使用しません。
2. 書き込み： 新規または全文置換のドキュメントには write({ document: { path, content } })、本文の検索・置換には edit({ document: { path, find, replace } })、フロントマターのマージパッチ（nullでキー削除）には edit({ document: { path, frontmatter } }) を使用します。delete({ document }) で削除、move({ from, to }) で移動/リネームします。本文の検索・置換は本文のみが対象です。すべてのコンテンツ書き込みには、1行（80文字以下）の summary（ユーザー向けの成果）を渡します。
3. プレビュー： すべての読み取り/書き込み応答には、ルートのみの previewUrl（/#/<doc>、ホスト:ポートなし）が含まれます。セッション開始時にブラウザを1度開いてください。編集を確認するために preview_screenshot を使用しないでください。ツールの応答が確認です。完全なマルチホスト契約については references/preview.md を参照してください。
4. ワークフローガイド： workflow({ kind: 'ingest' | 'research' | 'consolidate' | 'discover' }) はデータではなく手順ガイドを返します。作業がレイヤーに適合する場合に使用します。
5. 直接的な質問： プレーンなビジネス上の質問（「どの顧客が…」「～について何を決定しましたか？」）は、search/exec + 引用付きチャット回答にルーティングされます。「research」キーワードは不要です。永続化は、耐久性があり、マルチドキュメントで、まだカバーされていない場合のみ行い、まず提案します。詳細は references/corpus-qa.md を参照してください。
6. スキルの作成または改善（「スキルを作成/作成する」、「このスキルを改善する」、「これをスキルにする」）： 停止して、open-knowledge-write-skill スキルを呼び出してください。このスキルは、スコープ選択（プロジェクト vs グローバル）、SKILL.md契約、評価、インストールを管理します。このスキルから即興で作成しないでください。skill ターゲット（write({ skill })）を介して作成し、生の .ok/skills/… ドキュメントは決して使用しないでください。.claude/skills/・.cursor/skills/・.codex/skills/・.opencode/skills/・.agents/skills/ にあるインストール済みのプロジェクションを読み取り、差分を確認、または編集しないでください。 install がこれらを生成し、次の同期で上書きします。これらは真実の情報源ではありません。

ツールインデックス — 19のツール（ルーター。各ツールの完全な契約はMCPツールの説明に含まれます）

• 読み取り — exec（プライマリ。読み取り専用の cat/ls/grep/find/head/tail/wc/sort/uniq/cut + フロントマター/バックリンク/履歴のエンリッチメント。1つのコマンドまたは1つのパイプ。シェルではありません）、search（ランキングBM25 + 新しさ）、history（ドキュメントのバージョン）、links（kind: backlinks|forward|dead|orphans|hubs|suggest、またはワンコール監査用の配列）、skills（スキルの検索+読み取り：nameを省略するとプロジェクト+グローバルのすべてのスキルをLISTし、nameを渡すと1つをREADします。name+scopeでアドレス指定。パスでは指定しません）、config（解決済み設定）、palette（Markdownネイティブ作成フォーム+ html preview スターター+テーマトークン。JSXスキーマには palette({ components })）、preview_url（オンデマンドのブラウザプレビューURL）、share_link（GitHub基盤の共有URL。読み取り専用。GitHubリモートがない場合はエラー）。
• 書き込み — 4つのネイティブCRUD動詞。document/folder/template/skill/asset に対してポリモーフィック（そのアドレスキーの下で、ターゲットを正確に1つ渡します）。write（作成/上書き。write({ skill: { name, description, body, scope? } }) でスキルを作成 → .ok/skills/<name>/SKILL.md。install までは ドラフト です）、edit（本文の検索/置換 OR フロントマターのマージパッチ。アセットは不可）、delete（削除）、move（移動/リネーム。参照元を書き換えます。スキルの場合、scope/toScope でプロジェクト↔グローバルを移動可能。履歴はリセットされ、再 install が必要です）。出力は入力ターゲットキーを反映します。プレビューエンベロープ（previewUrl、warning）はトップレベルのままです。さらに、install（skill のドラフト→インストールステップ。エディタにプロジェクションします。write({ skill }) の後に実行します）、checkpoint（名前付きバージョン）、restore_version（ロールバック）。フォルダのフロントマターはオープンシェイプで、フォルダ自身のみに影響します（カスケードしません）。テンプレートは新しいドキュメントの開始点です。スキルを作成/改善する場合は、open-knowledge-write-skill（TL;DR #6）を呼び出し、即興で作成しないでください。
• 競合 — conflicts（kind: list|content）、resolve_conflict（解決策を書き込み+コミット。破壊的）。詳細は references/conflict-resolution.md を参照してください。
• ワークフロー — workflow（kind: ingest|research|consolidate|discover。手順ガイド。データではありません）。詳細は references/workflow-guides.md を参照してください。

誤用時の自己修正： JSON Schemaで表現できない制約（「ターゲットは正確に1つ」、「findにはreplaceが必要」、「本文XORフロントマター」）は、isError: true と1行の修正指示を返します。それを読んでその指示に従い再試行してください。推測しないでください。

OK MCPに含まれないツール（ホストのもの）：preview_start、preview_screenshot、WebFetch、WebSearch、ネイティブの Read/Grep/Glob/Edit。STOPルールが、スコープ内のMarkdownに対してどのツールを使用できるかを管理します。

STOP — スコープ内の .md/.mdx に対するネイティブツール

スコープ内のMarkdownの読み取りと書き込みはすべて、OKのMCPツールを経由してください。ホストのネイティブファイルツールは決して使用しないでください。 スコープ内のMarkdownに対するネイティブの Edit/sed/直接の Write はCRDTをバイパスし、シャドウリポジトリでのエージェント帰属を失います。ネイティブの読み取りは、OKが一致したファイルごとに返すフロントマター、バックリンク、シャドウリポジトリのアクティビティ、プロジェクトのgit履歴をスキップします。このワークスペースにOpenKnowledge MCPが設定されている場合、コンテンツディレクトリ内のMarkdownパスに対してネイティブファイルツールを使用しないでください。この禁止は、すべての一般的な合理化をカバーします。

• スコープ内の .md/.mdx に対するネイティブの Read/Grep/Glob — 元のケースです。
• スコープ内のMarkdownを含むディレクトリに対する Bash ls/Bash find/Bash cat — exec("ls -A …")/exec("find … -name '*.md'")/exec("cat …") を使用します。ネイティブはベアな名前を返します。exec はフロントマター、バックリンク数、および最近のアクティビティを返します。-A は ./.. ノイズなしで隠しエントリ（.ok/、.okignore）を表示します。
• Markdownをターゲットにしたグロブパターン（**/*.md、specs/**、reports/**、docs/**）— exec を find とともに、または exec("ls -A <dir>") を使用します。
• Markdown中心の探索のためのExplore/汎用サブエージェントのディスパッチ — サブエージェントは内部でネイティブツールを使用し、OKをバイパスします。Markdownの探索は、自分で exec/search を介して行ってください。サブエージェントはソースコードの探索には引き続き適切です。
• .ok/ 内のスコープ内Markdownに対するネイティブの Read/Grep — .ok/ はスコープ内です。その .md/.mdx を他のKBファイルと同様に扱います。
• スキルの発見または読み取りのための .ok/skills/ に対する ls/cat/find — .ok/skills/ は不透明な内部状態です。スキルは name+scope でアドレス指定され、パスでは指定されません。skills ツールを使用してください（nameを省略するとプロジェクト+グローバルをリスト、nameを渡すと1つを読み取り）。.ok/skills/... パスをブラウズしないでください。

MCPツールの可視性 — exec が見えなくてもエスケープハッチではありません。 MCPの配線はクライアント（Claude Code、Cursor、Codex、Windsurf、VS Code）によって異なります。サーバーラベルはユーザー定義です。ツールは exec という名前のトップレベルのシンボルとして表示されない場合があります。OpenKnowledgeがMCPサーバーとして登録されている場合、クライアントのドキュメント化されたMCP呼び出し（汎用の「MCPツールを呼び出す」フローを含む）を介して、その exec/search を経由してMarkdownの読み取りをルーティングしてください。登録がテストであり、トップレベルシンボルの可視性ではありません。

初期のツールリストは網羅的ではありません — MCPが欠落していると結論付ける前に、ツールのディスカバリを実行してください。 一部のクライアント（特にCodex）は、MCPツールを遅延 tool_search/ツールディスカバリステップの背後に隠します。そのため、mcp__open-knowledge__* は事前のツールセットには存在せず、検索後にのみ表示されます。可視リストからの欠落は「まだ発見していない」ことを意味し、「登録されていない」ことを意味しません。ツールが見えない場合、最初のアクションはクライアントのツールディスカバリ/tool_search を open-knowledge（または exec/search/write）に対して実行することです。初期リストから利用不可を推測しないでください。

エスケープハッチ。 .md/.mdx に対するネイティブの Read/Grep/Glob は、以下の場合のみ許可されます：上記のツールディスカバリを実行した後、このプロジェクトにOpenKnowledge MCPサーバーが登録されていない場合、または、実際にMCP呼び出しを実行して失敗した直後の場合。その場合は、「OpenKnowledge MCP unavailable:」で始まるユーザーに見える文を開始します。「登録されていない」という結論は、ツールディスカバリで空だった後にのみ到達できます。初期のツールリストだけからではありません。クライアントのMCPパスをスキップした、exec がトップレベルツールとして表示されなかった、ツールディスカバリを実行しなかった、またはスキルが必要ないと合理化したために、このハッチを使用しないでください。

ソースコードおよび非Markdownファイル（.ts、.py、package.json、…）：ネイティブの Read/Grep/Glob は常に使用できます。

読み取り — 例

• ファイルの読み取り：exec("cat <path>.md") — 内容+完全なエンリッチメント。
• ディレクトリのリスト：exec("ls -A <dir>") — 子ごとのフロントマター、再帰的なMarkdown数、サブディレクトリごとに最も最近更新されたドキュメント、フォルダ自身の title/description/tags + templates_available。プレーンな ls よりも -A を推奨します。
• リテラル検索：exec("grep -rn <term> <dir> | head -5") — 一致+一致したファイルのエンリッチメント。
• ランキング検索：search({ query }) — タイトルブースト+本文BM25+新しさ。最適なドキュメントを選ぶ場合に使用し、すべての出現箇所をリストする場合には使用しません。

書き込み

コンテンツができ次第、write/edit を呼び出します（STOPルールに従ってMCPを経由）。

インクリメンタルに永続化する — ナレッジベースがチェックポイントです（必須）。 マルチステップまたは長時間実行のタスク（調査スイープ、マルチソース合成、ドキュメントのバッチ）では、各ユニット（セクション、ソース、ドキュメントごと）を完了したら、完成した作業をKBに書き込みます。すべての調査結果をコンテキストに保持し、最後に一度だけ書き込むのを待たないでください。タスクの途中でレート制限、クラッシュ、またはコンテキストの圧縮が発生すると、まだ書き込まれていないすべてが失われます。既に永続化された作業は生き残り、ドキュメントを読み戻して再開できます。ターゲットドキュメントを早期に作成し（スケルトン+フロントマター）、各セクションが固まるにつれて edit で追加します。

すべてのコンテンツ書き込みに summary を渡します（推奨） — 1行（80文字以下）のユーザー向け変更ノート。これがタイムラインエントリになります。視覚的な構造（Callout、mermaid、テーブル、html preview）を、散文よりもポイントを伝える場合に使用します。ドラフト作成時に palette を呼び出します。アドバイザリーな書き込み警告、MDX作成、削除/移動の仕組み、およびビジュアル作成については、references/writing.md + references/components-and-visuals.md + references/media-and-assets.md を参照してください。

グラウンディング — すべての事実の主張にはソースが必要です（必須）

ナレッジベースのドキュメントは事実の成果物です。すべての主張はトレース可能でなければならず、ソースはナレッジベース内に存在しなければなりません。公開ウェブ上に浮遊していてはいけません。

• ナレッジベースが真実の情報源です — クローズドループ。 外部ソースはライブウェブに引用されません。ingest を介して取り込まれ、その後ローカルに引用されます。KBドキュメント内のベアな [source](https://...) URLは、完成した引用ではありません。それは「このソースはまだインジェストが必要」というTODOです。すべてのリーフがローカルドキュメントである場合にのみ、チェーンは機能します。
• すべての事実の主張は、主張の時点でそのソースを引用しなければなりません。 ソースのない推測は禁止です。
• KBドキュメントのWebソース → ページをフェッチし（ホスト WebFetch/WebSearch）、次に ingest でローカルドキュメントとして取り込み、ローカルパスを引用します：[source name](./path/to/source.md)（ローカルドキュメントは source_url: にURLを持ちます）。インラインの [source](URL) はチャットのための便宜であり、KBのためのものではありません。
• 自己取得カウント。 KBに載せる主張をグラウンディングするためにURLをフェッチした場合、そのフェッチはユーザーの共有とまったく同じように ingest をトリガーします。フェッチがエージェント主導であったからといって、インラインURL引用にダウングレードしないでください。
• 内部相互参照 → 権威ある主張があるOKドキュメントへの標準Markdownリンク。そのドキュメントは自身のソースを引用しなければなりません（チェーンは保存されたローカルドキュメントで終了します）。
• 証拠がない場合： Web検索を実行して ingest するか、インラインで (TODO: needs source) とマークするか、その主張を書きません。捏造しないでください。ソースのない推測は、トレース不可能な部族知識に腐敗します。

リンク — 標準Markdownリンク（必須）

別のドキュメントを名前で指定する名詞句にはすべてリンクを張ります — [text](./relative/path.md) — そして、積極的にリンクを張ります。すべてのリンクは、作業が完了するまでに存在するドキュメントに解決されなければなりません（同じパス内で後で作成する前方参照は問題ありません。本当に存在しないものについては、プレーンな散文+追跡タスクとして言及を残します）。リンクをバックティックで囲まないでください（`[text](./foo.md)` はバグです）。また、HTMLの <a> は使用しないでください。すべての write/edit 応答で brokenLinks を読み取ってください。[] はすべてのリンクが解決されたことを意味します。入力されたリストは、壊れた各 href + reason（no-such-doc/no-such-file/unresolvable）を名前で示します。後続の edit で修正してください。 links({ kind: "dead" }) は、信頼できる最終状態監査です（エディタの赤い下線はスラッグに対して寛容で嘘をつくため、ツールを信頼してください）。外部Webソースはインライン本文リンクではありません（グラウンディングを参照）。完全なルールセット+ [[Page]] レガシーノート：references/linking.md。

フォルダ、フロントマター、テンプレート

すべての .md/.mdx にはYAMLフロントマターが必要です — title + description は必須、tags は推奨。2つのオプトイン、ネストされたフォルダメカニズム：フォルダフロントマター（<folder>/.ok/frontmatter.yml — フォルダ自身のオープンシェイププロパティ。自己のみ、カスケードしません