先に結論
を一通り読んで、一番強く感じたのはこれです。
OKF、つまり Open Knowledge Format は、単なる「ナレッジカタログ」ではありません。
また、RAG 用のドキュメント置き場でもありません。
もっと本質的には、
人間と AI Agent の両方が読める知識を、Markdown + YAML frontmatter という普通のファイルとして表現・交換するためのフォーマット
です。
公式 README では、OKF は knowledge を plain markdown files with YAML frontmatter として表現する universal / vendor-neutral format であり、特定の agent、framework、model provider、serving system に依存しないと説明されています。
短く言うと、
MCP が Agent と外部ツールをつなぎ、A2A が Agent 同士をつなぐなら、OKF は Agent が読む知識そのものをファイル化する
ということです。
OKFとは何か
OKF は、知識をディレクトリ構造の中にある Markdown ファイルとして表現します。
最小イメージはこうです。
my_bundle/
├── index.md
├── datasets/
│ ├── index.md
│ └── sales.md
└── tables/
├── index.md
├── orders.md
└── customers.md
OKF 仕様では、知識の配布単位を Knowledge Bundle、1つの知識単位を Concept と呼びます。Concept は1つの Markdown 文書で表され、テーブル、API、メトリクス、業務プロセス、Playbook など、具体的な資産でも抽象的な概念でもよいとされています。
ここがかなり大事です。
OKF は「データそのもの」を保存する形式ではありません。
保存するのは、データやシステムの周辺にある知識です。
- このテーブルは何を表すのか
- このカラムはどう使うのか
- この API はどんな業務で呼ばれるのか
- このメトリクスはどう解釈するのか
- この障害対応手順はどのリソースに関係するのか
- どのドキュメントが根拠なのか
つまり OKF は、Agent が仕事をするときに必要になる metadata、context、curated insight を扱うためのフォーマットです。
なぜOKFが必要なのか
AI Agent が増えると、次に問題になるのは「Agent がどこから知識を読むか」です。
MCP があれば、Agent はデータベースや API に接続できます。
A2A があれば、Agent は別の Agent に仕事を依頼できます。
Skills があれば、Agent は作業手順を読めます。
でも、それだけでは足りません。
Agent が正しく仕事をするには、外部システムの「意味」を知らないといけません。
たとえば、BigQuery のテーブル一覧だけを見ても、Agent はそのテーブルの業務上の意味を理解できません。
events_
users
transactions
inputs
outputs
posts_questions
posts_answers
名前だけでは分からない。
スキーマだけでも不十分。
過去のドキュメント、例、注意点、関係性、参照元が必要です。
OKF は、そういう知識を Markdown と YAML frontmatter で表します。
仕様では、OKF は人間がツールなしで読め、Agent が専用 SDK なしで parse でき、version control で diff でき、tool / organization / time をまたいで portable である形式を目指すと説明されています。
ここが本質だと思います。
OKF は、ナレッジを「サービスの中」に閉じ込めません。
ナレッジをファイルにします。
Git で管理できます。
Pull Request でレビューできます。
LLM がそのまま読めます。
人間もそのまま読めます。
これはかなり強いです。
OKFは「Markdown + YAML frontmatter」
OKF の中心は、かなりシンプルです。
各 Concept は UTF-8 の Markdown ファイルです。
先頭に YAML frontmatter を置き、その下に Markdown 本文を書きます。
イメージはこうです。
---
type: BigQuery Table
title: Customer Orders
description: One row per completed customer order across all channels.
resource: https://console.cloud.google.com/bigquery?p=acme&d=sales&t=orders
tags: [sales, orders, revenue]
timestamp: 2026-05-28T14:30:00Z
---
# Schema
| Column | Type | Description |
|-------------|---------|-----------------------------------|
| order_id | STRING | Globally unique order identifier. |
| customer_id | STRING | Foreign key into customers. |
| total_usd | NUMERIC | Order total in US dollars. |
# Examples
```sql
SELECT order_id, total_usd
FROM sales.orders
WHERE total_usd > 100;
```
# Citations
[1] BigQuery table schema
ここで注意点があります。
上の例は Markdown の中に Markdown を載せています。
その中にさらに sql のコードブロックがあります。
そのため、外側のコードブロックは 4つのバッククォート で囲っています。
外側: ````
内側: ```
外側も内側も3つのバッククォートにすると、内側の ```sql が外側のブロックを閉じてしまいます。
Qiita に貼ると、# Citations 以降の見出しや本文が崩れる原因になります。
frontmatterは検索・分類用、bodyは意味を書く場所
OKF の設計で良いと思ったのは、structured data と unstructured data の分け方です。
frontmatter には、検索・フィルタ・インデックスに使う小さな情報を書きます。
type: BigQuery Table
title: Orders
description: One row per completed customer order.
resource: https://console.cloud.google.com/bigquery?p=acme&d=sales&t=orders
tags: [sales, orders]
timestamp: 2026-05-28T00:00:00Z
本文には、人間や LLM が本当に読みたい情報を書きます。
# Schema
# Joins
# Examples
# Citations
README でも、OKF は structured and unstructured data を意図的に混ぜると説明されています。frontmatter は query、filter、index に使いたい少数の fields に使い、Markdown body は prose、schemas、example queries のような人間と LLM が実際に読む内容に使う、という整理です。
つまり、こういう分担です。
frontmatter:
検索・分類・機械処理のための最小構造
markdown body:
人間と LLM が読む意味・例・根拠
全部を JSON にすると、人間が読むにはつらい。
全部を文章にすると、検索やフィルタが弱い。
OKF はその中間を狙っています。
index.md は Progressive Disclosure のためにある
OKF には index.md があります。
これは単なる目次ではありません。
Agent が大きな知識バンドルを読むときに、いきなり全部の Markdown を読むと重いです。
そこで、まず index.md を読んで、必要な Concept だけを開きます。
仕様では、index.md は任意のディレクトリに置ける directory listing であり、人間や Agent が個別文書を開く前に何があるかを確認できるようにする progressive disclosure のための仕組みと説明されています。
https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md
これは、Agent Skills や MCP の考え方にも似ています。
全部を最初から読ませない。
必要なものだけ段階的に読む。
Agent:
まず index.md を読む
↓
relevant な directory を選ぶ
↓
その directory の index.md を読む
↓
必要な Concept を開く
OKF は「LLM に全部読ませるフォーマット」ではありません。
「LLM が迷わず辿れるフォーマット」です。
Linkによってナレッジはグラフになる
OKF はディレクトリ構造を持っています。
でも、本質はツリーだけではありません。
Concept 同士は Markdown link でつながります。
Joined with [customers](/tables/customers.md) on `customer_id`.
仕様では、Concept A から Concept B への link は relationship を表すと説明されています。ただし、その関係が parent / child なのか、references なのか、joins-with なのか、depends-on なのかは link 自体ではなく周辺の文章で伝える設計です。
OKF は、厳密なグラフスキーマを最初から定義しません。
その代わり、普通の Markdown link を使います。
tables/orders.md
→ tables/customers.md
→ datasets/sales.md
→ references/schema-doc.md
これにより、ファイルとしては普通の Markdown なのに、Consumer 側ではグラフとして扱えます。
CitationsはAgent時代にかなり重要
OKF には # Citations の考え方があります。
これはかなり重要です。
Agent が知識を使うとき、問題になるのは「それはどこから来た情報か」です。
- 公式ドキュメントなのか
- 社内 Wiki なのか
- 自動推論なのか
- 過去の Issue なのか
- 古い仕様なのか
- 誰かのメモなのか
OKF 仕様では、Concept の本文が外部資料に基づく claim を含む場合、文書末尾の # Citations に sources を番号付きで載せることが推奨されています。
Agent が答えるときだけ citation を付けるのではなく、
Agent が読む知識そのものに citation を持たせる。
この発想はかなり実務向けです。
Conformanceはかなりゆるい
OKF の仕様は、意外と厳しくありません。
OKF v0.1 の conformant bundle であるための条件は、主に次の3つです。
1. 非予約 .md ファイルが parseable YAML frontmatter を持つ
2. frontmatter に non-empty type field がある
3. index.md / log.md がある場合は、それぞれの構造に従う
仕様では、missing optional fields、unknown type values、unknown additional frontmatter keys、broken cross-links、missing index.md files などを理由に bundle を reject してはいけないとされています。
これはかなり重要です。
OKF は、完全なスキーマ準拠を目指していません。
むしろ、
不完全でも読めること
を重視しています。
なぜなら、OKF bundle は人間が書くこともあれば、Agent が生成することもあるからです。
途中で refactor されることもあります。
一部だけ生成されることもあります。
リンク切れが一時的に発生することもあります。
そのたびに Consumer が落ちると、実務では使いにくいです。
reference agent はOKFを作るPoC
このリポジトリには、OKF の reference agent も含まれています。
ただし、ここは誤解しない方がよいです。
README では、agent は OKF bundle を自動生成する1つの方法を示す proof of concept であり、主な contribution は format 自体だと説明されています。
つまり、このリポジトリの主役は agent ではありません。
主役は OKF です。
reference agent は、OKF を作る側の例。
visualizer は、OKF を読む側の例。
この両端を見せることで、「このフォーマットは実際に作れて、実際に読める」ということを示しています。
reference agent は2段階で動く
reference agent の動きはかなり分かりやすいです。
1. BigQuery pass
BigQuery metadata から Concept document を作る
2. Web pass
seed URL を起点に、LLM が crawler として公式ドキュメントを読み、
既存 Concept を enrich する、または references/ doc を作る
README では、BQ pass は BigQuery metadata だけを使って source が持つ concept ごとに OKF doc を書き、web pass では LLM が crawler として seed URL を受け取り、fetch_url tool でページを取得し、既存 concept に対する authoritative documentation らしい outbound link を辿ると説明されています。
さらに、web pass では取得したページごとに、
a. 既存 Concept document を enrich する
b. references/<slug> doc を作る
c. skip する
のいずれかを選びます。
Agent に自由に Web を読ませるのではなく、seed、allowed host、page cap で囲う。
そして、読んだ結果を OKF というファイル形式に落とす。
これは実務で真似しやすい設計です。
Samplesが3つある
このリポジトリには、実際に生成済みの OKF bundle が3つ入っています。
README では、ready-to-browse bundle として GA4、Stack Overflow、Bitcoin の3つが紹介されています。
| Sample | 何を示すか |
|---|---|
| GA4 Google Merchandise Store | GA4 BigQuery Export documentation を seed に、e-commerce dataset の知識を作る |
| Stack Overflow | Stack Exchange community の schema references を seed に、複数 table を横断して enrichment する |
| Bitcoin crypto dataset | blocks / transactions / inputs / outputs の関係を prose と link で表す |
この3つの sample はよくできています。
単純な1テーブル例だけではなく、
- denormalized events table
- 多数の独立 entities
- 強く関連する fact tables
という違うパターンを見せています。
VisualizerはOKF ConsumerのPoC
OKF は Markdown なので、普通に GitHub で読めます。
でも、それだけではグラフ構造や backlinks は見えにくいです。
そこで visualizer があります。
README では、visualize subcommand は任意の OKF bundle を self-contained interactive HTML file として render でき、見る側に backend や install は不要だと説明されています。
Visualizer が見せるものは、主に次です。
- Concept 全体の force-directed graph
- type ごとの色分けノード
- Markdown link から作った directed edge
- frontmatter と rendered Markdown body
- backlinks の “Cited by”
- search box
- type filter
- graph layout 切り替え
OKF は「サービス」ではない。
でも、サービスっぽく可視化することはできる。
Consumer は自由です。
- GitHub
- Obsidian
- MkDocs
- Notion
- search index
- graph viewer
- LLM context loader
どれでもよい。
OKF の価値は、特定の UI ではなく、普通のファイルとして読めることです。
OKFはMetadata as Codeに近い
OKF を一言で分類するなら、自分は Knowledge as Code か Metadata as Code に近いと思いました。
仕様でも、OKF は LLM wiki repositories、Obsidian / Notion のような hierarchical markdown with cross-links、catalog metadata を source code と一緒に置く Metadata as Code approaches に近いと説明されています。違いは、OKF が interoperability に必要な小さなルールを仕様化している点です。
単に Markdown を置くだけなら、誰でもできます。
でも、それだけだと Agent が安定して読みにくいです。
OKF は、そこに最低限のルールを入れます。
- Concept は Markdown file
- 先頭に YAML frontmatter
- type は必須
- index.md は progressive disclosure
- log.md は履歴
- Markdown link は関係性
- # Citations は根拠
- Consumer は unknown field や broken link に寛容である
この小さな仕様化が、Agent 時代には効いてくると思います。
Skills / MCP / Plugin / A2A / AG-UI / OKF の関係
ここまで書いてきたシリーズと並べると、OKF の位置づけはこうです。
| 技術 | 本質 | 何を扱うか |
|---|---|---|
| Agent Skills | 作業手順 | Agent がどう仕事するか |
| MCP | 外部接続 | Agent が tools / data にどう接続するか |
| Codex Plugin | 配布 | Skills / Apps / MCP をどう配るか |
| A2A | Agent間通信 | Agent が他の Agent にどう委任するか |
| AG-UI | ユーザー体験 | Agent の状態を UI にどう出すか |
| OKF | 知識フォーマット | Agent と人間が読む知識をどう保存・交換するか |
もう少し実務っぽく言うと、こうです。
Agent Skills:
この仕事は、こう進める
MCP:
この外部ツール・データには、こう接続する
Codex Plugin:
これらをチームに配れる形にまとめる
A2A:
他の Agent に仕事を依頼する
AG-UI:
Agent の進行状況と承認をユーザー UI に出す
OKF:
Agent が読む業務知識・メタデータ・根拠をファイルとして持つ
この中で、OKF は通信プロトコルではありません。
MCP や A2A のように request / response を決めるものではありません。
AG-UI のように event stream を決めるものでもありません。
Plugin のように配布パッケージを決めるものでもありません。
OKF は、Agent が参照する知識をどう持つかを決めます。
つまり、Agent 基盤の中では Knowledge Layer です。
OKFとRAGの違い
OKF は RAG と関係します。
でも、OKF は RAG そのものではありません。
RAG は、検索して、関連文書を context に入れて、回答する仕組みです。
OKF は、その検索対象となる知識を、どんな形式で持つかの話です。
RAG:
どう検索して、どう LLM に渡すか
OKF:
そもそも知識をどんなファイルとして保存するか
OKF bundle は search index に入れてもよいです。
LLM が直接読んでもよいです。
Graph viewer で見てもよいです。
Obsidian で編集してもよいです。
README でも、OKF は static file server、knowledge-management UI、LLM loading files into context、search index、graph viewer などで serve / consume できると説明されています。
つまり OKF は、RAG pipeline の前段にある 知識の形 です。
OKFとMCPの組み合わせ
OKF と MCP はかなり相性がよいと思います。
MCP は Agent に外部 data / tools / resources を渡す仕組みです。
OKF は Agent が読む knowledge bundle の形式です。
たとえば、OKF bundle を読む MCP server を作るとします。
MCP Server: okf-server
tools:
search_concepts(query)
read_concept(concept_id)
list_concepts(type)
get_backlinks(concept_id)
resources:
okf://bundle/index
okf://bundle/tables/orders
okf://bundle/references/ga4-export-schema
こうすると、Agent は MCP 経由で OKF を段階的に読めます。
まず index.md を読む。
必要な Concept を検索する。
Concept を開く。
backlinks を見る。
citation を辿る。
OKF はファイル形式なので、MCP server の実装も比較的シンプルにできます。
OKFとAgent Skillsの組み合わせ
Agent Skills は「作業手順」です。
OKF は「知識」です。
この2つは分けた方がよいです。
たとえば、データ分析 Agent を考えます。
Skill:
BigQuery dataset を調査して分析レポートを作る手順
OKF:
各 dataset / table / metric / playbook の知識
Skill に全部のテーブル説明を書くと、すぐに巨大になります。
でも OKF にテーブル知識を分ければ、Skill は手順に集中できます。
Skill:
1. OKF bundle の index.md を読む
2. 関係する Concept を探す
3. Schema / Examples / Citations を確認する
4. BigQuery に問い合わせる
5. 分析結果に citation を付ける
この方がきれいです。
Skills は workflow。
OKF は knowledge base。
OKFで失敗しやすいところ
1. 何でもMarkdownにすればOKだと思う
OKF は Markdown ですが、ただの Markdown 集ではありません。
最低限、frontmatter、type、index、links、citations の設計が必要です。
特に type が雑だと、Consumer が扱いにくくなります。
悪い例です。
type: doc
良い例です。
type: BigQuery Table
または、
type: Metric
type は中央登録されません。仕様でも、type values は central registry に登録されず、producer は descriptive and self-explanatory な値を選び、consumer は unknown type を許容するべきだとされています。
2. bodyを自由作文にしすぎる
OKF の body は自由です。
でも、自由すぎると Agent が読みづらくなります。
仕様では、body は standard markdown であり、freeform prose よりも headings、lists、tables、fenced code blocks のような structural markdown を優先することが推奨されています。
つまり、こういう構造がよいです。
# Schema
# Joins
# Examples
# Gotchas
# Citations
LLM は文章も読めます。
でも、構造化された Markdown の方が安定して読めます。
3. index.md を軽く見る
小さい bundle なら、index.md なしでも読めます。
でも、Concept が増えると index.md が重要になります。
Agent にとって index.md は目次です。
人間にとっても目次です。
Visualizer や search index を作るときにも便利です。
4. Citationを後回しにする
OKF は knowledge format なので、根拠が重要です。
最初に Citation を設計しないと、後から「この情報どこから来た？」となります。
特に Agent が生成した OKF では、citation が弱いと信頼性が落ちます。
5. 完璧なスキーマを作ろうとする
OKF は、完璧な統一 taxonomy を作るものではありません。
仕様でも、fixed taxonomy of concept types を定義すること、storage / serving / query infrastructure を規定すること、Avro / Protobuf / OpenAPI のような domain-specific schema を置き換えることは non-goals とされています。
ここは重要です。
OKF は全部を支配するフォーマットではありません。
既存の schema や catalog を参照しながら、Agent と人間が読める知識レイヤーを作るものです。
今からOKFを試すなら、こう始める
最初から reference agent を動かさなくてもよいと思います。
まずは、小さい bundle を手で作るのがよいです。
my_okf_bundle/
├── index.md
├── tables/
│ ├── index.md
│ └── orders.md
├── metrics/
│ ├── index.md
│ └── monthly_revenue.md
└── playbooks/
├── index.md
└── incident_response.md
1つ目の Concept は、こんな感じで十分です。
---
type: BigQuery Table
title: Orders
description: One row per completed customer order.
resource: bigquery://acme.sales.orders
tags: [sales, orders, revenue]
timestamp: 2026-06-29T00:00:00Z
---
# Schema
| Column | Type | Description |
|-------------|---------|-------------------------|
| order_id | STRING | Unique order identifier |
| customer_id | STRING | Customer identifier |
| total_usd | NUMERIC | Order amount in USD |
# Joins
Joined with [Customers](/tables/customers.md) on `customer_id`.
# Examples
```sql
SELECT COUNT(*) AS orders
FROM `acme.sales.orders`
WHERE DATE(placed_at) = CURRENT_DATE();
```
# Citations
[1] Internal BigQuery schema
この時点で、もう OKF です。
その後に、
-
index.mdを追加する -
references/を作る -
# Examplesを増やす -
# Gotchasを追加する -
# Citationsを整える - MCP server で読めるようにする
- GitHub PR でレビューする
- Visualizer を作る
という順番で育てるのがよいと思います。
まとめ
OKF は、AI Agent 時代のかなり重要なフォーマットになりそうです。
ただし、本質は「ナレッジを管理すること」ではありません。
本当に大事なのは、
- 知識を Markdown + YAML frontmatter で表す
- 人間と Agent が同じファイルを読む
- Git でレビュー・diff・履歴管理できる
- frontmatter は検索・分類に使う
- body は意味・例・根拠を書く
- index.md で progressive disclosure する
- Markdown link で知識をグラフにする
- citation で根拠を残す
- Consumer は不完全な bundle にも寛容に読む
という点です。
Agent Skills は、AI に仕事のやり方を渡します。
MCP は、AI と外部 tools / data をつなぎます。
Codex Plugin は、それらを配布可能にします。
A2A は、Agent 同士をつなぎます。
AG-UI は、Agent とユーザー体験をつなぎます。
OKF は、Agent と人間が共有する知識をファイルとして残します。
これから AI Agent を実務で使うなら、モデルやツールだけでは足りません。
重要になるのは、
Agent が読む知識を、誰が見ても編集でき、どのシステムにも持ち運べる形で残すこと
だと思います。
OKF は、そのためのかなりシンプルで強い選択肢です。