Marp Deck Export

Goal

会話やリポジトリの実状況から、5〜10 分で話せるプレゼン資料を Marp Markdown で作り、 PDF / PPTX / HTML に書き出す。正（source of truth）は .md、描画物は生成物として扱う。 文字量と画像の中の文字の大きさは lint で、意味が伝わるかは cold read で、崩れは PNG で、 見てほしい所に目が行くかは glance test で確かめてから書き出す。

Workflow

1. 文脈を集める: まず現在の会話から。不足分だけリポジトリ・PR・docs/・実データで補う。 リポジトリを題材にする発表なら、実ソース（コード・docs/plan/・設定）を読む。憶測で書かない。
2. 相手・用途・主張を決める: 対象読者と、聞き手の現状（スタート）と発表後に期待する状態（ゴール）を決める。 聞き手に最も伝えたいこと（主張）を 1 文で書く。題材（何の話か）とは分け、題材の説明はこの 1 文の根拠として骨子に並べる。 依頼に伝えたいことが書かれていなければ、文脈から主張の候補を 2〜3 個作り、どれを最も伝えたいかをユーザーに聞く。 投影用か配布用かをユーザーに確認する（配布用なら frontmatter に class: handout）。長さが曖昧なら確認する。 ユーザーへの確認は 1 回の質問にまとめる。 目安は 1 スライド 20〜40 秒 → 5〜10 分で本文 10〜14 枚（表紙・目次・扉・まとめは別）。 聞き手のペルソナを 1〜3 行で書く。聞き手が知っている語・知らない語も書く（cold read にそのまま渡す）。
3. 骨子を先に作る: 短い kebab-case スラッグを選び、章立てと各スライドの見出し（結論を言い切る文）だけを箇条書きで出す。 見出しだけで話の筋が通って Step 2 の主張に行き着くか、章ごとの枚数に偏りがないか、各見出しが references/writing-rules.md の 8 項目を満たすかを見てから本文を書く。 図・グラフ・スクショ・表・コード・大きな数字を置くスライドには、証拠の型と**見てほしい所（1 か所）**を見出しに添える。 型は references/visual-rules.md の「証拠の型を選ぶ」から選ぶ。
4. 下書き: assets/marp-template.md（clean テーマ / 16:9）をコピーして書く。 文字量の上限は lint/slide-density.markdownlint-cli2.jsonc、文の書き方は references/writing-rules.md、 図・グラフ・スクショ・強調は references/visual-rules.md、それ以外の判断は references/design-rules.md に従う。
5. 保存: docs/slides/<slug>/YYYY-MM-DD_<slug>.md に置く（ディレクトリが無ければ作る）。 画像は同じディレクトリの assets/ に置き、デッキからは assets/<画像> で参照する。 同じ題材の別版（配布用・作り直し）は、既存の docs/slides/<slug>/ に日付や -handout を付けた名前で並べる。
6. lint: scripts/lint_deck.sh <deck.md> が通るまで直す。文字量の直し方は design-rules.md の「文字を減らす順序」に従う。 画像の中の文字が小さすぎるという指摘は、visual-rules.md の「スクショ」「図とグラフ」に従って切り抜くか描き直す。 このステップでは PNG を見ない。
7. cold read: scripts/extract_visible_text.sh <deck.md> で見える文字だけを取り出し、 会話を引き継がない新しいサブエージェント（Claude Code なら general-purpose。fork は会話を引き継ぐので使わない）に references/cold-read.md のプロンプトで読ませる。指摘を直したら lint を再実行する。
8. PNG で崩れを確認（1 回）: scripts/render_deck.sh <deck.md> png を実行し、一覧画像（sheet-*.png）を見る。 design-rules.md のチェックリストで気になるスライドだけ原寸の PNG を開く。直したら再描画し、直したスライドだけ見直す。
9. glance test: Step 3 で見てほしい所を決めたスライドの PNG とぼかした PNG（blur/）を、 会話を引き継がない新しいサブエージェントに references/glance-test.md のプロンプトで見せる。 目立つ所が見てほしい所と違えば visual-rules.md で直し、lint と PNG を再実行する。
10. 書き出し: scripts/render_deck.sh <deck.md> pdf,pptx など。 発表者ノートは PPTX のノートと HTML の発表者ビューに入る。

Content rules

• 数値・固有名詞は実データで裏取りする。統計は gh やファイルからその場で数え直す。 計画文書の古いスナップショット値をそのまま転記しない（実態とズレる）。
• 1 スライド 1 メッセージ。見出しはそのスライドの結論を言い切る文にする。
• ユーザーの言語・トーンに合わせる。ソースに無い主張を足さない。
• 文は聞き手が 1 回読んで意味を取れるように書く（references/writing-rules.md）。 lint を通すために文字を減らすときも、主体・対象・単位のような意味を運ぶ語は削らない。

Styling gotchas

• テーマは clean（assets/themes/clean.css）。色・余白・レイアウトはテーマで決まるので、デッキに style: を書かない。 見た目を変えたいときはテーマを直す（全デッキに効く）。
• テーマの code {} に背景色・文字色を付けたら、pre / pre code も必ず別に指定する。 さもないとインラインコード用の配色がブロックコードにも効いてコントラストが死ぬ。
• Marp は一部の HTML タグをそのまま解釈する（<b> <a> <span> など）。 プレースホルダーや本文に <A> のような英字の山括弧を書かない。

Rendering

skills/marp-deck-export/scripts/lint_deck.sh <deck.md>
skills/marp-deck-export/scripts/extract_visible_text.sh <deck.md>
skills/marp-deck-export/scripts/render_deck.sh <deck.md> [formats]

• formats は既定 pdf。pdf,pptx,html,png のカンマ区切りで複数指定可。
• png は一時ディレクトリに出力し、そのパスを表示する。ImageMagick があれば、ぼかした PNG（blur/）と 9 枚ずつの一覧画像 sheet-*.png も作る。
• テーマはスクリプトが --theme-set で読み込む。VS Code の Marp 拡張でプレビューするなら、markdown.marp.themes にテーマのパスを足す。
• --pdf と --pptx は 1 回の marp 実行で同時指定できない → スクリプトは形式ごとに実行を分ける。
• PDF / PPTX / PNG はヘッドレス Chromium を使う。The browser is already running や起動エラーで落ちるのは サンドボックスが Chromium をブロックしているサイン。サンドボックス外で再実行する（/sandbox で調整可）。 HTML は Chromium 不要。Chrome が無く Brave がある環境では Brave を使う（CHROME_PATH で上書き可）。
• lint は markdownlint-cli2（無ければ npx）で動き、Chromium は不要。デッキは標準入力で渡すので、リポジトリ側の markdownlint 設定の影響を受けない。 画像はデッキのディレクトリからの相対パスで探し、PNG と SVG だけを測る。

Google スライドで使う場合

pptx を書き出し → Google ドライブにアップ → 「Google スライドで開く」でインポートする。

Files

• assets/marp-template.md — 構成の見本（コピーして使う雛形）
• assets/themes/clean.css — テーマ（色・余白・レイアウト用クラス）
• assets/charts/bar.svg — 横棒グラフの雛形（グレーの棒と 1 本のアクセント色、値の直接ラベル）
• references/design-rules.md — 用途・文字を減らす順序・構成・色・クラス・目視チェックリスト
• references/writing-rules.md — 1 回で意味が取れる文の 8 項目（語と、文・スライドのつながり）・削ってよい語・書き換え例
• references/cold-read.md — 初見の読み手テストのプロンプトと結果の読み方
• references/visual-rules.md — 証拠の型の選び方・見て分かるかの 5 項目・スクショと図とグラフの作り方・書き換え例
• references/glance-test.md — 初見の人の目が行く所のテストのプロンプトと結果の読み方
• lint/slide-density.cjs — スライドごとの文字量と、画像の中の文字の大きさを確かめる markdownlint のカスタムルール
• lint/slide-density.markdownlint-cli2.jsonc — 文字量の上限と画像の下限（投影用 projection / 配布用 handout）
• lint/fixtures/ — lint の回帰テスト用デッキ
• scripts/lint_deck.sh — 文字量と画像の lint
• scripts/extract_visible_text.sh — cold read に渡す、見える文字だけのデッキ
• scripts/render_deck.sh — pdf / pptx / html / png への描画ヘルパー（png ではぼかした PNG も作る）
• scripts/test_lint_deck.sh — lint の回帰テスト（ルールや上限を変えたら実行する）