k2f

K2F

K2F を使って、洗練された Word（docx）、PDF、入力可能な AcroForm PDF、Adobe InDesign（IDML）を作成、デザイン、編集できます。K2F は、エージェントが洗練された文書を正確かつ簡単にデザイン、編集できるように設計されています。メニュー、証明書、プランナー、招待状、ワークシートなど、見栄えのよい文書が必要なときに AI エージェントと一緒にお使いください。Gallery のテンプレートから始めることもできます。

.K2F は ZIP 形式です。意味（座標ではなく）を表すセマンティックな JSON ツリーを編集すると、エンジンが pack／compile を実行し、変更不可のレンダリングロックを生成します。参照エンジンは 1 つだけなので、どこでもピクセル単位で同一の出力が得られます。

ワークフローを選ぶ

タスクに応じて、参照ファイルを 1 つ 読んでください。すべてのワークフローを読み込まないでください。

タスク	読むファイル
.K2F の作成または更新（CV、チラシ、スライドデッキ、ポスター、レポート、ノード ID によるパッチ）	references/writing.md
Markdown ↔ K2F の変換	references/converting-markdown.md
公開済みロックから PDF をエクスポート	references/exporting-pdf.md — バイト列／見た目がおかしい場合：pdf-contract.md
公開済みロックから PPTX をエクスポート	references/exporting-pptx.md
公開済みロックから DOCX をエクスポート	references/exporting-docx.md
公開済みロックから IDML をエクスポート	references/exporting-idml.md
永続的な /v/{appearance_hash} リンクを公開	references/publishing.md
<k2f-viewer> を Web アプリに埋め込む	references/embedding-viewer.md（npm i @openk2f/k2f）

Writing（デフォルト）：ワークスペースを取得し（source/ に作成用パッケージ、ルートに成果物を配置）、ソースコードのように JSON を編集し、catalog/content/ex_*.json から図形をルートの children にコピーして（content/root.json を断片で置き換えないでください）、scripts/pack_verify.py を実行する、という 1 つのループで進めます。作成ディレクトリは、ユーザーの .K2F または Gallery パッケージの場合は k2f unpack … -o ./out/doc/source、該当するものがない場合は starter/ を使って scripts/init_package.py --workspace ./out/doc で作成します。

• 展開済みの作成ディレクトリでは Editor.insert_node を使用しないでください。この API が対応するエージェント用の方言はより限定的です。JSON による作成では、パック時に検証される完全な形式スキーマを使用します。
• テキストの modifiers には intent と UTF-8 の バイト range が必要です。必ず scripts/modifier_range.py を実行してください。手作業で数えないでください（特に \n をまたぐ場合）。
• 入力可能な空欄／チェックボックスには、catalog/content/ex_form.json をコピーしてください（____ や □ は使わないでください）。

Gallery の URL（<origin>/gallery/<slug>）またはパッケージ URL の場合は、<origin>/api/gallery/templates/<slug>（またはパッケージ URL）から .K2F をディスクに取得し、k2f unpack を実行してください。ZIP をコンテキストに読み込まないでください。MCP は任意です。作成に MCP は不要で、インストールもされません。list_templates／download_template を備えたサイト MCP がすでに接続されている場合、download_template は同種の packageUrl を返します。writing.md の手順 2 と同様に、取得して展開してください。ツールがない、種類が一致しない、またはダウンロードに失敗した場合は、starter/ から続行してください。タスクを中止しないでください。

K2F とは

PDF は AI にとって読み取りも編集もできません。HTML/CSS はデバイスごとに異なる表示になります。K2F はその両方を解決します。エージェントは意味を表すプレーンな JSON を記述し、単一のリファレンスエンジンがその意味をどこでもピクセル単位で同一の出力に変換します。

座標でコンテンツを配置する代わりに：

{"text": "WARNING!", "x": 100, "y": 50, "color": "red", "bold": true}

K2F の作成者は意味を記述します：

{"id": "doc.warning", "role": "warning", "content": {"type": "text", "value": "WARNING!"}}

すべての .K2F ファイルは、2 つの状態を格納した ZIP です：

• 状態 A — セマンティックツリー（content/root.json、変更可能、編集するファイル）。すべてのノードには、安定したドット区切りの id、role、省略可能な variant と modifiers（バイト範囲に対するインラインの強調／リンク／数式）があります。座標、色、フォントサイズはなく、これらはすべて styles/theme.json にロール／バリアントごとに定義されています。
• 状態 C — レンダーロック（document.K2F.lock、変更不可、自動生成）。正確なジオメトリ、描画操作、整合性ハッシュが含まれます。すべてのビューアーと PDF エクスポートは、ツリーではなく、これを描画します。

エンジンが（エージェントではなく）pack / compile を実行して A を C に変換します。パッケージ内のその他のパスには、manifest.json（ページサイズ、余白）、assets/fonts|images|data/*、changelog.json（編集履歴）、および省略可能な signatures/v1.json があります。

.K2F をユーザーに渡す際は、k2f.dev/playground（ブラウザー）または k2f.dev/download（デスクトップアプリ）を案内してください。

セットアップ

手元にあるのはこのスキルフォルダーのみで、K2F のソースチェックアウトも templates/ ツリーもありません。

ワークフローを実行する前に、公開済みツールをインストールしてください：

pip install k2f              # CLI on PATH + Python SDK — no need to install Cargo
npm i @openk2f/k2f           # only when embedding <k2f-viewer> in a web app
# cargo install k2f          # optional: CLI without Python

スクリプトはこのスキルディレクトリから実行してください（または絶対パスを指定してください）。コアスクリプト（init_package.py、pack_verify.py、modifier_range.py）は標準ライブラリのみで実行できます（python scripts/…）。省略可能な compare_images.py では uv run が必要です（視覚的な比較画像のオーバーレイ（任意））。作成者のディレクトリは任意の場所に置けます。pack_verify.py の実行には PATH 上の k2f（pip install k2f）または K2F_CLI が必要です。バイナリを探して git チェックアウトやビルドディレクトリを調べることはありません。

基本ルール

デザインされた用紙の下部 3 分の 1が空白になるのは、最もよくある視覚的な失敗です。pack_verify.py が終了コード 0 を返す／pages=1 になることは、紙面が埋まっていることを意味しません。PNG を開いて確認してください。修正方法：ex_filled_page.json をルート直下の子としてコピーします（height = コンテンツボックスの高さ。{fr:1} の表／注記／図が残りの領域を埋めます）。短いレターや、成長中の文書の最終ページは短いままでもかまいません。

source/ の編集は、コンパイルするまで反映されません。 ビューアーが描画するのは作成者の JSON ではなく、document.K2F.lock です。コンテンツやテーマを編集した後は、pack_verify.py を実行し、tmp/preview.png を開くか、.K2F を再読み込みしてください。

1. スタイルを定義するのは theme.json だけであり、ノードには定義しません。 ノードにスタイルフィールドを設定することは、コンパイル失敗の最も一般的な原因です。
2. document.K2F.lock を手作業で編集しないでください。 ツリー（またはテーマ）を変更してから、pack_verify.py を実行します（再ロック）。
3. PDF、PPTX、DOCX、IDML はロックの一方向の描画物であり、2 つ目のソースではありません。（PDF_IS_NOT_A_SOURCE、PPTX_IS_NOT_A_SOURCE、DOCX_IS_NOT_A_SOURCE、IDML_IS_NOT_A_SOURCE）
4. 署名は、人または組織が別途行う手順です。 エージェントの出力が UNSIGNED なのは仕様です。
5. 編集のたびに検証してください。 writing/errors.md のエラーコードをもとに修正し、ロックには手を加えないでください。
6. 実際の画像を確認してください — まず下部の空白を確認します。 パック後、描画されたすべてのページを開いてください（--render を実行すると preview-1.png … が出力されます）。デザインされた用紙の下部 3 分の 1 が空白なら、作業は完了していません。デザインされた用紙（請求書、CV、チラシ、ポスター、スライド、カード、ソーシャル投稿、1 ページのインフォグラフィック／チェックリスト／プランナー — タイトルがレポートでも同様）→ ex_filled_page.json をルート直下の子としてコピーします（固定の height ＋ {fr:1} の伸長要素）。hug スタックに page_shell ロールを設定しても、シェルにはなりません。pack_verify.py が終了コード 0 を返しても、PAGE_UNDERFILL は必ず修正してください（コンテンツボックスの高さが 180pt 未満の場合はチェックが省略されます）。短いレターは上詰めのままでもかまいません。成長中の文書（契約書、長いレポート、論文、学術論文）→ 1 つのフローツリーを使用します。最終ページは短くてもかまいません。p1／p2 のページラッパーや、文書全体を囲むページ高のシェルは使用しないでください。章、付録、署名ページ、スライド 2 枚目以降、カードの裏面では break_before: page を使用できます。詳細：writing.md。

コンテンツとデザイン

content/ または styles/theme.json を編集する前に、作成者ディレクトリ内に Markdown でコンテンツとデザインを記述します。長いコンテンツを 1 つのファイルにまとめないでください。content/*.json と同じように分割します。各ファイルには スラッグ を付けます。ページまたはセクションのトピックを表す、小文字の ASCII 文字による kebab-case にします（例：executive-summary、title-slide）。短い 1 ページなら、content_and_design.md 1 つにまとめられます。1 ページにつき 1 ファイルにする場合は、content_and_design_<slug>.md とします（スライドなら、例：content_and_design_agenda.md）。JSON フラグメントに対応するセクションは、content/<slug>.json と同じディレクトリに content_and_design_<slug>.md として置き、同じスラッグを使います。その後、python scripts/init_package.py --workspace ./out/doc … を実行します（source/ と tmp/ を作成します。これらのファイルがすでに含まれているメモのみの source/ も、その場で初期化できます）。

ワークスペースの構成：

./out/doc/
  doc.K2F                 # deliverable
  doc.pdf                 # optional exports, same stem
  source/                 # author package (edit this)
    content_and_design_executive-summary.md
    manifest.json
    content/
      root.json
      executive-summary.json   # optional fragment; same slug as its .md
    styles/ assets/ changelog.json
  tmp/                    # preview.png and other debug renders

各ファイルでは、そのページまたはセクションだけを扱い、次の両方を記述します。

• コンテンツ — すべての文章と画像（何を描写するか、幅×高さ、画像を生成する必要がある場合は完全な生成プロンプト）。図が必要な場合 → 生成してください
• デザイン — 文字の階層、余白、色、レイアウト

ドキュメント全体で共通する文字、色、余白は最初のファイルに記述します。後続のファイルには、各ファイル固有の文章と画像、使用する共通設定、異なる点を記述します。

• ユーザーが制約を指定している場合 — その指示に従います。
• ユーザーが指定していない場合 — 成果物の種類（レポート、ポスター、スライド資料、チラシなど）に求められる最高水準の美しさを実現します。デザインを施す場合は、スターターテーマを変更せずに納品しないでください。

ファイルが確定したら、writing/fields.md、続いてschema/で使用可能なキーを確認し、theme.json と content/ を実装して、pack_verify.py --render を実行します。PNG を開き、出力がこれらのファイルと一致するまで調整します。ルール 6 が最終チェックです。ファイルが計画であり、レンダリング結果がレビュー対象です。

スキーマ

読み取り専用形式の JSON Schema はschema/にあります（エンジンに埋め込まれているものと同一のバイト列です）。作成者ディレクトリにコピーしないでください。k2f pack が ZIP にスキーマを挿入します。手作業で作成した schema/ ファイルは UNEXPECTED_PATH になります。

1. 使用可能なキー： writing/fields.md にざっと目を通し、編集するスキーマファイルだけを開きます。content/ → schema/nodes.schema.json、styles/theme.json → schema/styles.schema.json + schema/visual_primitives.schema.json、manifest.json → schema/manifest.schema.json。
2. 最初のドラフトの形： catalog/content/ex_*.json からルートの children にコピーします。これらは、そのままパッケージ化できる模範例です。構成要素の一覧はcatalog/README.mdを参照してください。
3. SCHEMA_INVALID： エラーになったオブジェクトをスキーマファイルと照合します。キーがスキーマにあるのに拒否される場合は、CLI が古くなっています（pip install -U k2f）。キーがスキーマにない場合は削除してください。HTML/CSS の知識をもとにフィールドを新たに作らないでください。
4. バージョンの確認： k2f schema dump -o /tmp/k2f-schema または python -c "import k2f; print(k2f.format_schemas().keys())" を実行します。

同梱パッケージ

パス	目的
schema/	読み取り専用形式の JSON Schema。writing/fields.mdを確認した後に参照します。作成者ディレクトリにはコピーしないでください
starter/	空のツリー + コアテーマ + Roboto。既存の .K2F も一致する Gallery パッケージもない場合に、source/ へコピーされます
catalog/	模範的な構造の辞書。ex_*.json ノードを作成者ディレクトリにコピーします。成果物ではありません（索引）