archscribe

Archscribe

記事、システムの説明、プロセス、参考画像から、洗練された手描き風の図を作成します。デフォルトのブラウザーレンダラーでは、PNG、GIF、MP4、SVG、編集可能なExcalidraw、インタラクティブなHTMLを生成できます。

1. 環境を確認する

セッションごとに1回実行します：

python -X utf8 -c "import PIL, svg.path"
python -X utf8 -c "from playwright.sync_api import sync_playwright"
python -X utf8 scripts/doctor.py

• 基本パッケージが不足している場合：python -m pip install -r requirements.txt
• Playwrightが不足している場合：python -m pip install -r requirements-browser.txt && python -m playwright install chromium
• ffmpegが不足している場合：MP4はスキップされますが、ほかのブラウザー形式は引き続き使用できます。
• Chromiumを利用できない場合：--renderer pillowを使用します。Pillowは、従来のフローアニメーション付きでPNG、GIF、Excalidrawに対応しています。

同梱のフォント、アイコン、rough.jsにより、主要なビジュアルシステムをさまざまな環境で利用できます。Chromium、ffmpeg、まれなCJKフォールバックフォントは、引き続き環境に依存します。

2. レイアウトを選ぶ

レイアウト	用途	容量
panorama	入力、コア、判断、詳細パネルを含むシステム全体	入力2～6個、コアカード2～4個、パネル0～3個
swimlane	カテゴリー別の帯／比較行（DailyDoseOfDSスタイル）、役割をまたぐワークフロー、カタログ	タイトル＋サブタイトル列を持つレーン2～5本、各レーン最大5ステップ、レーン内の破線ループチャネル
graph	プロジェクトごとに異なるループ構造（再試行／再計画／再呼び出しなど）を持つ自由形式のワークフロー	ノード2～24個、エッジ最大40個、自動DAGレイアウト＋ループレーン

判断基準：

• 複数の領域を含むシステム全体 → panorama
• 並列するカテゴリー、バリエーション、役割、または比較（「XのN種類」） → swimlane（各レーンに色付きの帯が付き、暗めのタイトル列には「Triggered by: ...」のような任意のsubtitleを設定できます。レーン内で右から左へ向かう接続は、カードの下にある破線のループチャネルへ自動的に配置されます）
• 独自のトポロジーを持つもの：直線的なステージ、分岐／合流、複数の異なるループ → graph（nodes＋edgesを宣言します。kind: "loop"のエッジは、前進する波が終わった後に動作する破線の戻りチャネルになります）。右方向に長いグラフは、端が切れたり上部に偏ったレイアウトになったりするのを防ぐため、自動的に下方向へ積み重ねられます。

3. 仕様を記述して検証する

assets/default-spec.jsonまたはassets/examples/内のファイルから始めます。フィールドの完全なリファレンスはreferences/spec-format.mdです。

タイトルは短くし、ユーザーの言語を使い、詳細は本文、注記、またはインタラクティブなHTMLサイドバーに記載します。

python -X utf8 scripts/render_animated_diagram.py --spec spec.json --outdir out --validate-only

すべてのエラーを修正してください。警告は、テキストが長い、不明なアイコンがある、無視されるフィールドがある、コンテンツがレイアウトの容量を超えている、グラフが自動的に積み重ねられる、またはグラフのキャンバスの幅／高さが無視されることを示します。

4. ビジュアルテーマを選ぶ

どちらも主要なスタイルとして利用できます：

• default：黒いキャンバスにネオンが光る手描き風。光るビーム、粒子、ビネットが特徴です。ブランドのヒーロービジュアルです。
• paper：明るく温かみのある白い紙（DailyDoseOfDSスタイル）。セージ／ペリウィンクルの帯、ほぼ黒のインク、色付きの線で縁取られた白いカードを使います。フローアニメーションでは、ネオンビームの代わりに小さな単色の点が矢印に沿って移動します。

スタイルはパレットと仕上がり全体を制御します。--styleを使うと、仕様内のスタイルを上書きできます。ほかのスタイル名は検証に失敗します。

5. アニメーションを選ぶ

• flow：データの連続的な移動。安全なデフォルトです。
• draw：ホワイトボードへの描画
• relay：一度に1つの接続
• trace：リクエストの経路をたどる
• chapter：段階的に説明を組み立てる
• failure-recovery：失敗／再試行を軸にしたナラティブのタイミング

最後の3つは決定論的なナラティブの演出と、より長い最小タイムラインを使用します。従来のPillowのflow以外のすべてのプリセットで、ブラウザーレンダラーが必要です。

6. レンダリングと検証

まず、レイアウト確認用の PNG をレンダリングします。

python -X utf8 scripts/render_animated_diagram.py --spec spec.json --outdir out --basename diagram --formats png --check

次に、公開用セットをレンダリングします。

python -X utf8 scripts/render_animated_diagram.py --spec spec.json --outdir out --basename diagram --formats gif,mp4,png,excalidraw,svg,html --verify --check --strict-formats

--formats では指定が厳密に適用され、要求された対応形式のファイルのみが出力されます。不明な形式を指定すると失敗します。公開時には --strict-formats を使用し、MP4／SVG／HTML がない場合に、暗黙に別形式へフォールバックするのではなく失敗するようにしてください。--check は "ok": true を返す必要があります。

PNG を目視で確認し、重なり、交差するコネクター、窮屈なラベル、弱い階層構造、端の切れ、余白の偏りがないかをチェックします。読みやすいサイズを下回るまで文字を小さくする前に、文言を短くするかレイアウトを変更してください。

7. アイコンとブランド

仕様では、安定した意味ベースのアイコンキーを使用します。主要なキーには file、folder、scan、shield、db、package、message、api、clock、brain、gear、eye、terminal、globe、server、lock、check、clipboard があります。

追加の意味ベースのエイリアスは、クラウドインフラストラクチャ、データ、AI、セキュリティ、ビジネス上の役割、状態をカバーしており、cloud、cluster、container、queue、cache、vector-db、agent、model、rag、tool-call、guardrail、evaluation、identity、audit、user、success、failure、retry などがあります。

カスタムロゴやカラフルなアイコンには、ローカルの SVG／PNG パスを指定して icon_file を使用します。パノラマパネルのブランドマークには left_panel.badge_file を使用します。パスは仕様ファイルからの相対パスとして解決されます。

イラストシステム

icon を受け付けるすべての項目では、以下も指定できます。

• icon_style：outline、illustrated、hero のいずれか。
• icon_size：compact、standard、hero のいずれか。
• icon_motion：auto（アイコンに組み込まれた動作ストーリーを再生）または none（静止ポーズで固定）。従来のプリセット名（think-pulse、gear-spin、eye-scan、memory-write、shield-check、scope-scan、budget-gauge、trigger-ping、tool-spark、output-pop）も引き続き使用でき、auto と同じように動作します。

密度の高い二次ノードには outline、通常のコンセプトカードには illustrated、ストーリーを伝える主要なコンセプト 1～3 個には hero を使用します。ブラウザレンダラーは、プレートなしの「ネオンスケッチ・デュオトーン」イラストを描画します。テーマカラーのインクを使った手描きの線と、動く部分に意味に応じたアクセントを 1 色加えます。約 56 種類の意味ベースのファミリーが、それぞれ独自のシームレスなループ動作ストーリーを表現します（シナプス信号、ギアのピッチ、チップの落下、シャックルのクリックなど。references/illustrated-icons.md を参照）。これには、エージェントループやパイプラインの図向けの専用ループワークフローパック（loop、decision、split、merge、wait、orchestrator、subagent、handoff、human、plan、score、compare、sandbox、checkpoint、error、rollback、emit、ingest、…）も含まれます。サンプル仕様は assets/examples/loop-icon-pack-spec.json です。Pillow は簡略化したオフライン用デュオトーン版をレンダリングし、Excalidraw では編集可能なアイコンのプレースホルダーが維持されます。

DailyDoseOfDS 風の短いループには、1210×1138、20 FPS、41 フレーム、安定したカメラ、一度に 1～3 個のアクティブパス、主要なコンセプトには illustrated／hero アイコン、アニメーションには flow を使用します。assets/examples/illustrated-loop-spec.json（ダークパノラマ）または assets/examples/swimlane-spec.json（明るい紙の帯）を出発点にしてください。

8. 納品

• 必要に応じて GIF をインラインで表示します。
• 公開やソーシャルプラットフォームには MP4 を優先します。
• すぐに確認できるよう PNG を含めます。
• 編集可能であることが重要な場合は .excalidraw を含めます。
• 探索やプレゼンテーション用にインタラクティブ HTML を提供します。
• 拡大縮小可能な静的公開物には SVG を使用します。

この SKILL.md を変更した後は、トリガーの動作をテストする前に、新しいタスクを開始するかセッションを更新してください。スクリプトとアセットの変更はすぐにテストできます。