okf

OKF — Open Knowledge Format

Open Knowledge Format (OKF) は、Google Cloud Data チームが提案するオープンな仕様で、LLM-Wiki パターンを移植可能で相互運用可能な形式として定義します。ナレッジは、ディレクトリ内の YAML フロントマター付き Markdown ファイル（「バンドル」）として保存されます。どのような生成元でも書き込め、どのエージェントでも利用できます。独自の SDK も、特別なランタイムも、ベンダーロックインもありません。

基本理念：Markdown だけ。ファイルだけ。YAML フロントマターだけ。

このスキルを使用する場面

• AI エージェントが解析できる構造化ナレッジドキュメント（テーブルスキーマ、API 仕様、メトリクス定義、運用手順書、非推奨の通知など）を作成する必要がある
• ツールの変更後も維持できる移植可能なナレッジバンドルを作成したい（ベンダーカタログへの依存なし）
• 異なるシステムが同じ組織ナレッジ（結合パス、ビジネス KPI、インシデントガイド）を必要とするマルチエージェントのコンテキストレイヤーを構築している
• ナレッジアトム同士を相互リンクし、親子階層で表現できる範囲を超えた、より豊かな関係グラフを構築したい
• tarball、git リポジトリ、ファイルシステムマウントとしてナレッジを公開または配布する必要がある
• LLM-wiki の出力を OKF v0.1 標準に正式に準拠させたい

このスキルを使用しない場面

• 生の Web ソースの取り込みや、ボルトレベルの Wiki メンテナンス → llm-wiki
• Obsidian ボルトの自動化（プラグイン開発、CLI、URI ハンドオフ） → obsidian
• コードやドキュメントから永続的なコミット済みナレッジグラフを作成する → graphify
• ナレッジドキュメントに取り込むための Web スクレイピング → scrapling
• 独立した okf-memory/okf-agent-memory Go CLI/MCP の運用、または OKF v0.2 のプロジェクトメモリレイアウトの初期設定 → okf-agent-memory

OKF の構造

バンドルディレクトリ

knowledge-bundle/
├── tables/
│   ├── orders.md
│   └── customers.md
├── metrics/
│   └── wau.md
├── runbooks/
│   └── outage-response.md
└── concepts/
    └── revenue-calculation.md

各ファイルはナレッジアトムです。YAML フロントマター付きの Markdown ドキュメントが 1 つ入ります。 ディレクトリ自体が配布単位です（tarball / git / ファイルシステムマウント）。

フロントマターのスキーマ（OKF v0.1）

---
type: <string>          # (required) kind of atom: "BigQuery Table", "API Endpoint",
                        #   "Concept", "Runbook", "Metric Definition", "Data Source", …
title: <string>         # (required) human-readable name
description: <string>   # (required) one-sentence summary the agent can quote verbatim
resource: <url>         # (optional) URL to the described resource
tags: [<tag>, …]        # (optional) list for filtering / discovery
timestamp: <ISO 8601>   # (optional) last-updated datetime, e.g. 2026-06-21T10:00:00Z
---

type、title、description のみが厳密な必須項目です。 アトムが稼働中のシステムまたは URL に紐付いている場合は、resource を追加してください。 timestamp を使用すると、利用するエージェントが最新性を確認できます。

Markdown 本文のセクション

セクション	目的
# Overview	自由形式のコンテキスト — 背景、所有者、注意事項
# Schema	カラム／フィールド／パラメーターの構造的な説明（テーブル形式を推奨）
# Examples	具体的な使用例。主にコードブロック
# Joins / # Relations	関連するアトムへの相互リンク
# Citations	ドキュメントの主張を裏付ける外部ソース

セクションは任意です。アトムの種類に関連するものだけを含めてください。

手順

ステップ 1 — バンドルを初期化する

# Create the bundle root
mkdir my-knowledge-bundle && cd my-knowledge-bundle

# Scaffold a directory layout
mkdir -p tables metrics runbooks concepts api

既存のプロジェクトでは、バンドルをコードと同じ場所に置くか、独立したリポジトリに配置します。

my-project/
├── src/
├── docs/
└── knowledge/          ← OKF bundle lives here
    ├── tables/
    └── metrics/

ステップ 2 — ナレッジアトムを作成する

テーブルアトムの例

---
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-06-21T10:00:00Z
---

# Overview

Primary fact table for order analytics. Owned by the Data Engineering team.
Refreshed hourly from the Kafka `orders` topic.

# Schema

| Column        | Type      | Description                                          |
|---------------|-----------|------------------------------------------------------|
| `order_id`    | STRING    | Globally unique order identifier.                    |
| `customer_id` | STRING    | Foreign key into [customers](/tables/customers.md).  |
| `total_usd`   | NUMERIC   | Order total in US dollars after discounts.           |
| `placed_at`   | TIMESTAMP | When the customer submitted the order (UTC).         |
| `channel`     | STRING    | `web` \| `mobile` \| `api` \| `partner`.             |

# Joins

- Join to [customers](/tables/customers.md) on `customer_id` for user attributes.
- Join to [products](/tables/products.md) via [order_items](/tables/order_items.md).

# Citations

[1] [BigQuery table](https://console.cloud.google.com/bigquery?p=acme&d=sales&t=orders)

メトリクス定義アトム

---
type: Metric Definition
title: Weekly Active Users (WAU)
description: Count of distinct users who triggered at least one qualifying event in the trailing 7-day window.
tags: [kpi, growth, users]
timestamp: 2026-06-21T10:00:00Z
---

# Overview

Owned by the Growth Analytics team. Used in all executive dashboards.

# Definition

```sql
SELECT
  DATE_TRUNC(event_date, WEEK) AS week_start,
  COUNT(DISTINCT user_id)      AS wau
FROM [events](/tables/events.md)
WHERE event_name IN ('session_start', 'purchase', 'share')
  AND event_date >= DATE_SUB(CURRENT_DATE(), INTERVAL 7 DAY)
GROUP BY 1
\```

# Relations

- Source table: [events](/tables/events.md)
- Related metric: [Monthly Active Users (MAU)](/metrics/mau.md)

運用手順書アトム

---
type: Runbook
title: Database Connection Pool Exhaustion
description: Steps to diagnose and recover from connection pool exhaustion on the primary Postgres cluster.
tags: [incident, database, postgres, oncall]
timestamp: 2026-06-21T10:00:00Z
---

# Overview

Triggered when `pg_stat_activity` shows ≥95% pool utilization or `FATAL: remaining connection slots are reserved` errors appear.

# Steps

1. Check active connections: `SELECT count(*) FROM pg_stat_activity;`
2. Identify blocking queries: see [slow-query runbook](/runbooks/slow-queries.md).
3. Kill idle connections older than 5 min if count > threshold.
4. Scale pool via [connection pooler config](/concepts/pgbouncer-config.md).
5. Page DBA on-call if not resolved in 10 min.

# Citations

[1] [PgBouncer docs](https://www.pgbouncer.org/)

ステップ 3 — アトム同士を相互リンクする

バンドルルートからの絶対リンクを使用します（推奨 — 移動後も安定します）。

See the [customers table](/tables/customers.md) for join key details.

同じ場所にあるファイルには、相対リンクを使用します。

See [related concept](./other-concept.md).

設計ルール：リンクは関係が存在することを示します。関係の種類（親、外部キー、結合、依存先）を示すのは、リンク自体ではなく、その前後の文章です。これにより、グラフの型を固定せず、利用側が柔軟に扱えるようになります。

ステップ 4 — バンドルを検証する

利用または配布の前に、基本的な構造の lint を実行します。

# Check all .md files have required frontmatter fields
python3 -c "
import os, sys
import re

bundle = '.'  # path to bundle root
errors = []

for root, dirs, files in os.walk(bundle):
    for f in files:
        if not f.endswith('.md'):
            continue
        path = os.path.join(root, f)
        text = open(path).read()
        if not text.startswith('---'):
            continue  # skip non-OKF files
        fm_end = text.find('---', 3)
        if fm_end == -1:
            errors.append(f'{path}: unclosed frontmatter')
            continue
        fm = text[3:fm_end]
        for field in ('type:', 'title:', 'description:'):
            if field not in fm:
                errors.append(f'{path}: missing required field {field!r}')

if errors:
    for e in errors: print('ERROR:', e)
    sys.exit(1)
else:
    print('OK — all OKF files valid')
"

ステップ 5 — バンドルを配布する

# As a tarball
tar -czf my-knowledge-bundle.tar.gz my-knowledge-bundle/

# As a git repo (recommended for versioning + freshness via timestamp)
git init my-knowledge-bundle && cd my-knowledge-bundle
git add . && git commit -m "Initial OKF bundle"
git remote add origin https://github.com/acme/knowledge-bundle.git
git push -u origin main

# As a filesystem mount in a Docker container
# docker run -v $(pwd)/my-knowledge-bundle:/knowledge ...

ステップ 6 — AI エージェントからバンドルを利用する

import os, re, yaml

def load_okf_bundle(bundle_path: str) -> list[dict]:
    """Load all OKF atoms from a bundle directory."""
    atoms = []
    for root, _, files in os.walk(bundle_path):
        for f in files:
            if not f.endswith('.md'):
                continue
            path = os.path.join(root, f)
            text = open(path).read()
            if not text.startswith('---'):
                continue
            fm_end = text.find('---', 3)
            if fm_end == -1:
                continue
            try:
                fm = yaml.safe_load(text[3:fm_end])
                body = text[fm_end + 3:].strip()
                atoms.append({
                    'path': os.path.relpath(path, bundle_path),
                    'frontmatter': fm,
                    'body': body
                })
            except Exception:
                pass
    return atoms

# Usage
atoms = load_okf_bundle('./knowledge')
tables = [a for a in atoms if a['frontmatter'].get('type') == 'BigQuery Table']

ステップ 7 — llm-wiki と統合する

OKF バンドルは、リポジトリの llm-wiki スキルのワークフローと互換性があります。

# After running llm-wiki to capture raw sources, promote to OKF-compliant format:
# 1. Add required frontmatter (type, title, description) to each wiki/*.md
# 2. Add resource: field pointing to the source URL
# 3. Organize into typed subdirectories (tables/, metrics/, concepts/, …)
# 4. Run the Step 4 validator

# Use the llm-wiki skill for:
#   - Raw source capture and summarization
#   - Query filing and lint passes
#   - Obsidian/git vault maintenance

# Use OKF for:
#   - Portable, interoperable distribution to other teams/agents
#   - Standard frontmatter that consuming agents can parse without a custom schema

ステップ 8 — プラグインをインストールする

# Project install
npx skills add https://github.com/akillness/jeo-skills --skill okf

# Global install
npx skills add -g https://github.com/akillness/jeo-skills --skill okf

# Target specific agents
npx skills add -g https://github.com/akillness/jeo-skills --skill okf -a claude-code -a codex -y

また、scripts/install.sh も同梱されています。これは pyyaml の依存関係を確認し、既存のバンドルを任意で検証するワンショットヘルパーです。 フィールドとセクションの全リファレンスについては、references/usage.md を参照してください。

出力形式

ユーザーが okf にヘルプを求めた場合は、簡潔な概要を返します。

# OKF Routing Brief

## Scope
- Task: create-bundle | author-atom | validate | distribute | consume | migrate-from-llm-wiki
- Atom type: table | metric | runbook | concept | api-endpoint | other

## Recommended next move
- bootstrap-bundle | author-atom | validate | distribute | consume | llm-wiki-promote

## Why
- 2-3 bullets grounded in the user's request

## Route-outs
- `llm-wiki` for raw source capture and vault maintenance
- `obsidian` for Obsidian vault automation
- `graphify` for durable committed knowledge graphs
- `scrapling` for web-content extraction into OKF documents

ベストプラクティス

1. 1つのアトムに1つの概念 — 各ファイルでは、テーブル、メトリクス、API エンドポイント、ランブック、概念のいずれか1つだけを扱います。範囲が1つのトピックを超える場合は分割します。
2. description はエージェントの見出し — エージェントが追加の文脈なしで回答にそのまま引用できるように記述します。
3. 相対リンクより絶対リンク — /tables/customers.md はファイルを移動しても有効ですが、../tables/customers.md は気づかないうちにリンク切れになります。
4. 本番アトムにはすべてタイムスタンプを付ける — タイムスタンプがあれば、利用するエージェントは古いアトムをスキップできます。タイムスタンプがないと、新しさを検出できません。
5. type は列挙型ではなく自由形式の文字列 — "BigQuery Table"、"Kafka Topic"、"REST API"、"Runbook"、"Metric" はすべて有効です。バンドル内で一貫して選び、規約をルートの README.md に記載します。
6. 配布前に検証する — Step 4 のリンターを実行します。frontmatter が壊れていると、下流のエージェントで利用時にエラーが通知されないまま失敗します。
7. 新しさを把握するため Git で追跡する — Git リポジトリがあれば、利用者はコミット日時で古さを検出し、標準の git pull で差分を受け取れます。

参考資料

• OKF 仕様：https://github.com/google/open-knowledge-format
• PyTorchKR のディスカッション（韓国語）：https://discuss.pytorch.kr/t/open-knowledge-format-okf-google-ai-feat-llm-wiki/10701
• LLM-Wiki パターン：llm-wiki スキル（../llm-wiki/SKILL.md）を参照してください
• Obsidian 連携：obsidian スキル（../obsidian/SKILL.md）を参照してください
• ナレッジグラフ：graphify スキル（../graphify/SKILL.md）を参照してください
• OKF へのウェブスクレイピング：scrapling スキル（../scrapling/SKILL.md）を参照してください
• ローカルでの使用方法：references/usage.md
• ローカルインストーラー：scripts/install.sh