open-knowledge

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

OpenKnowledge（OK）は、MCP 経由で利用できる Markdown-CRDT コラボレーションプラットフォームです。このスキルは、OK エージェント向けガイダンスの唯一の情報源です。特に明記されていない限り、以下のルールはすべて必須です。詳細は 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 を実行してください。

CLI 名。 ここに記載されているコマンドは Stable の ok（open-knowledge）と ~/.ok/ を使用します。OpenKnowledge Beta では、代わりに ok-beta（open-knowledge-beta）と ~/.ok-beta/ を使用してください。preview_url の okOpenCommand には、すでに正しいものが指定されています。

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

要約 — 90% のケース

1. 読み取り： 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 } })、フロントマターのマージパッチには edit({ document: { path, frontmatter } })（キーを削除するには null）を使用します。delete({ document }) で削除し、move({ from, to }) で移動または名前を変更します。本文の検索・置換は本文のみが対象です。コンテンツを書き込む際は毎回、1行の summary（80文字以内で、ユーザーに表示する結果の説明）を渡してください。
3. ドキュメントのプレビュー／表示 — 最初に使用するサーフェスを1つ決めてください（セッションごとに1回）。 最初に該当した条件で止めてください。OK_DESKTOP_TERMINAL または OK_HOSTED_AGENT が設定されている → OpenKnowledge 内（デスクトップターミナル／アプリ内エージェントパネル）です → ok open <name> を実行します（ユーザーがすでに見ているウィンドウを切り替えます）。ここでは返信に localhost の URL を貼り付けないでください · アプリ内ブラウザー（Claude Code Desktop の Browser ペイン、Cursor、Codex） → preview_url を使い、ドキュメントを開く／移動します · それ以外の通常の CLI → ok open <name> を実行します。ok open <name> はドキュメントまたはフォルダーを開きます（自動判定）。スキルには --skill <name> を使います。previewUrl フィールドはルート ID であり、開く手段ではありません。編集内容の確認に preview_screenshot を使わないでください。手順0の全手順とサーフェスごとの使い方については、references/preview.md を参照してください。
4. 直接的な質問： 「どの顧客が…」「…について何を決めましたか」のような一般的な業務上の質問には、search または exec を使い、出典を示したチャット形式の回答を返してください。「research」というキーワードは不要です。永続化するのは、情報が長期的に有用で、複数のドキュメントに関わり、すでに記載されていない場合に限り、まず提案してください。references/corpus-qa.md を参照してください。
5. スキルの作成または改善（「スキルを書く／作る／改善する」「これをスキルにする」）： 作業を停止し、範囲（プロジェクト／グローバル）、仕様、評価、インストールについて /open-knowledge-write-skill を呼び出してください。スキルはドキュメントのパスではなく、write({ skill }) を使って作成します。スキルはエディターの skills/ ディレクトリ（.claude · .cursor · .codex · .github · .opencode · .pi · .agents）に実際のフォルダーとして存在します。1つのソースと、管理対象のコピー／シンボリックリンクで構成されます。読み取り／編集には skills と edit({ skill }) を使用してください。ソースに処理がルーティングされます。 ソースではないコピーを直接編集しないでください。記録済みで未編集のコピーは、スキルウォッチャーの実行時またはサーバー起動時にソースから更新されるため、ソースの編集が更新に先行することがあります。コピーを直接編集すると、そこから分岐し、更新されなくなります。

ツール一覧 — 19 個（ルーター。呼び出し時の契約はツールの説明と入力スキーマに記載）

• exec — ドキュメントのコンテキスト付きでファイルやディレクトリを読み取ります。
• search — ワークスペース内の一致項目を順位付けして取得します。
• links — リンクの関係と候補を調べます。
• lint — コンテンツのルールを確認し、自動修正を適用します。
• audit — コンテンツのルールと内部リンクを検証します。
• write — コンテンツを作成または置き換えます。
• edit — コンテンツやメタデータをその場で変更します。
• delete — コンテンツを削除します。
• move — 管理された操作を通じてコンテンツの名前を変更するか、移動します。
• install — スキルのソースとエディターの配置先を管理します。
• import — スクリプトを実行せずにスキルフォルダーを取り込みます。
• history — ドキュメント、フォルダー、スキルのバージョンを調べます。
• skills — 名前とスコープでスキルを検索、一覧表示、または読み取ります。
• checkpoint — 名前付きバージョンを保存します。
• restore_version — ドキュメントまたはスキルのバージョンを復元します。
• palette — コンポーネントと作成フォームを検索します。
• config — 解決済みの設定を読み取ります。
• preview_url — ブラウザーのプレビュー URL を取得します。
• share_link — GitHub を利用した共有リンクを取得します。

lint/audit が成功した場合は ran を確認してください。ran に含まれていないファミリーはチェックされておらず、[] はチェックが選択されていないことを意味します。リンクの検証には audit を使用してください。links は関係とリンク切れの生の状態を報告します。注意事項については references/linking.md を参照してください。

スキルの配置先とスキルの内容は別々です。ソースフォルダーがスキルそのものであり、インストール済みのコピーを削除してもスキルは削除されません。Project↔Global の移動では、履歴がリセットされます。移動先のレベルで保持できるものだけが再配置され、残りはソースから削除されて droppedLocations として返されます（成功した場合は install で再追加してください）。復元する前に、返された結果を確認してください。フォルダーの frontmatter は自由形式で、そのフォルダーだけに適用されます（カスケードしません）。新しいドキュメントの開始点となるのはテンプレートです。

誤用時の自己修正：「ターゲットを 1 つだけ指定する」「find には replace が必要」「本文か frontmatter のどちらか一方」といった、JSON Schema では表現できない制約に違反すると、isError: true と修正方法を示す 1 行の形式が返されます。その形式を読んで再試行してください。推測しないでください。

OK MCP（お使いのホストにあるもの）には含まれないツール：preview_start、preview_screenshot、WebFetch、WebSearch、ネイティブの Read / Grep / Glob / Edit。対象範囲内の 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 は .／.. を除く隠しエントリも表示します。
• Markdown を対象とする Glob パターン — exec はファイルオペランドを展開します（cat specs/*.md）。引用符で囲まれたパターンや、コマンド独自のパターン（find -name）はそのまま保持されます。
• Markdown の調査に Explore／汎用のサブエージェントを呼び出すこと — サブエージェントは内部でネイティブツールを使用するため、OK を迂回します。Markdown の調査は自分で exec／search を使って行ってください。サブエージェントはソースコードの調査には引き続き適切です。
• .ok/ 内の対象範囲内の Markdown に対するネイティブの Read／Grep — .ok/ も対象範囲内です。その中の .md／.mdx は、ほかの KB ファイルと同じように扱ってください。
• スキルの検出や読み取りを目的としたスキルフォルダーへの ls／cat／find — スキルにはパスではなく name+scope でアクセスします（スキルは任意のエディターディレクトリ、.agents/skills/ ハブ、カスタムルートのいずれにも配置でき、別の場所にコピーがある場合もあります）。skills ツールを使用してください。

exec が見当たらないことは、回避の口実にはなりません。 クライアントによって設定、ラベル、ツールの表示方法は異なります。特に Codex などでは、MCP ツールの検出が遅延される場合があります。判定基準はトップレベルのシンボルに表示されるかどうかではなく、登録されているかどうかです。まず open-knowledge のツール検出を実行してください。詳細：references/setup.md。

例外。 .md／.mdx に対するネイティブの Read／Grep／Glob は、（上記の）ツール検出を実行した結果、このプロジェクトに OpenKnowledge MCP サーバーが登録されていない場合、または MCP 呼び出しを実際に行って失敗した直後に限り、使用できます。その場合は、ユーザーに見える文を OpenKnowledge MCP unavailable: で始めてください。「登録されていない」と結論づけられるのは、ツール検出を実行して該当するサーバーが見つからなかった場合だけです。最初のツール一覧だけで判断してはいけません。クライアントの MCP 経路を使わなかった、トップレベルのツールとして exec が表示されなかった、ツール検出を実行しなかった、スキルは不要だと判断した、といった理由で例外を適用してはいけません。

ソースコードおよび Markdown 以外のファイル（.ts、.py、package.json、…）：ネイティブの Read／Grep／Glob を常に使用してください。

執筆

内容ができたらすぐに write / edit を呼び出してください（STOP ルールに従い、MCP 経由で実行します）。

段階的に永続化してください — ナレッジベースがチェックポイントです（必須）。 複数段階にわたるタスクや長時間かかるタスク（調査、複数ソースの統合、複数のドキュメントの処理など）では、作業が完了した単位ごと（セクションごと、ソースごと、ドキュメントごと）に、完了した内容をナレッジベースに書き込んでください。仕上げにまとめて書き込もうとして、完了した調査結果をコンテキスト内に保持し続けてはいけません。途中でレート制限、クラッシュ、コンテキストの圧縮が発生すると、まだ書き込んでいない内容はすべて失われます。すでに永続化した内容は残るため、ドキュメントを読み返して作業を再開できます。早い段階で対象ドキュメントを作成し（スケルトンとフロントマターを用意し）、内容が固まるごとに各セクションを edit してください。

コンテンツを書き込むたびに summary を渡してください（推奨）。 ユーザー向けの1行メモ（80文字以内）を指定します。これはタイムラインの項目になります。文章よりも要点を伝えやすい場合は、ビジュアル構造（Callout、mermaid、表、html preview）を活用してください。下書きの段階で palette を呼び出してください。書き込み時の警告、MDX の記述、削除／移動の仕組み、ビジュアル作成については、references/writing.md + references/components-and-visuals.md + references/media-and-assets.md を参照してください。

根拠 — すべての事実の主張に出典が必要です（必須）

ナレッジベースのドキュメントは事実を記録するものです。すべての主張を出典までたどれるようにし、出典は公開ウェブ上ではなく、ナレッジベース内に置いてください。

取り込みは手順であり、ツールではありません。 バイナリとテキストの分類、SSRF 対策を施した取得フラグ、サイズと実行ファイルのチェック、ラッパーのフロントマターについては、references/ingest-and-sources.md を参照してください。最初に取り込む前に読んでください。単純に取得して貼り付けるだけでは、すべてのチェックを飛ばすことになります。

• クローズドループ。 外部ソースは取り込み手順を通じて取得し、その後、ローカルで引用します。ナレッジベースのドキュメント内に裸の [source](https://...) を置いても、引用にはなりません。「取り込みがまだ必要」という意味の TODO です。すべての末端がローカルドキュメントである場合にのみ、引用の連鎖が機能します。
• すべての事実の主張には、主張箇所に出典を必ず明記してください。 出典のない推測は禁止です。
• ウェブ上の出典 → ページを取得し（ホストの WebFetch / WebSearch を使用）、取り込んでから、パスを引用します：出典名（ローカルドキュメントには source_url: が記載されます）。インラインの [source](URL) はチャットで使うためのもので、ナレッジベース用ではありません。
• 自分で取得した場合も対象です。 主張の根拠として自分で取得した URL も、同じように取り込む必要があります。インライン URL で代用することはできません。
• 内部相互参照 → 信頼できる主張を含む、問題のないドキュメントにリンクしてください。そのドキュメントには独自の出典が記載されます（引用の連鎖は保存済みのローカルドキュメントで終わります）。
• 根拠がない場合は？ 検索して結果を取り込むか、(TODO: needs source) と記すか、その主張を書かないでください。捏造してはいけません。出典のない推測は、追跡できない内部の言い伝えとして腐朽していきます。

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

別のドキュメントを指す名詞句にはすべて [テキスト](./relative/path.md) 形式のリンクを付け、積極的にリンクしてください。長いドキュメントの特定のセクションを示す場合は、チャットの返信内でも ./path.md#heading-slug にリンクしてください。すべてのリンクは、作業が終わる時点で存在するドキュメントに解決できる必要があります（同じ作業中に後で作成するドキュメントへの先行参照は問題ありません。実際には作成されないドキュメントへの言及は、リンクにせず通常の文章として残し、追跡可能なタスクを作成してください）。リンクをバッククォートで囲んではいけません（`[text](./foo.md)` は不具合です）。HTML の <a> も使用しないでください。write / edit の後は毎回 brokenLinks を読み、報告された href を修正してください。 [] は、brokenLinkSuppression によって予約ログの検出結果（修正対象ではありません）が抑制されていない場合、または link-check-deferred 警告によりまだチェックされていないことが示されていない場合に、すべてのリンクが解決されていることを意味します（サーバーの起動中、または他の書き込みでビジー状態だった場合）。そのドキュメントは、後でそのドキュメントに対して write / edit を実行するか、audit を実行したときにのみ再チェックされます。サーバーの起動中は audit がタイムアウトすることがあります。audit が正式な判定方法です。 同じマーカーは同じ意味を持ちます。外部ウェブソースは本文内に直接リンクしないでください（「根拠」を参照）。ルール全文、スラッグの規則、[[Page]] のレガシーに関する注記については、references/linking.md を参照してください。

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

すべての .md／.mdx に YAML フロントマターが必要です。title と description は必須、tags は推奨です。**OKF プロジェクト（okf パック）は例外です。**パックのルールが優先されます。ルート以外の index.md にフロントマターは不要です（frontmatter-reserved-index リントは、キーがあると警告します）。log.md にもフロントマターは不要で、コンセプトドキュメントに必要なのは空でない type だけです。そこでの title／description は任意です。オプトインで使えるネストしたフォルダの仕組みが 2 つあります。フォルダーのフロントマター（<folder>/.ok/frontmatter.yml — フォルダー自体のオープン形式のプロパティ。適用対象はフォルダー自身のみで、子ドキュメントには継承されません）と、テンプレート（<folder>/.ok/templates/ — 新しいドキュメントの作成時に使う内容）です。ほとんどのフォルダーには .ok/ がありません。ドキュメントのフロントマターは、ディスク上のそのドキュメント自身の YAML のみです。構造モデルと書き込み前の完全なチェックリストについては、references/folder-model.md を参照してください。テンプレートの作成とフォルダーの編集については、references/template-authoring.md を参照してください。フロントマターと本文の編集ルールについては、references/doc-editing.md を参照してください。

• **書き込む前にフォルダーを確認してください（必須）。**フォルダー内のドキュメントを作成／編集する前に、セッションごとに各フォルダーにつき 1 回 exec("ls -A <folder>") を呼び出してください。フォルダーの title／description／tags と templates_available が返されます。これを省略すると、フォルダーのルールに違反するドキュメントが作成されます。（フォルダーにフロントマターもテンプレートもなく、リポジトリのほかの場所に相当量のコンテンツがある場合は、オンボーディングが済んでいません。まず references/onboard-existing-repo.md を実行してください。）
• 適合するテンプレートがあれば使ってください（必須）。write({ document: { path, template } }) でテンプレートを適用してください。継承されたテンプレートも対象です。一致するテンプレートがない場合、またはユーザーが自由形式を求めた場合に限り、省略できます（その理由をチャットに記載してください）。同じ形式が繰り返し使われる場合は、先を見越してテンプレートを作成してください。
• **ドキュメントごとに繰り返し使うプロパティが必要になった場合（必須）。**複数の兄弟ドキュメントで同じフロントマターを書く場合は、テンプレートに初期値を設定してください（write({ template })）。フォルダーのフロントマターからドキュメントへ値は継承されません。

競合を考慮した書き込み

競合を理由に書き込みが拒否された場合は、ツールの復旧手順と references/conflict-resolution.md に従い、アプリで追跡対象の競合を解決するようユーザーに依頼してください。

アンチパターン — 特によくあるもの

作業	してはいけないこと	すること
Markdown の一覧表示／検索／読み取り	Bash: ls／Glob: **/*.md／Read: foo.md	exec("ls -A …")／exec("find …")／exec("cat …")
Markdown の多いディレクトリを調べる	Agent(Explore)（OK を迂回）	自分で exec／search を使う
別のドキュメントを参照する	`[text](./p.md)`（バッククォートで囲む）または HTML <a>	[text](./p.md)
画像を埋め込む	<img>、localhost／preview_url の URL、ホットリンク	ローカルに保存して 
KB ドキュメントで事実を主張する	引用のない本文、またはインラインの [src](https://…)	ソースを取り込み（references/ingest-and-sources.md）、ローカルパスを引用する
編集が反映されたことを確認する	preview_screenshot／検証ループ	CRDT ツールの応答を信頼する
Markdown ドキュメントを削除する	Bash: rm／ネイティブの削除機能	delete({ document })（リスクがある場合は、事前に checkpoint() を実行）
不慣れなフォルダーに書き込む	いきなり write を実行する	まず exec("ls -A <folder>") を実行する

表の全項目については、references/anti-patterns.md を参照してください。

ナレッジレイヤー — KB 作業の典型的な形

繰り返し行われる3つのプラクティスであり、ツール呼び出しではありません。それぞれ、スキルのガイダンスとして提供される一連の手順です。

レイヤー	タイミング	手順
取り込み	共有された URL／PDF／ファイルをそのまま保持する場合、または主張の根拠とするために URL を取得した場合（バイナリソースはスクレイピングせず、そのまま保持します）。	references/ingest-and-sources.md — ここに含まれています。§Grounding はこれに依存します
調査	ソースを調査／比較／統合し、status: provisional の記事と sources: を作成します。	/research-with-sources スキル
統合	意思決定が行われた場合、supersedes: チェーンを持つ正規の信頼できる情報源を作成します。	/consolidate-notes スキル

調査と統合は ok seed --pack knowledge-base で導入できます。このパックがなければ、これらの手順は利用できません。独自の手順を即興で作らず、通常の根拠に基づいた write として作業するか、パックの導入を提案してください（ok seed --pack knowledge-base --dry-run で追加される内容を確認できます）。

黙って手順をつなげないでください。取り込み → 調査 → 統合の進行はユーザーに委ね、手順の STOP ゲートはセッションレベルの「質問せずに進める」というヒントより優先してください。KB の内容を変更するターンの後は、log.md があるか確認し、その規約に従ってください（references/cadence-and-logs.md）。複数ドキュメントをまとめて処理する際は、プレビューに進行状況が表示されるよう、作業を交互に進めてください。

すでにコンテンツがあるリポジトリのオンボーディング：references/onboard-existing-repo.md。レイヤーモデルとパック：references/starter-packs.md。

このスキルの範囲を超える機能

OK には、このスキルで説明されている以上の機能があり、リリースごとに変化します。ここで説明されていない機能については、推測せずに確認してください。

• ドキュメント — https://openknowledge.ai/docs
• ソース — https://github.com/inkeep/open-knowledge

対象範囲のまとめ

OK は、解決された content.dir の下にあるドキュメントを探します（実行時：config({ key: 'content.dir' })）。ルートまたは任意の深さのフォルダーにある .gitignore と .okignore が除外対象を定義します。content.dir の下にある、除外されていないすべての .md／.mdx ファイルは OpenKnowledge ドキュメントです。specs/、reports/、docs/ の下にあるファイルも含まれます。フォルダーのメタデータとテンプレートは、.ok/config.yml ではなく、入れ子になった <folder>/.ok/ に保存されます。git worktree で作業していますか？ OK ツールの呼び出し時に worktree の絶対パスを一度 cwd として渡してください。セッション中はその設定が維持されるため、読み取り、書き込み、プレビューのすべてがその worktree を対象にします。