okf

Open Knowledge Format（OKF）

OKF は、AI エージェントが必要とするコンテキストを バンドル として表現する、Google のオープンでベンダー中立な仕様（v0.2）です。バンドルは Markdown ファイルのディレクトリで、各ファイルは コンセプト（テーブル、データセット、指標、ランブック、プレイブック、API、結合パス）を表し、説明対象のコードの隣でバージョン管理されます。Markdown ファイルと YAML フロントマターだけで構成されています。この形式が契約となるため、どのプロデューサーでもバンドルを作成でき、どのコンシューマー（エージェント、ビューアー、検索インデックス）でも SDK やベンダーロックインなしで読み取れます。

このスキルは 2 つの方法で使えます。必要に応じてコマンドを実行する方法と、エージェントが読むナレッジを整える際に暗黙的に適用する方法です。詳細な規範仕様は spec.md に、コマンドごとの手順は commands.md に、コピーして使える出発点は templates.md にあります。

OKF の方法を選択する

OKF に関するリクエストでは、ユーザーが意図する成果に合う、最も範囲の狭い方法を選択してください。OKF Studio の一般的なチャットでは、okf_capability_catalog を呼び出して有効なバージョン管理対象のカタログを確認し、okf_capability_resource を呼び出して選択した方法を読み込みます。Studio 以外では、該当する capability ファイルを直接読み込みます。最初の進捗報告で、選択した capability を明示してください。リソースを読み込むまでは、その方法を使用したと主張してはいけません。

ユーザーの意図	読み込む方法
範囲が限定されたバンドルに関する質問に回答する、または既知のリンクをたどる	okf-inspect
証拠を選択する、経路を調べる、または取得漏れを診断する	okf-retrieve
保存先やコンセプトマップが未確定の新しいバンドルを計画する	okf-create
既存のナレッジに事実、引用、または関係性を追加する	okf-enrich
ファイルを変更せずに準拠状況やナレッジの健全性を確認する	okf-audit
再現可能な検証上または健全性上の不具合を修正する	okf-repair
範囲が限定された外部証拠とバンドル内の主張を照合する	okf-research
変更前に直接的な影響と下流への影響を特定する	okf-change-impact
バージョン管理されたスキーマ、規約、レイアウト、または識別子の変更を計画する	okf-migrate
受け入れ済みの証拠と既知の保存先から新しいコンセプトを作成する	okf-author、続けて writing
意味を変えずに既存の文章を改善する	okf-revise、続けて writing

すべての方法は引き続き参照可能ですが、詳細な指示は必要に応じて読み込みます。すべての方法を一度に読み込むと、コンテキストを無駄に消費し、相容れない境界を組み合わせてしまいます。たとえば、inspect は読み取り専用、revise はナレッジの変更を禁止し、enrich は出典のある追加を許可し、repair は再現可能な不具合を必須とします。1 つのリクエストが複数のフェーズにまたがる場合は、各方法を順番に実行し、それぞれの停止条件と成果物の契約を守ってください。

実行環境

能力ファイルは、OKF Studio 内での実行を必須とするものではなく、持ち運び可能な手法として扱ってください。

• OKF Studio 内では、指定された okf_* および studio_stage_* ツールを使用してください。作業用の画面が役立つ場合は、選択した手法に必要な構造化成果物を出力してください。
• Studio 外では、インベントリの作成、読み取り、検索、走査をホストのファイルシステムおよび検索ツールに置き換えてください。一致性と接続性を確認するには、同梱のバリデーターを実行してください。承認された編集には、ホスト標準の差分確認およびレビューの手順を使用してください。Studio ツールの結果、レシート ID、ヘルス所見 ID、バンドルのフィンガープリントを捏造しないでください。
• 構造化成果物は、デフォルトでは Studio 専用です。 Studio 外では、呼び出し元から成果物の JSON を明示的に求められない限り、同じ証拠と判断を簡潔な文章、Markdown、または通常の差分で返してください。
• 承認はホストのワークフローに従います。 Studio では書き込みをレビュー済みのステージングに留めます。それ以外では、ユーザーが指定した編集範囲とホスト標準の承認ルールに従ってください。手法に記載された Studio のステージングに関する説明によって、ファイルを編集するという明示的な依頼が無効になることはありません。

唯一のルール

すべての概念ドキュメントに、空でない type フィールドを含む YAML フロントマターがあれば、そのバンドルは規格に適合しています。これだけが必須要件であり、v0.2 では明確にそう定めています。それ以外は推奨される構造であり、存在しなくても利用側は対応できる必要があります。この原則を守れば、誰が作成したバンドルでも、誰のエージェントでも読み取れます。規格への完全な適合基準と、利用側に求められる許容範囲については、spec.md を参照してください。

v0.2 で追加された内容。 v0.1 が答えていたのは「エージェントが知っておくべきことは何か？」でした。v0.2 では「これは信頼すべき内容か、今も正しいか？」が加わりました。任意のファミリーが 4 つ追加されましたが、どれもバンドルを規格不適合にすることはありません。sources（知識の由来と、信頼性を示すシグナル）、generated および verified（誰が作成し、誰が確認したか。信頼階層はこの情報に基づいて算出されます）、status および stale_after（ライフサイクル）、そして Attested Computation 型（エージェントが実行できるものの、作成はできない、承認済みの計算）です。v0.1 から変更された点は 2 つあります。timestamp は generated: { by, at } に変わり、本文セクションの # Citations は sources フロントマターに置き換わりました。v0.1 のバンドルも、文書化されたフォールバックにより引き続き利用できるため、移行は急務ではなく、実施する価値があります。手順については migrate コマンドを参照してください。

コマンド

/okf <command> [target] として実行します。詳細は commands.md を参照してください。

コマンド	内容
init	バンドルを作成します。ディレクトリ、okf_version を宣言するルートの index.md、最初の概念フォルダーを作成します。
add	1つの概念ドキュメントを作成します。説明的な type を選び、推奨されるフロントマターを記入し、sources と generated を記録して、本文に # Schema と # Examples を記述します。
attest	承認済みの計算を Attested Computation 概念として定義します。これにより、エージェントは計算を実行して結果の検証を受けられますが、書き換えることはできません。
migrate	バンドルを v0.1 から v0.2 に移行します。機械的な名前変更を2つ行い、続いてアクターと、検証済みとして主張しない内容について判断します。
enrich	ソース（BigQuery データセット、OpenAPI 仕様、wiki、ウェブサイト、docstring）を概念に変換します。まず全範囲をインベントリに列挙し、次に信頼できるドキュメントをたどる工程でスキーマ、結合パス、引用を追加し、さらにエンティティの工程で、ソースが言及しているものの説明していない、重要な名前すべてに独自のリンク先概念を与えます。
link	相対 Markdown リンクで概念を結び付け、周囲の文章で関係性を明示します。
index	index.md の一覧を生成または更新し、段階的な情報開示によってエージェントがナビゲートできるようにします。
log	日付入りの log.md エントリー（Creation、Update、Deprecation）を新しい順に追加します。追記専用で、1エントリー1行とし、並行する作成者が競合なくマージできるように記述します。
validate	適合性チェックを実行します。node okf-validate.mjs <bundle> を使うか、commands.md の手動チェックリストに従います。
health	書き込みを行わずに、適合性、接続性、ナビゲーション、来歴、鮮度、重複、カバレッジのシグナルを検査します。
retrieve	質問に対する一貫性のあるエビデンスを選択し、経路、省略、プロバイダー、フィンガープリント、棄権の判断を保持します。
export	既存のソースを適合するバンドルに変換します。カタログ、メタデータダンプ、スキーマエクスポート、ドキュメントサイト、ウェブサイト、または外部 URL（/okf export <url>）が対象です。全範囲をマッピングし、すべてのセクションを網羅し、名前付きエンティティごとに独自の概念を与えたうえで、作成ゲートを通過させます。フロントページのスナップショットではありません。プロデューサーの役割です。
consume	質問に答えるためにバンドルを読み取ります。index.md から始め、リンクをたどり、不足しているものは許容します。

暗黙のモード

エージェントが後から読むためにナレッジを整える場合は、求められていなくても OKF を適用してください。

• エージェントが参照するデータ資産（テーブル、ビュー、データセット、メトリクス、ディメンション）またはプロセス（ランブック、プレイブック、インシデントガイド）を文書化する場合は、散文ではなく、type を持つ概念として記述してください。
• エージェントが利用するメタデータ、カタログ、スキーマ、または docstring をエクスポートまたは変換する場合は、JSON の塊や Wiki のダンプではなく、バンドルを出力してください。
• エージェントが必要とする非推奨の通知、結合パス、またはビジネス上の意味の定義を書く場合、それは概念です。ファイルと type を付与してください。
• 既存の OKF バンドルを編集する場合は、作業中も準拠状態を保ってください。概念の generated（by と at の両方。担当者は前回の執筆者と異なる場合があるため）を更新し、log.md にエントリを追加し（今日の日付の見出しの下に1行で記載し、過去のエントリは編集しないでください）、影響を受ける index.md を再生成し、関係を作成したら必ずリンクを追加してください。generated.at が示すのは、最後の意味のある変更です。そのため、意味を保った機械的な変換（リンク形式の変換、句読点の調整など）ではログを更新し、generated はそのままにしてください。文章を書き換えた場合は更新してください。モデルの変更は担当者の変更です。別のモデルが新しい文章を書いた場合、古い帰属を引き継がず、そのモデルを by に記録してください。verified イベントが付いた概念を実質的に変更した場合、その検証は変更後の内容を対象としなくなるため、確認されていない文章にお墨付きを与える状態にせず、削除してください。これは「ナレッジに手を加えて変換する」ケースであり、記録を省くとバンドルがいつの間にか劣化する原因になります。

ガード。 OKF はエージェントが読むナレッジのためのものであり、人間だけが読む文章のためのものではありません。README、ブログ記事、人間向けの設計ドキュメントはバンドルではありません。成果物がエージェント向けかどうか不明な場合は、変換する前に確認してください。

概念ドキュメントの概要

概念はフロントマターと Markdown 本文で構成されます。概念の識別子は .md を除いたパスです。そのため、tables/orders.md は tables/orders という概念になります。

• フロントマター。 type は必須です。次の項目を優先順位順に指定することを推奨します：title、description（1 文）、resource（基盤となるアセットの正規 URI）、tags（YAML リスト）。続いて v0.2 の各ファミリーを指定します。いずれも任意です：sources（リスト。各エントリーには少なくとも resource が必要で、本文で引用する場合は id も必要です。また、判明している場合は信頼性を示す author、usage_count、last_modified も指定します）、generated: { by, at }（記述者と記述日時。v0.1 の timestamp に代わるもの）、verified（実際の確認を示す { by, at } のリスト、または単一のマッピング）、status（draft|stable|deprecated。指定がなければ stable）、stale_after（絶対日付の YYYY-MM-DD）。生成側は他のキーを追加できます。利用側は未知のキーを拒否せず、そのまま保持します。
• 作成主体。 すべての識別フィールド（generated.by、verified[].by、sources[].author）には、同じ規則を適用します。エージェントまたはツールの場合は <producer>/<version>、人の場合は human:<id>、自動化処理の場合は process:<id> です。利用側は human: 接頭辞に基づいて信頼度を計算するため、エージェントが生成したコンテンツにこの接頭辞を付けてはいけません。この単一の規則によって、信頼レイヤーの有効性が保たれます。
• 本文。 自由形式の文章より、構造化された Markdown（見出し、リスト、表、コードフェンス）を優先してください。適用できる場合は、# Schema、# Examples、# Computation の見出しを使用します。主張を 1 つ引用するには、sources エントリーの ID を脚注で付けます（...sharded daily.[^ga4-schema]）。ラベルは結合キーであり、文章ではありません。各事実には、拡張セットが提供する中で最も適切な形式を選んでください（次のセクションを参照）。
• 予約済みファイル名。 これらは概念ではありません。index.md はディレクトリ一覧であり、バンドルのルートにある index.md が okf_version を宣言する場合を除き、フロントマターを含みません。log.md は日付付きの変更履歴を追記していくファイルです。過去のエントリーは編集せず、修正内容は以前の記述に優先するものとして追記します。
• リンク。 どちらの形式も有効な OKF です：バンドル絶対パス（/tables/customers.md。リンク元のファイルが移動しても有効なため、仕様で推奨されている形式）と相対パス（customers.md、../tables/customers.md）です。とはいえ、デフォルトでは相対パスを使用してください。GitHub は絶対パスをリポジトリのルートに対するパスとして解決するため 404 になり、Google の参照ビジュアライザーはそこからエッジを作成せず、Google はまさにこの理由から独自のサンプルバンドルを相対パスに変換しました。リンク元のファイルを移動すると相対リンクは壊れるため、移動後は必ずバリデーターを再実行してください。バリデーターは両方の失敗パターンを報告します。リンクが表すのは関係性であり、その意味はリンク自体ではなく、周囲の文章に記述されます。
• 外部資料。 取り込んだウェブページやドキュメントは、references/<slug>.md に通常の概念として追加し、type: Reference とその URL を resource に指定します。URL だけでなく、その内容を取り込んでください。オフラインでも概念だけで内容が完結するよう、要点を本文に抽出します。resource は再確認のための出典情報であり、知識の代わりではありません。リンク先の参照を前提とする要約はスタブです（/okf export を参照）。

最も適した Markdown 形式を選ぶ

「構造を表す Markdown を優先する」という考え方は、見出しや表にとどまりません。構造を内包する事実には、拡張 Markdown 形式のほうが散文より機械可読性に優れています（エージェントは、辺のリストや数式を解析できますが、それについて説明する段落を解析するわけではありません）。また、バンドルが実際に読まれる場所（GitHub、OKF ビューアー）では、豊かな形式で表示されます。利用側で何も表示されない場合でも、ソースは通常の Markdown として読めるため、移植性に影響はありません。

事実	次の形式で記述	次の形式では記述しない
トポロジー：結合、系譜、パイプラインの流れ、状態	```mermaid フェンス（erDiagram、flowchart、sequenceDiagram）。辺がデータです	矢印について説明する散文の段落
形式的な定義：メトリックの数式、しきい値、ウィンドウ	TeX。インラインなら $…$、ディスプレイなら $$…$$	散文の擬似数式（「数をウィンドウで割る」）
用語の意味：用語集、列挙値、ステータスコード	定義リスト（用語 の後に : 定義）	「X - Y を意味する」のような箇条書き
状態を伴うチェックリスト：ロールアウトや移行の進捗	タスクリスト（- [x] / - [ ]）	「ステップ 1 から 3 は完了」のような散文
1 つの主張を 1 つのソースに帰属させる場合	ラベルが sources エントリの id である脚注（[^ga4-schema]）	括弧内の URL、または対応先のない単独の [^1]
フィールドごとの事実：スキーマ、パラメーター	Markdown の表（すでに慣例となっています）	キーと値を散文で記述

意味や推論には散文を使い、事実に形がある場合はこれらの形式を使ってください。templates.md の作成例では、それぞれの形式を適切な箇所で示しています。

検証

バンドルディレクトリに対して、同梱のチェッカーを実行します。

node okf-validate.mjs path/to/bundle

必須要件（概念にフロントマターがない、または type が空でない）に違反するとエラー（終了コード 1）になり、バンドルがそれらに対応しているため失敗には至らない、推奨事項への違反は警告になります。v0.2 で追加された内容はすべて任意なので、エラーにはなりません。ガイダンスとしてチェックされ、ルートのインデックスで "0.2" を宣言しているバンドルに対して --strict を指定した場合にのみゲートの対象となります。このゲートの対象は、残存する timestamp と # Citations、resource のない sources エントリ、by のない generated、範囲外の status、および runtime がないか計算が行われていない Attested Computation です。v0.1 のバンドルは、どちらの場合でも問題なく検証されます。報告される警告の 1 つに、バンドルのグラフ接続性があります。孤立した概念（概念間リンクの入出力がない概念）と、壊れた概念リンク（予約済みの index.md へのリンクを含め、リンク先が概念ではないリンク）が対象です。--strict を指定すると、これらは失敗として扱われます。エージェントはバンドルをたどっても孤立した概念に到達できず、壊れたリンクもたどれないため、どちらも構造上コンテキストが欠けている状態となり、これは作成者側のゲートとして機能します。説明を編集した後に --drift を指定すると、各インデックスの項目とリンク先の概念の description を比較し、古い主張を示したままの項目を検出します。スクリプトを通過しても、あらゆる場所で正しく表示されるとは限りません。実際の利用側ではアクタープレフィックスやリンク形式の扱いが仕様と異なるため、どこを再確認すべきかは commands.md の差異一覧を参照してください。スクリプトの基になったレビュアー向けチェックリストも、commands.md にあります。

検証で確認するのは適合性であり、網羅性ではありません。 50 ページのサイトを薄いスタブにしたものでも、唯一のルールは各ファイルの type に関するもので、バンドルにソースの内容が取り込まれているかどうかは問わないため、問題なく検証に通ります。ソースからバンドルを作成する（export、enrich）場合、デフォルトの実行は必要ですが、それだけでは不十分です。okf-validate --strict と commands.md の作成ゲートを実行してください。検出されたセクションをすべて網羅すること、概念に実質的な深みを持たせること、根拠を支える名前をすべて個別のリンク付き概念に分解すること（バンドルはソース側の説明が尽きるところではなく、ゲートが示すところで止めます）、孤立した概念や壊れたリンクのない接続済みグラフにすること、そしてクロールの境界があれば log.md に記録することが必要です。デフォルトの okf-validate に通ることと、エクスポートを完了することは同じではありません。

このスキルのファイル

• spec.md。OKF v0.2 の規範的なリファレンス全体（適合性、フィールド、来歴と信頼性、アクター、リンク付け、証明付き計算、バージョニング、v0.1 からの変更点、対象外事項、設計原則）。
• commands.md。各コマンドの一連の手順、対象となるファイル、検証チェックリスト。
• templates.md。コンセプト、ルートの index.md、サブの index.md、log.md のテンプレートに加え、BigQuery テーブル、メトリクス、ランブック、外部参照の記入例。
• writing.md。作成と改訂に共通する、読者の目的、文章、構成、改訂、事実保持に関する取り決め。
• capabilities/。上記のルーターによって選択される、対象を絞った調査、取得、作成、拡充、監査、修復、調査、変更影響分析、移行、執筆、改訂の各手法。
• okf-validate.mjs。依存関係ゼロの適合性チェッカー。

ソース

Open Knowledge Format は Google Cloud が公開しています。仕様：GoogleCloudPlatform/knowledge-catalog。発表記事：How the Open Knowledge Format can improve data sharing。同じリポジトリには、リファレンス作成ツール（拡充エージェント）、リファレンス利用者としての単一ファイル HTML ビジュアライザー、閲覧可能な 4 つのサンプルバンドルも含まれています。spec.md にそれぞれの説明があります。GA4、Stack Overflow、Bitcoin は v0.2 形式で再生成されており、acme_retail は新規で、信頼性シグナル、非推奨のメトリクス、BigQuery を利用した証明付き計算など、v0.2 のすべての機能を試せます。OKF v0.2 は、後方互換性を保ちながら拡張できるよう設計された初期段階の標準です。また、証明ランタイムプロトコル、証明者 ABI、証明のキャッシュ、セマンティックレイヤーのテンプレートについては、後の改訂まで明示的に扱いを保留しています。そのため、これらを独自に作り出さず、仕様を再確認してください。