OKF

散らばったドキュメント、データベース構造、業務ロジックなどの社内知識を共通の形式でパッケージ化し、AIエージェントに正確な文脈（コンテキスト）を伝えるための標準規格として策定された。

OKFの最大の特徴は、独自のランタイムや高度なSDKを必要とせず、広く普及している既存のテキスト形式を組み合わせている点にある。

最小構成のデータ構造（ファイル単位）

OKFにおける1つの概念（Concept）は、UTF-8形式のMarkdownファイルで記述され、以下の2つの要素のみで構成される。

• YAML Frontmatter：ファイルの先頭に記述する構造化されたメタデータデータブロック
  • 必須フィールド: type（概念の種別、例：Table, Articleなど）の1つのみ
  • 推奨オプション: title（タイトル）、description（概要）、resource（参照元URL/URI）、tags（タグ）、timestamp（タイムスタンプ）など
• Markdown Body：人間が読み、LLM（大規模言語モデル）が理解するための自由形式の本文。従来のMarkdown同様、見出しやソースコードブロック、表などをそのまま使用。

OKFバンドル（ディレクトリ構造）

これらのMarkdownファイルを格納した1つのディレクトリ階層をOKFバンドルと呼ぶ。

ファイル間は、通常のMarkdownの相対パス・絶対パスのリンクを用いて相互参照。これらがリンクし合うことで、フォルダ全体が自律的な知識グラフ（ナレッジグラフ）として機能。

予約ファイル

バンドルのルートや各ディレクトリを整理するために、以下の2つの特殊なファイル名が予約されている。

• index.md：ディレクトリ内のコンテンツ一覧（目次）を記述するファイル
• log.md：更新履歴や変更ログを記述するファイル

設計における3つの主要原則

OKFは、従来の複雑なスキーマ（メタデータ管理）の課題を解決するため、以下の原則に沿って極めて軽量に設計されている。

• 極限のシンプルさ：必須項目をtypeのみに絞ることで、プログラムでのパースが容易でありながら、手動での記述（ObsidianやNotion、GitHubのMarkdown等）や既存ツールとの高い親和性を保っている
• エラーへの高い寛容性（Soft Conformance）: 適合条件として「未定義のメタデータキー」や「リンク切れ」があっても、消費側（AIエージェント）はエラーで処理を中断せず、ベストエフォートで情報を読み込むことが仕様として規定
• ポータビリティ: 特定のクラウド、特定のAIモデル、特定のデータベース製品に依存しません。GitリポジトリやZipアーカイブとして簡単に配布・変更履歴管理（Diff）が可能

サンプル

AIエージェントに「このテーブルには何が入っていて、どう使えばいいか」を教えるための定義ファイルrevenue_table.md の例。

---
type: Table
title: 2026年度 顧客売上集計テーブル
description: BigQuery上の顧客ごとの月次売上データを格納した本番環境テーブル
resource: bq://my-gcp-project.sales_dataset.monthly_customer_revenue
tags:
  - sales
  - finance
  - production
timestamp: 2026-06-15T09:00:00Z
---

# 顧客売上集計テーブル (`monthly_customer_revenue`)

このテーブルは、毎月1日の午前3時（JST）にバッチ処理によって更新されます。財務レポートや営業ダッシュボードのソースデータとして使用してください。

## 主なカラム（列）
* **`customer_id`** (STRING): 顧客の一意の識別子。`crm_users` テーブルと結合可能です。
* **`total_amount`** (NUMERIC): 当月の税抜き合計売上金額。
* **`currency`** (STRING): 通貨コード（例: `JPY`, `USD`）。

## AIエージェントへの指示（クエリ時の注意点）
> ⚠️ **注意**: 返金処理された取引は `total_amount` に**含まれていません**。正確なネット売上を計算する場合は、別ファイルの [返金ルール定義](./refund_policy.md) を参照して減算ロジックを組んでください。

## サンプルSQL
```sql
SELECT 
  customer_id, 
  SUM(total_amount) AS annual_revenue 
FROM 
  `my-gcp-project.sales_dataset.monthly_customer_revenue`
WHERE 
  currency = 'JPY'
GROUP BY 
  customer_id;
```

AIエージェントが顧客からの質問に答えたり、データ分析をしたりする際の社内ルールを教える定義ファイル refund_policy.md の例。

---
type: Article
title: 返品・返金に関する業務規程
description: ECサイトにおけるユーザーへの返金条件とシステム上のステータス管理
tags:
  - policy
  - support
timestamp: 2026-05-10T12:00:00Z
---

# 返品・返金に関する業務規程

当社ECサービスにおける、商品の返品および返金に関する基本ルールです。AIカスタマーサポートエージェントは、このルールに基づいて顧客対応を行ってください。

## 返金条件
1. 商品到着後 **14日以内** の申請であること。
2. 商品が未使用、または初期不良であること。

## データ上の扱い
返金が承認されると、基幹データベースの `orders` テーブルの `status` カラムが `'REFUNDED'` に変更されます。

詳細なデータ構造は [顧客売上集計テーブル](./revenue_table.md) の参照データと連携しています。

Skillsとの関係

SkillsはAIエージェントに「どのように作業を実行するか」を教えるための形式であり、手順やノウハウなどの手続き知識を記述する。一方、OKF（Open Knowledge Format）はAIエージェントに「何を知っておくべきか」を与えるための形式であり、業務ルールや製品情報などの宣言的知識を記述する。したがって、Skillsが行動の方法を定義するのに対し、OKFは参照すべき知識そのものを定義する。両者は競合するものではなく、AIエージェントの能力と知識をそれぞれ補完する関係にある。

skillsの構造例

my-skill/
├── SKILL.md
├── scripts/
├── templates/
└── references/

OKFの典型的構造

knowledge/
├── customers/
│   └── customer_rank.md
├── products/
│   └── product_catalog.md
└── finance/
    └── revenue_definition.md

skillsとOKFの構造例

Agent
 ├─ Skills
 │   ├─ report-generation
 │   ├─ sql-analysis
 │   └─ troubleshooting
 │
 └─ OKF
     ├─ finance/
     ├─ products/
     └─ operations/

Mathematics is the language with which God has written the universe.