okf-wiki

okf-wiki：Open Knowledge Format のナレッジベースをひな形から作成する

OKF（Open Knowledge Format）では、知識を小さな Markdown ファイルとして保存します。ファイルごとに1つの概念を扱い、それぞれに YAML フロントマターで来歴を記録します。ナビゲーション用にディレクトリ内に index.md ファイルを配置し、仕様を満たしているか検証するバリデーターを備えています。人とエージェントの両方が読み書きするナレッジベース、ニュースルームの組織的記憶、リサーチアトラス、チームの意思決定ログ、インフラマップを想定して作られています。

このスキルは、仕様に準拠した OKF プロジェクトをひな形から作成し、検証します。形式の仕様は spec/SPEC.md（このスキルのディレクトリ内）にあります。構成を変更する前に読んでください。

使用する場面

• OKF のナレッジベース、アトラス、Wiki を始めたい場合。
• 来歴を記録した、1ファイルにつき1つの概念という構成でドキュメントを整理したい場合。散文形式のページではなく、構造化された形式を求めている場合。
• リポジトリで「OKF を初期化」し、必要に応じて GitHub Wiki に公開したい場合。

まずはここから：ユーザーとウィキの範囲を決める

何かをひな形から作成する前に、ユーザーと4つのことを決めます。これらは作成するものと公開方法を左右し、概念ができた後で変更するのは面倒です。ユーザーに質問し、明確な回答を待ってください。クライアントに構造化された質問ツールがある場合は、それを使います。質問は2段階に分けます。最初に3つの質問をまとめて行い、その後、対象読者が公開または両方の場合に限り、公開方法について質問します（内部専用のウィキには該当せず、関連する選択肢もその回答によって変わるため、最初の質問群には含められません）。リポジトリまたはプロジェクトからタイトルを推測して確認します。ユーザーが依頼の中ですでに回答している質問は省き、伝えられた内容を再度尋ねないでください。

1. 対象読者：このウィキを読むのは誰ですか？この回答が、ほかの項目の方針を決めます。
   • 内部（エージェントとチームメイト）： オリエンテーション用のフックが役立つので、有効のままにします。バンドルにはインフラの詳細が含まれることがあるため、通常はプライベートリポジトリに置きます。リポジトリ内の bundle/ が信頼できる情報源です。
   • 公開（閲覧する人）： 読みやすさと秘密情報の除去を優先します。人が読むものであり、エージェントは読まないため、フックの重要性は低くなります。公開ビューを用意する計画を立ててください（下記の「公開」を参照）。
   • 両方： リポジトリ内の bundle/ を信頼できる情報源として、エージェント向けのフックを有効にしつつ、人向けの公開ビューも用意します。ユーザーが迷っている場合は、こちらを既定にします。
2. タイトルとセクション：ナレッジベースのタイトル（推測してから確認します）と、最初に用意するセクションです。空欄のまま尋ねるのではなく、ユースケースに応じたプリセットを提示します。
   • ニュースルームの組織的な記憶：people, orgs, sources, decisions, beats
   • リサーチアトラス：concepts, sources, methods, findings
   • インフラまたはフリートのマップ：machines, services, networks, credentials, processes
   • 意思決定ログ：decisions, context, events 選択したタイトルとリストを、以下の --title と --sections に渡します。リストはユーザーが編集できます。
3. 今すぐ入力するか、後で入力するか：既存の資料（リポジトリ、ドキュメント、メモ、または URL）をもとに今すぐ概念を作成するか（資料を収集し、ひな形作成後に執筆のループに入ります）、または空のツリーを作成し、後でユーザーが入力するかを決めます。
4. 公開先：対象読者が公開または両方と決まった後にのみ行う追加の質問です（内部専用のウィキの場合は完全に省きます）。
   • リポジトリ内のバンドルのみ（既定）： バリデーターと相対リンクがそのまま機能し、管理対象を増やさずに済みます。ほとんどのウィキに適しています。
   • GitHub Wiki： 読むための任意の場所です。上級者向けの手動設定については、以下の「オプション：GitHub Wiki に公開する」を参照してください。scripts/gh-wiki-bootstrap.py で初期設定します。
   • GitHub Pages： バンドルからレンダリングされる閲覧可能なサイトです。まだ構築されていないため、目標として扱い、リポジトリ内のバンドルを信頼できる情報源として維持してください。

回答をひな形作成コマンド（タイトルとセクション、および公開専用ウィキでユーザーがフックを使わない場合は --no-hooks）と、入力の手順に反映します。対象読者の回答は、「完了前に」のセクションで意図的に決めるよう求められる公開範囲でもあります。後続の設定に反映できるよう、ここで最初に決めておきます。

作成されるもの

scripts/scaffold.py は、作成時点で独自のバリデーターに合格するプロジェクトを書き出します。

<target>/
  SPEC.md                 the OKF format contract
  README.md               how to use and validate the bundle
  scripts/validate.py     the validator
  .claude/                optional Claude Code adapter: session-orientation hooks
    settings.json         registers the hooks (Claude Code approves them once)
    hooks/okf-anchor.py   SessionStart: load the index into context
    hooks/okf-orient.py   PreToolUse: gate the first action on orientation
  bundle/                 the OKF bundle (the validated tree)
    index.md              carries okf_version: "0.3" by default; "0.4" with --trust-signals
    <section>/
      index.md
      example-concept.md  a starter concept with full frontmatter

ドキュメントとツールはプロジェクトのルートに置き、検証対象は bundle/ のみです。これらは分けてください。バリデーターは、バンドル内の予約されていないすべての .md ファイルを、フロントマターが必要な概念として扱います。そのため、bundle/ 内に誤って置かれた SPEC.md があると検証に失敗します。.claude/ アダプターは bundle/ の外にあるため、概念のチェックに引っかかることはありません。

実行方法

インストール済みスキルディレクトリの外部に、明示的なターゲットを指定します。Windows では、標準の Windows 環境に python3 がないため、python3 の代わりに python を使用してください。--title と --sections には上記のオンボーディングでの回答を指定し、ユーザーがオプトアウトした場合にのみ --no-hooks を指定します。スキャフォールドは自動的に検証されます。

Claude Code では、${CLAUDE_SKILL_DIR} がこのスキルのディレクトリに展開されます。

python3 "${CLAUDE_SKILL_DIR}/scripts/scaffold.py" ./my-knowledge-base \
  --title "Team knowledge base" \
  --sections concepts,services,decisions

その他のクライアントでは、スキルカタログから SKILL.md の絶対パスを取得します。プロジェクトディレクトリにとどまり、インストール済みスクリプトを絶対パスで実行します。

python3 /absolute/path/to/okf-wiki/scripts/scaffold.py ./my-knowledge-base \
  --title "Team knowledge base" \
  --sections concepts,services,decisions

デフォルトのセクションは concepts です。空でないディレクトリに書き込むには --force を使用し、検証の実行を省略するには --no-validate を使用します。また、サンプルのフロントマターの日付を設定するには --date YYYY-MM-DD を使用します。セッションフックはデフォルトで書き込まれます。--no-hooks を指定すると省略され、--hooks-os posix|windows を指定すると、自動検出された起動コマンドを上書きします（以下を参照）。

スキャフォールドされたプロジェクトのルートから、いつでも検証できます（Windows では python を使用してください）。

python3 scripts/validate.py --bundle bundle    # must exit 0

バンドルに内容を追加する：既存の資料からコンセプトを作成する

スキャフォールディングでは、プレースホルダーのコンセプトが1つある空のツリーが作成されます。よくある次のような依頼、「ドキュメント／計画／メモ／リポジトリを渡すので、ウィキを作成してください」には、インポートスクリプトがありませんし、作成することもできません。何を1つのコンセプトとするか、その1行の説明を書くこと、その type を選ぶこと、そして source を実際の出典に紐付けることは、機械的な変換ではなく判断を要する作業だからです。次の手順で、コンセプトを直接作成してください。

1. ソースを収集します。 ユーザーが指定したファイル、フォルダー、リポジトリ、URLを読み込みます（URLの場合は先に取得します）。何かを書く前に全体にざっと目を通し、自然な概念の区切りを把握します。
2. 概念の区切りを決めます。 1つのファイルには1つの概念をまとめます。つまり、読者が単独で調べるような1つの事柄（サービス、決定、パス、人物、イベント）です。5つの事柄を扱うドキュメントは5つの概念に分割し、単独では意味が通じない断片は1つにまとめます。見出しは手がかりであってルールではないため、##ごとに機械的に1ファイルへ割り当てないでください。
3. 各概念を bundle/<section>/<slug>.md に完全なフロントマター付きで作成します。 作成前にバンドルのルートにある index.md を読み、検証キーが宣言された形式と一致するようにします。okf_version が 0.1 から 0.3 の場合は verified を、0.4 の場合は verified_on を使います。type, title, description, source, timestamp, tags とともに、該当するキーをそのまま出力します。
   • type は語彙リストから選びます。インフラストラクチャ：Machine、Network、Service、Session、Project、Repo、Credential、Path、Process。ドメイン中立：Concept、Decision、Event、Person、Org、Source。さらに、その他すべてを含むReferenceもあります。種類は固定されており、リストにない種類は失敗になります。
   • description は1行で記述します。source は各要素を引用符で囲み、事実の実際の出所（起源となるファイルパス、URL、コマンド、イベント）を示します。このスキル自体を出所にしてはいけません。
   • timestamp は今日の日付にします。verified／verified_on は事実が最後に真実だと確認された日付です。機械的に今日の日付を設定せず、どのように事実を知ったかに基づいて設定します。
     • 今この時点で現実と照合して再確認した場合、またはユーザーがこのセッションで決定、好み、意図を示し、その内容についてユーザーが信頼できる情報源である場合：今日の日付。
     • ユーザーが外部またはシステムの状態（仕様、パス、設定）を記憶に基づいて述べている場合、その記憶は情報源の主張であり、再確認ではありません。その状態を最後に確認した日付、または記憶にある日付にします。今その話題が出たからといって今日の日付にはしません。
     • 日付のある情報源から再確認せずにコピーした場合：最後に真実だと確認されていた日付（情報源自体の日付）にします。今日の日付にはしません。
     • 再確認できない日付なしの記録（メモリファイル、過去の会話）に由来する場合：根拠を示せる最も古い日付、ファイルのタイムスタンプ、導入コミット、またはその内容が述べられた日付にします。今日の日付にはしません。日付を示す根拠がまったくない場合、その事実はまだ検証可能ではありません。日付を確認できる情報源を探すか、その概念を記載しないでください。 日付が不確かな場合は、より古い日付に丸めます。古い verified なら「古くなっている可能性があるため、再確認が必要」と正しく示せますが、今日の日付では「たった今確認済み」と誤って受け取られます。フロントマターの日付が基準です。本文に注意書きを加えても、過大な値は訂正されません。バリデーターやツールが参照するのは日付だけです。
   • 作業中にシークレットの値を除去します。Credentialの概念にはキーの名前と取得方法を記載し、値は絶対に記載しません。シークレットが漏れていると、バリデーターはビルドを失敗させます。
4. 配置してリンクします。 各概念を適切なセクションに配置し（必要に応じてセクションを作成）、そのセクションの index.md に項目を追加し、関連する概念同士を相対パスの [text](path.md) リンクで相互参照します。[[slug]] のWikiリンクは使わないでください。[[slug]] は自動メモリ用の記法で、OKFバリデーターはこれを拒否し、解決もしません。そのため、誤記や削除済みの参照があっても、気付かれないまま検証を通過します。新しいセクションを作成した場合は、バンドルのルートにある index.md からもリンクしてください。このルートファイルはセッションアンカーが読み込むナビゲーションマップです。検証には通っても、ルートからリンクされていないセクションは、全体を把握する際に見つけられません。
5. プレースホルダーを削除します。 新規にひな形を作成した場合、実際の概念ができた時点で、スターターの example-concept.md（およびセクションの index.md にあるその項目）を削除します。削除しないと、完成したWikiにサンプルが残り、検証も通過してしまいます。
6. 検証を繰り返します。 python3 scripts/validate.py --bundle bundle を実行し、報告された問題を修正して、終了コードが0になるまで繰り返します。source 要素を引用符で囲んでいない場合や、フロントマターのキーが不足している場合によく失敗します。50個のファイルを書いてからまとめて問題を調べるのではなく、いくつかずつ作成し、その都度検証してください。

ソースがすでにOKF準拠の場合

ユーザーが既存のOKFバンドル（たとえば、okf_versionを含むindex.mdと、フロントマター付きのコンセプトファイルを備えた上流のサンプル）を指定した場合は、インポートするのではなく、そのまま採用します。ツリーをコピーまたはクローンし、新しいルートをバリデーターに指定して、移動によって壊れたリンクを修正します。他のコンテンツと並ぶ独立した領域として維持するには、一意の名前を付けたトップディレクトリを用意し、okf_versionを含む結合ルートのindex.mdを1つ作成して、採用した各バンドルのルートにあるindex.mdからフロントマターを削除し、通常のセクションインデックスにします（バリデーターが許可するのは、結合ルートにある1つのokf_versionのみです。ネストされたindex.mdに残っている場合は検証に失敗します）。相互リンクには相対パスを使い、結合ルートを検証します。すでに準拠しているバンドルを自分のコンセプトに書き直すのは無駄な作業です。実際にそれが目的の場合に限り、構成を変更してください。

フォーマットの概要

仕様全体はspec/SPEC.mdにあります。この仕様はGoogleの上流OKFを厳密にフォークしたもので、7つすべてのフロントマターキーを必須とし、上流のresourceおよび# Citationsの代わりにsourceリストを使用し、検証日キーを追加し、typeの語彙を限定して、リンクの解決を強制します。spec/SPEC.mdの「Relationship to upstream OKF」には、すべての相違点が記載されています。特に重要なルールは次のとおりです。

• すべてのコンセプトに必須のフロントマターを設定します。type, title, description, source、前述のバージョン固有の検証キー、timestamp, tagsが必要です。typeには、Machine、Network、Service、Session、Project、Repo、Credential、Path、Process（インフラストラクチャ）、Concept、Decision、Event、Person、Org、Source（ドメイン中立）、またはReference（その他全般）のいずれかを指定します。
• すべてのsource要素を引用符で囲みます。ソースのポインターには#と: が含まれており、引用符で囲まないとYAMLが壊れます。source: ["README.md", "issue #445"]。
• **verified／verified_onは、事実が最後に真実だと確認された日付、現実との照合日、またはユーザーが自らの権限で事実を述べた日付（決定や好みなど）です。外部の状況についてユーザーが単に記憶している事実は、再確認ではなくソースの主張です。timestamp**はコンセプトの作成または更新日時です。検証日はISO形式のYYYY-MM-DDです。0.3および0.4では、timestampに完全なISO 8601形式の日時も指定できます。日付に関する詳細なルールは、前述の作成ワークフローを参照してください。
• **秘密の値は絶対に記載しないでください。**Credentialコンセプトには、キー名と取得方法のみを記載し、値は記載しません。秘密情報が漏洩している場合、バリデーターはビルドを失敗させます。
• index.mdとlog.mdは予約済みであり、フロントマターを付けません（バンドルルートのindex.mdは例外で、okf_versionのみを含めます）。

オプション：上流v0.2の信頼性／出所シグナル

上流のGoogle OKF v0.2（2026年7月）では、コンセプトを読む前に利用者がその信頼性を判断できるよう、任意の語彙が追加されました。generated（生成した人物またはもの）、verified（このフォーク独自の単一日付フィールドではなく、複数の独立した確認のリスト）、sources（各ポインターの信頼性を示す構造化データ）、status（draft／stable／deprecated）、stale_after（絶対的な有効期限日）、および承認済みで検証可能な計算を表すAttested Computation typeです。いずれも必須ではなく、これらを採用しないバンドルには影響しません。

これらを有効にしてプロジェクトをひな形から作成するには、scaffold.py <target> --trust-signalsを実行します。バンドルではokf_version: "0.4"が宣言され、必須フィールドのverifiedはverified_onに変更されます（これにより、verifiedを新しい形式に使用できます。フィールドの詳細な仕様と名称変更の理由については、spec/SPEC.mdの「Trust and provenance」セクションを参照してください）。Attested Computationも0.4でのみ使用できるtypeです。このフラグを指定しない場合、ひな形の作成方法は、この語彙が導入される前と変わりません。

セッションフック

スキャフォールドされたプロジェクトには、Claude Code のセッションがメモリーではなくバンドルから開始されるようにする、2 つのフックを備えたオプションの Claude Code アダプターを含められます。

• okf-anchor.py（SessionStart）は、バンドルのルートインデックスをセッションコンテキストに出力します。
• okf-orient.py（PreToolUse、マッチャーなし）は、Claude がインデックスを読んだことを確認するまで、セッションの最初のアクションを一度ブロックし、その後はセッションの残りの間、ブロックを解除します。OKF バンドル外では何もせず、エラー時は処理を続行するため、セッションが行き詰まることはありません。

どちらもクロスプラットフォーム対応の単一の python3 スクリプトです。スクリプトはすべての OS で同一で、生成されたアダプター設定内のインタープリターだけが異なります。macOS/Linux では python3、Windows では python です。scaffold.py は OS を自動検出します。--hooks-os posix|windows を指定すると、使用する OS を強制できます。

Claude Code は、チェックインされたプロジェクトのフック設定を信頼されていないものとして扱うため、プロジェクトを初めて開いたときに、ユーザーにフックの承認を求めます。承認後は自動的に実行されます。無効にするには、--no-hooks を指定してスキャフォールドするか、.claude/ を削除するか、既存のプロジェクトで disableAllHooks を設定してください。

クライアントの境界

移植可能な OKF の構成要素は、SPEC.md、requirements.txt、scripts/validate.py、および bundle/ ツリーです。生成される README.md には、これらの共通構成要素と、有効になっているクライアントアダプターの両方が記載されます。生成される 3 つの .claude/ ファイルは Claude Code アダプターであり、OKF フォーマットの一部ではなく、Codex と共通の動作でもありません。Codex はこれらをプロジェクト設定として読み込まないため、このスキルでは SessionStart や PreToolUse のライフサイクルが Codex 上で実行されると主張してはいけません。

共通のオンボーディング手順はクライアントに依存しません。上記のラベル付きコマンドは、クライアント固有のスキルルートの検索方法を説明しています。記録された Codex のパイロットでは、オンボーディングの選択肢があらかじめすべて設定され、明示的にインストール済みのパスが使用されていたため、その過去の結果は、新たに一般化された質問フローに関する実行時の根拠にはなりません。

Claude Code と Codex が混在するプロジェクトでは、Claude Code が信頼を求めてフックを使用できるよう、.claude/ を残してください。Codex では何も実行されません。Codex のみを使うプロジェクトでは、スキャフォールド時に --no-hooks を指定するか、後から .claude/ を削除してください。どちらを選んでも、移植可能なバンドルとバリデーターは変わりません。

オプション：GitHub wiki に公開する

OKF はリポジトリ内のファイルとして使うのが最適です（バリデーターと相対リンクがそのまま機能します）。リポジトリの GitHub wiki は任意の閲覧用インターフェースです。設定は高度な手動作業なので、ほとんどのユーザーはスキップして、バンドルをリポジトリ内に置いておくのがおすすめです。

ページが 1 つもない wiki には、プッシュ先となる Git リポジトリも API もないため、最初のページはウェブ UI から作成する必要があります。scripts/gh-wiki-bootstrap.py はこの手順を自動化しますが、ログイン済みのブラウザーを実際に操作するため、ユーザー自身で用意するものが 2 つ必要です（wiki のページはウェブ UI でのみ操作できるため、GitHub PAT は使えません）。

• Chromium がインストールされた Playwright： pip install playwright && playwright install chromium。
• 保存済みの GitHub ウェブセッション： GitHub にすでにログインしているブラウザーから取得した Playwright の storageState JSON。スクリプトはこのセッションを再利用します。ログインを代行することはありません。--state でパスを指定してください（既定値：~/.cache/gh_state.json）。

Claude Code の場合：

python3 "${CLAUDE_SKILL_DIR}/scripts/gh-wiki-bootstrap.py" owner/repo --state /path/to/gh_state.json
# then: git clone https://github.com/owner/repo.wiki.git and push your pages

その他のクライアントでは、インストール済みのスキルの絶対パスを使用してください。

python3 /absolute/path/to/okf-wiki/scripts/gh-wiki-bootstrap.py owner/repo --state /path/to/gh_state.json
# then: git clone https://github.com/owner/repo.wiki.git and push your pages

注意点：GitHub wiki は OKF ツリーよりもフラットな構造で、[[WikiLinks]] を使用します。そのため、OKF の入れ子になったディレクトリと相対リンクは、wiki の形式に合わせて調整する必要があります。wiki は公開された閲覧用として扱い、信頼できる唯一の情報源にはしないでください。（v0.1 にはブートストラップ手順が含まれていますが、バンドルから wiki への自動同期はまだ実装されていません。）

完了前に

• バリデーターを実行し、終了コードが 0 であることを確認してください。
• オンボーディング時に設定した公開範囲が、作成した内容に今も適していることを確認してください。実際のインフラストラクチャを記録することになったバンドルは、通常、社内向けです。OKF は立場を示しません。判断するのはあなたです。