okf

Open Knowledge Format (OKF) スキル

OKF では、YAML frontmatter を含む Markdown ファイルのディレクトリとして知識を表現します。 設計上、最小限の構成です。スキーマレジストリも、ランタイムも、SDK もありません。あなたの役割は、記憶に頼るのではなく、仕様に準拠した OKF バンドルを作成、保守、利用することです。

重要な作業に取りかかる前に、必ず正式な仕様を読んでください。 reference/SPEC.md。これは OKF v0.2 仕様の原文であり、以下のすべてのルールの根拠です。

唯一の厳格なルール

次の場合に限り、バンドルは準拠しています（§11）。予約されていないすべての .md ファイルに解析可能な YAML frontmatter ブロックがあり、そのすべてに空でない type フィールドがあること。これ以外はすべて柔軟なガイダンスです。利用側は、任意フィールドの欠落、未知のタイプ、リンク切れを許容しなければなりません（MUST）。それらを理由にバンドルを拒否してはいけません。

適用する規約

• 1 つの概念につき 1 ファイル。 ファイルパスから .md を除いたものが概念 ID です。
• Frontmatter： type は必須です。利用に役立つ場合は title、description、tags を追加します。resource（正規 URI）は、実在するアセットに紐づく概念にのみ追加し、抽象概念では省略します。
• 本文： 見出し、表、リスト、フェンス付きコードなど、構造化された Markdown を優先します。一般的な見出しは # Schema、# Examples、# Computation です。
• 相互リンク： 標準の Markdown リンクを使います。バンドルルートからの絶対パス形式（/services/auth-api.md）を優先します。リンクは関係性を示します。その種類は、リンクではなく周囲の文章で示します。
• 予約ファイル： index.md（ディレクトリ一覧。frontmatter は不要。ただしバンドルルートのインデックスには okf_version と、このプラグインの upkeep: enforced オプトインフラグを含めてもかまいません。また、ネストされた git リポジトリをフックの監視対象にするには、recursive: true（または深さ n。ルートより下の階層数を示し、true は 6）を追加します）と、log.md（ISO 形式の日付付きの履歴。新しい順）です。これらの名前を概念に使用してはいけません。
• log.md に記録する内容： ライフサイクルイベントのみを、バンドルルートの log.md に記録します。バンドルの作成、概念の非推奨化または廃止、ある概念が別の概念に置き換わること、ソース変更後の概念の再生成、検証の実施です。概念への通常の編集は記録しません。generated と git にすでに記録されているためです。ログは追記専用なので、既存のエントリを書き換えたり削除したりしてはいけません。

v0.2 の各項目群（すべて任意ですが、記入する価値があります）

• 信頼性（§5.2）： generated: { by, at } — 現在のコンテンツを誰が、いつ生成したかを示します。verified: [{ by, at }] — それ以降に誰が確認したかを示します（単独のマッピングは1件として扱います）。by は アクター規約（§7）に従って記述します。エージェントは <producer>/<version>、人は human:<id>、自動ジョブは process:<id> です。人が執筆または承認した場合は、必ず human: を使ってください。コンシューマーは、このプレフィックスに基づいて信頼レベルを判断します。
• ライフサイクル（§5.4–5.5）： status: draft|stable|deprecated（省略時は stable）と、絶対日時を表す ISO 8601 形式の stale_after（日付のみも許容されます）。TTL ではありません。
• 出典情報（§5.1）： sources: [{ id, resource, title, author, usage_count, last_modified }] と、sources と同じ階層に置いて各 usage_count の期間を示す usage_window: { from, to }（各エントリーに独自の値を指定して上書きすることもできます）。期間のない usage_count には警告が出ます。各エントリーで resource は必須です。URL、バンドル内のパス、スコープ記述子を指定できます。特定の主張の出典は、その出典の id をラベルにした Markdown の脚注で示します。…sharded daily.[^ga4-schema] に加えて、[^ga4-schema]: … の定義を記述します。ラベルは結合キーであり、sources[].id と一致している必要があります。
• 証明（§10）： 認可された計算は独立した概念として扱います。type: Attested Computation とし、runtime（必須）、parameters、executor、attester を持たせ、計算そのものは # Computation（または computation: のパス）に記述します。その値を必要とする概念から、この概念にリンクします。数値の SQL を、その数値について説明する概念にインラインで記述しないでください。

v0.1 のバンドルを読む場合は？ 2つの構造が置き換えられました（§13.1）。timestamp は generated.at に、本文の # Citations リストは sources になりました。どちらも読み込み、v0.2 形式で記述してください。また、maintain モードでレガシー概念を編集する際は、編集の一環として frontmatter を移行してください。バリデーターはどちらについても警告します。

コピーして使えるテンプレート：概念、インデックス、ログ。

デフォルトのバンドル配置場所

プロジェクトですでに別の場所を使っている場合を除き、リポジトリのルートに .okf/ を使用します。説明対象のコードと一緒にコミットしてください。ナレッジもコードとして管理します。

モード

produce — バンドルを作成または拡張する

新しいバンドルを作成しますか？ 最初のファイルを手作業で作成する代わりに、init の高速パスを使用してください。準拠した index.md、log.md、および推奨される frontmatter をすべて備えた getting-started.md の概念を、一度に生成します。

uv run "${CLAUDE_SKILL_DIR}/scripts/okf_init.py" <target-dir> [--title "..."]

--force を指定しない限り、すでに .md ファイルがあるディレクトリには変更を加えません。その後、次の手順で拡張します。

1. reference/SPEC.md を読みます。
2. 出典を選びます。コード（ソースコード、README、docstring、設定から概念を導き出す）、docs/wiki（ページの内容を概念にまとめ、元のページを sources に記録する）、manual（決定事項、プレイブック、メトリクス）から選択します。
3. ドメイン別のディレクトリ構成を選びます（例：services/、datasets/、decisions/）。1ファイルにつき概念を1つ記述します。
4. templates/concept.md をもとに各概念を記述します。説明的な type を設定し、推奨フィールドを記入し、generated と実際に読んだ sources を記録し、関連する概念への相互リンクを追加します。
5. ディレクトリごとに index.md を追加または更新します（ルートのインデックスには okf_version: "0.2" も記述します）。新しいバンドルでは、log.md に日付入りの Creation エントリーを追加します。既存のバンドルを拡張する場合は追加しません。
6. 検証します（下記を参照）。完了する前に、すべてのエラーを修正してください。

maintain — バンドルを現状に合わせる

1. 変更の影響を受ける概念を特定します（resource、パス、またはトピックで検索します）。この整理作業はエージェントが得意とするところです。影響を受けるファイルをすべて、一度に更新してください。
2. 本文とgenerated.atを更新します（generated.byには自身のアクターを指定します）。相互リンクを修正または追加し、新しいアセットには新しい概念を作成します。削除したアセットは、コンテキストを黙って削除するのではなく、status: deprecatedを付け、非推奨化についてlog.mdに記録します。単独のフィールドではなく、v0.1のバンドル全体が対象ですか？手作業で編集せず、バリデーターの--migrateを一度実行してください。
3. 関連するindex.mdファイルを更新します。ライフサイクルイベントの場合に限り、日付付きのlog.mdエントリを追加します（log.mdに記録する内容を参照）。
4. 検証します。

consume — バンドルをコンテキストとして使う

1. 段階的に情報を開示できるよう、まずバンドルルートのindex.mdを読み、その後、タスクに関連する概念へのリンクだけをたどります。
2. 読んだ内容の信頼性を見極めます。status: draft／deprecated、期限を過ぎたstale_after、またはverifiedエントリがない場合は、いずれも「依拠する前に確認が必要」という意味です。リンク切れはエラーではなく、まだ書かれていない知識として扱います。
3. Attested Computationが対象とする数値が必要ですか？宣言されたparametersに値を割り当てて、その計算を実行してください。独自のクエリは決して書かないでください。
4. 作業中に長期的に役立つ情報を得た場合は、maintainに切り替えて書き戻します。

検証（完了を宣言する前に実行してください）

適合性を目視で判断せず、決定的なチェッカーを実行してください。チェッカーが付属するコンパニオンの**validate**スキル（/okf:validate <bundle-dir> --strict）を呼び出します。そのスキルがインストールされていない場合は、次のコマンドを直接実行します。

uv run "${CLAUDE_SKILL_DIR}/../validate/scripts/okf_validate.py" <bundle-dir> --strict

すべてのERROR（§11の重大な失敗）を解決してください。--strictでは警告も実行失敗（終了コード1）の原因になるため、警告も解消してください。§11への適合だけを判定対象にする場合は、--strictを外す（または--max-warnings Nを使用する）ことができます。