okf-loom — リポジトリローカルスキル は何をしますか?
このリポジトリ自体がスキルです。クローンし、このSKILL.mdをロードした上で、以下で参照されている小さなリソースファイルとチェックアウトローカルスクリプトを使用してください。パッケージ公開のワークフローを学ぶ必要はありません。永続的な成果物はこのgitリポジトリのレイアウトです。
デフォルトの振る舞い(要求されなくても実行すること)
以下は、このスキルを使用するエージェントに対して常に期待される標準的な動作です。
-
ドキュメントはOKFバンドルです。 ユーザがドキュメント、ノート、知識ベース、または「これをまとめて」と依頼した場合、OKFコンセプトとして作成します — コンセプトごとに1つのマークダウンファイル、完全なfrontmatter(
type、title、description、tags、timestamp、さらに実際に情報を伝える場合はaliases/entities/relations/provenance/citations)を付けます。新しいバンドルはscripts/okf-loom bootstrap <dir>で開始するか、既存のバンドルに追加します。docs-bundle/demo/showcase.mdは、完全に装飾されたコンセプトの標準的な例です(レンダリングして開き、各キーがなぜ重要なのかを確認してください)。 -
書き込み後は検証します。 一連の書き込みの後は必ず
scripts/okf-loom validate <bundle>を実行し、結果を修正します。また、scripts/okf-loom discover <bundle>を定期的に実行し、不足しているリンク/インデックス/説明を検出します。index.mdファイルが古くなっている場合は、scripts/okf-loom index <bundle>で生成ブロックを再生成します(マーカーセーフ —okf:generatedマーカーの間のみ書き換えます。マーカーのない手書きのインデックス散文は置き換えられるので、git diffを確認してください)。 -
プロアクティブにサーブします。 レンダリングされた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にあることを伝えてください。 -
コラボレーションループを実行します。 スタジオが起動している間、ユーザのコメントはあなたの仕事です:
scripts/okf-loom wait <bundle>はコメントまたは変更があるまでブロックし、その後、主張 → 編集 → 解決(comment-claim/ ミューテーター /comment-resolve)を行います。最初のループの前にresources/studio-agent-loop.mdを読んでください。 -
スタジオセッションがライブの間は、コンテンツ変更にミューテーターを優先します(
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を読んでください。