Communitygithub.com

okf-loom — リポジトリローカルスキル

Markdownドキュメントバンドルを検証済みのOKFナレッジグラフに変換するツールキット。ローカルスタジオ、静的サイト出力、エージェント向けCLIを備えています。

okf-loom — リポジトリローカルスキル とは?

okf-loomは、Open Knowledge Format (OKF) バンドルを扱うための包括的なツールキットです。このスキルは、リポジトリ自体がスキルとして機能する設計で、パッケージ公開のワークフローを学ぶ必要がありません。主な機能として、バンドルの検証、検索、発見、更新、ライブスタジオの起動、コンセプトの作成があります。エージェントは、まずバリデーションを行い、その後プロアクティブにスタジオを起動してユーザにURLを提示することが期待されます。スタジオが起動している間は、コラボレーションループ(コメントの取得、編集、解決)を継続的に実行します。CLIは`scripts/okf-loom`を通じて提供され、特別なインストールは不要で、PyYAMLがあればそれを使用し、なければ内蔵のフォールバックで動作します。ファイル編集はアトミックかつマーカーセーフであることが要求され、不明なfrontmatterキーは保持されます。このスキルは、OKFバンドルを中心としたドキュメント管理とナレッジグラフ構築のワークフローを効率化し、特にClaude CodeやCursorなどのAIエージェントが、構造化された知識ベースを操作するのに最適です。

対応✓Claude Code~Codex CLI~Cursor
npx skills add ojamin/okf-loom

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

okf-loom — リポジトリローカルスキル は何をしますか?

このリポジトリ自体がスキルです。クローンし、このSKILL.mdをロードした上で、以下で参照されている小さなリソースファイルとチェックアウトローカルスクリプトを使用してください。パッケージ公開のワークフローを学ぶ必要はありません。永続的な成果物はこのgitリポジトリのレイアウトです。

デフォルトの振る舞い(要求されなくても実行すること)

以下は、このスキルを使用するエージェントに対して常に期待される標準的な動作です。

  1. ドキュメントはOKFバンドルです。 ユーザがドキュメント、ノート、知識ベース、または「これをまとめて」と依頼した場合、OKFコンセプトとして作成します — コンセプトごとに1つのマークダウンファイル、完全なfrontmatter(type、title、description、tags、timestamp、さらに実際に情報を伝える場合はaliases/entities/relations/provenance/citations)を付けます。新しいバンドルはscripts/okf-loom bootstrap <dir>で開始するか、既存のバンドルに追加します。docs-bundle/demo/showcase.mdは、完全に装飾されたコンセプトの標準的な例です(レンダリングして開き、各キーがなぜ重要なのかを確認してください)。

  2. 書き込み後は検証します。 一連の書き込みの後は必ずscripts/okf-loom validate <bundle>を実行し、結果を修正します。また、scripts/okf-loom discover <bundle>を定期的に実行し、不足しているリンク/インデックス/説明を検出します。index.mdファイルが古くなっている場合は、scripts/okf-loom index <bundle>で生成ブロックを再生成します(マーカーセーフ — okf:generatedマーカーの間のみ書き換えます。マーカーのない手書きのインデックス散文は置き換えられるので、git diffを確認してください)。

  3. プロアクティブにサーブします。 レンダリングされたwikiが成果物であり、デバッグビューではありません。ユーザがドキュメントを見たい、読みたい、レビューしたい、コメントしたいと思ったとき、またはあなたがバンドルを構築/変更した場合でユーザがそれを見たくなる可能性が高いときは、要求を待たずにスタジオを起動し、URLを渡してください:

    scripts/okf-loom serve path/to/bundle --no-open          # ローカル:  http://127.0.0.1:8787/
    scripts/okf-loom serve path/to/bundle --no-open --tunnel # + 公開httpsURL (cloudflaredが必要)
    

    --tunnelは、このマシンにいないユーザ向けのhttps://…trycloudflare.comリンクを表示し、トンネルホストをスタジオのクロスオリジン許可リストに自動的に追加します。ユーザには、任意のテキストを選択してコメントできること、グラフは/__graphにあることを伝えてください。

  4. コラボレーションループを実行します。 スタジオが起動している間、ユーザのコメントはあなたの仕事です:scripts/okf-loom wait <bundle>はコメントまたは変更があるまでブロックし、その後、主張 → 編集 → 解決(comment-claim / ミューテーター / comment-resolve)を行います。最初のループの前にresources/studio-agent-loop.mdを読んでください。

  5. スタジオセッションがライブの間は、コンテンツ変更にミューテーターを優先します(write-concept、set-frontmatter、link-add、entity-add、update):これらは属性が付与され、元に戻せ、開いているタブにライブでブロードキャストされます。それ以外の場合は直接ファイル編集でも問題ありません — ウォッチャーがそれを検出します。

クイックスタート

okf-loom/内から:

scripts/okf-loom --help
scripts/okf-loom validate docs-bundle --strict

通常のドキュメント検証にプライマリランタイムのインストール手順は必要ありません。PyYAMLが存在する場合はそれを使用し、それ以外の場合はokf-loomは内蔵の保守的なYAMLフォールバックを使用します。

チェックアウトの名前がokf-loom/である親ワークスペースから:

okf-loom/scripts/okf-loom validate okf-loom/docs-bundle --strict

例では、ローカルシェルラッパーやインストール済みコンソールスクリプトではなく、チェックインされたヘルパーを直接使用しています。

いつ何を読むか

状況読むもの
常に、最初に(60秒で概要+デフォルトパス)resources/overview.md
バンドルに初めて書き込む前resources/gotchas.md
CLI動詞の実行 / フラグが不明な場合resources/command-reference.md
コンセプトファイルを手動で作成または編集する場合resources/format-basics.md 次に resources/authoring.md
「適切な」frontmatterがどのようなものか決める場合docs-bundle/demo/showcase.md — 実例
検証の実行が失敗した場合、またはCIゲートが必要な場合resources/validation.md
検索モード、発見、プラン、静的ビルドresources/advanced-operations.md
スタジオが起動中でユーザがコメントしている場合resources/studio-agent-loop.md
scripts/okf_loom/以下のランタイムを変更する場合resources/architecture-map.md
曖昧な点 — 拘束力のある契約docs-bundle/reference/spec.md
人間向けのエンドユーザドキュメントdocs-bundle/

リポジトリレイアウト

okf-loom/
├── SKILL.md                 # ロード可能なスキルエントリポイント
├── resources/               # エージェントが読む小さなガイダンスファイル
├── scripts/
│   ├── okf-loom              # チェックインされたヘルパーコマンド
│   ├── okf_loom/             # チェックアウトローカルランタイムパッケージ
│   ├── build_skill_archive.py
│   ├── capture_readme_media.py
│   ├── capture_viewer_proof.py
│   ├── capture_signal_controls.py
│   └── lint-js.sh
├── docs-bundle/             # OKFドキュメントバンドル
├── samples/                 # OKFバンドルの例
├── tests/                   # チェックアウトスクリプト用のpytestテスト
├── docs/                    # READMEメディア (docs/media/)、スクリーンショット、設計計画
├── README.md                # 人間向け概要
├── AGENTS.md                # 最初にAGENTSを読むエージェント向けの簡潔なポインタ
└── CLAUDE.md                # 最初にCLAUDEを読むエージェント向けの簡潔なポインタ

コアコマンド

# バンドルを検証する。
scripts/okf-loom validate path/to/bundle --strict

# 調査 / 検索。
scripts/okf-loom info path/to/bundle
scripts/okf-loom search path/to/bundle "顧客注文" --mode hybrid

# ライブコラボレーションスタジオを起動する(公開リンクには--tunnelを追加)。
scripts/okf-loom serve path/to/bundle --no-open

# ギャップを発見し、安全なミューテーションを適用する。
scripts/okf-loom discover path/to/bundle --out /tmp/okf-suggestions.json
scripts/okf-loom link-add --bundle path/to/bundle --source tables/orders --target tables/customers

# スタジオ起動中のコラボレーションループ(現在の仕様 §12)。
scripts/okf-loom wait path/to/bundle        # コメント/変更が届くまでブロック
scripts/okf-loom comment-claim path/to/bundle <comment-id> --summary "何をするか"
scripts/okf-loom comment-resolve path/to/bundle <comment-id> --summary "何をしたか"

絶対条件(非交渉事項)

  • scripts/okf-loomを使用すること。インストール済みパッケージやコンソールスクリプトを想定しないこと。
  • PyYAMLが存在する場合はそれを優先するが、バンドルされたフォールバックは通常のランタイム/ドキュメント検証には十分であり、サポートされていない高度なYAMLでは安全側に倒れて失敗する。
  • PyPI/パッケージ公開フローを主要パスとして追加しないこと。
  • 未知のfrontmatterキーと手書きのバンドルコンテンツを保持すること。
  • typeはOKF v0.1において、唯一必須のコンセプトfrontmatterキーである。
  • リンク切れはデフォルトではコンシューマに対する警告であり、オーサリングミューテーターは、--allow-forward-referenceが明示されない限り、ターゲット欠落時に安全側に倒れて失敗する。
  • すべてのokf-loomの書き込みはアトミックかつマーカーセーフでなければならない。

より深いルールについては、resources/gotchas.mdを読んでください。

関連スキル