md-to-slidev

箇条書きの Markdown を、Slidev のプレゼンテーションに変換する Skill。

• 入力: 発表したい内容を箇条書きで整理した Markdown（構造は「入力の約束」のとおり）
• 出力: slides.md、slide-plan.md、デザイン部品一式（style.css、layouts/、components/、composables/）。Slidev プロジェクトが無ければ最小の雛形も
• 扱わないこと: PowerPoint・Marp・reveal.js への出力、既存スライドの手直し、画像の生成、入力にない事実の追加

画面の構成

本文スライドは、左に「タイトル → 本文 → 図 → 下段の強調」、右に幅 440px の結論欄（SECTION／CONCLUSION／ページ数）を持つ。タイトルは話題名、主張は右の結論欄に数行で置く。この構成を前提に、以下の原則で書く。

6つの原則

1. タイトルは話題名、主張は結論欄に

タイトルは「何の話か」を名詞句で示す（「トークン」「仕様書の書き方」「人とAIの業務分担」）。各スライドに「見た人に覚えてほしいこと」を1つ決め、結論欄に1行12字程度で改行して置く。結論が2つあるなら分割を提案する。詳細は references/writing.md。

2. 本文は見出し語と中身の階層で組む

本文は、画面だけ読んでも分かる密度にする。1段目に用語・対象・観点、2段目にその定義・性質・例・理由を置く。定義は冒頭に、例は ex) で、1項目に1つの内容。入力の3段目・4段目にある定義・例・理由は本文へ引き上げる。薄い1行だけの本文にしない。

3. 画面は技術用語で言い切る

製品や機能は正式名（Rules・Skills・MCP など）で書き、言い換えの概念名を作らない。比喩（机・本棚・シェフなど）は、入力が指定していても画面に出さず、技術用語に置き換える。比喩は発表者ノートで口頭の補助にとどめる。

4. 図は本文に無い構造を見せる

プロセス・分岐・対比・ループ・会話・階層・構成・範囲は図で示す。図は本文の箇条をそのまま箱に並べ直すものではなく、本文に無い構造（順序・分かれ方・並べた比較・戻り）を足すもの。部品は同梱のもの（Step、Branch、Comparison、Group、Sequence、Shot、Architecture など）を組み合わせ、スライドごとに新しい見た目を考えない。選び方は references/components.md の「図の選び方」。

5. 入力にない事実を足さない

結論は入力から導く。補足が要りそうな箇所は「確認が必要な事項」として報告し、事実として書かない。最新情報（製品の機能・価格・対応状況など）に触れる箇所は、発表前の確認が要ることをノートと報告に書く。

6. デザインは部品に閉じ込める

色・フォント・余白・線幅は style.css の変数と部品が持つ。slides.md には内容と部品の呼び出しだけを書き、<style>、style="…"、色・サイズのクラスを書かない。余白が要るときは <Spacer /> を使う。規則の詳細は references/design-rules.md。

入力の約束

# プレゼンタイトル

- 目的: …            ← 最初の ## より前の箇条書きは前提（目的・聴衆・持ち時間・使われ方）。スライドにしない
- 聴衆: …

## セクション名         ← セクション区切りのスライドになる

- スライド1枚分の文    ← 最上位の箇条書き1つ = スライド1枚。ここから話題名（タイトル）と結論を作る
  - 説明              ← 2段目・3段目 = 本文と図の材料。見出し語と中身の階層に組み直す
    - 補足
      - 詳細          ← 4段目以降 = 定義・例・理由は本文へ引き上げ、話し方の指示はノートか計画へ
- 次のスライド

• 対応は原則 1対1。分割・統合・削除は Step 3 で提案し、承認されたものだけ行う
• 入力に表があれば Comparison に、コードブロックがあればそのままコード表示にする
• ## が無い入力は、セクション区切りなしで扱う。# が無ければタイトルを聞く
• すでにスライド化された Markdown（--- 区切り、layout 指定）や、他の Skill が作った設計書は対象外。箇条書きに直してもらう

ワークフロー

Step 0: 入力と環境の点検

• 入力が「入力の約束」の形か確かめる。違えば、どう直せばよいかを伝えて止まる
• カレントに Slidev プロジェクト（package.json の dependencies に @slidev/cli）があるか見る。あればそこに書く。無ければ Step 6 で雛形を作ることを伝え、置き場所（既定はカレント）を確認する
• 置き場所に slides.md・style.css・layouts/・components/・composables/ が既にあれば、上書きしてよいかを Step 5 の承認と一緒に確認する

Step 1: 前提の確認

# の直下の箇条書きから、目的・聴衆・持ち時間・使われ方（口頭で発表する／配布して読まれる／両方）を読み取る。読めない項目のうち、判断が変わるものだけを聞く（選択式の質問ツールがあればそれを使う）。

• 既定は「両方」向けの密度（原則2）。「口頭のみ」と明示されたときだけ、本文を1段目中心に薄くする
• 持ち時間が分かれば、Step 5 の計画で枚数から見積もって照合する。分からなければ照合しない
• 聞かずに済む項目は「仮定」として計画に明記して進む

Step 2: 内容理解と構造化

入力全体を読み、テーマ・主張・事実・具体例・比較対象・因果関係・時系列・用語を把握する。そのうえでストーリーの型を推定する。

• 入力の ## の順が型と合わないときは、並べ替えを Step 5 の計画で提案する。承認されなければ入力の順のまま。並べ替えを黙って行わない
• 用語の表記を1つに揃える。同じものを指す語が混ざっていたら、正式名に寄せた対応表を計画に書く（「AI → 生成AI」「机 → コンテキストウィンドウ」）

Step 3: スライド分割とタイトル・結論

最上位の箇条書きを1枚ずつスライドにし、タイトルと結論を作る。詳細は references/analysis.md と references/writing.md。

• タイトル: その箇条書きが扱う話題を名詞句で（全角15字程度まで）。段階を追うスライド群は「Lv1.」のような通し番号を前に付ける
• 結論: 2段目以降の内容から、聴衆に覚えてほしいことを1つ導く。1行12字程度で文節ごとに改行し、2〜5行。タイトルの繰り返しにしない
• 下の階層が無く主張も読めないときは、計画に 結論未定 と印を付け、候補を2つ示して承認時に決めてもらう。スキルが入力にない主張を断定しない
• 分割の提案: 1つの箇条書きに結論が2つある、本文が12行を超える、図が2種類要る
• 統合の提案: 隣り合う箇条書きが同じ結論の言い換え
• 削除の提案: 進行だけを伝えるスライド（「90分の流れ」「ここでデモに切り替える」）は内容を持たないので、入力にあっても計画で要否を聞く。承認されなければ作る
• 機能スライド: 表紙（# から）、セクション区切り（## から）。オープニング・まとめ・付録の区切りは章番号を振らない（numbered: false）。目次は入力に目次・流れにあたる箇条書きがあるときだけ。結び（まとめ・呼びかけ）も入力にあるときだけ

結論を番号順に並べ、本文を見ずに読む。飛躍があれば「入力にこういう箇条書きを足すと通る」と提案し、重複があれば統合を提案する。

Step 4: 本文・図・レイアウトの決定

各スライドについて、本文を組み、図の部品とレイアウトを選ぶ。

• 本文: 見出し語と中身の階層に組み直す（references/writing.md）。比喩は技術用語に置き換える
• 図: 内容の型から部品を選ぶ（references/components.md の「図の選び方」）。2つを比べるなら同じ部品を2つ並べる（md-stack に Group ×2）、会話のやりとりは Sequence、戻りのある流れは Step の loop、画面や実物は Shot
• 下段の強調: 結論とは別に、覚えてほしい式・注意・原則が1つあれば ::note:: に EmphasisBox で置く（「トークン数＝コンテキストの消費量＝利用量・コスト」）。結論の言い換えは置かない。横に広い2つ目の図（Branch など）も ::note:: に置ける
• 図にする内容が無いスライドは図なしでよい。図を置くために内容を作らない
• 同じ概念が複数のスライドに出るなら、同じ部品・同じ並びで描き、highlight や overlay で今の話題を示す
• レイアウト: 本文の横に図 → md-standard／本文の下に横長の図・画像 → md-shots／本文の下に図を2〜3個並べる → md-stack／大きな表 → md-wide
• 画像: この Skill は画像を作らない。画面・生成物・公式の図など、実物を見せると伝わるスライドは、入力がそれに触れているときだけ <Shot todo="入れる画像の説明" /> で置き場所を作り、報告で差し込む画像を挙げる

Step 5: スライド計画の承認

ここまでの結果を assets/slide-plan.template.md の形にまとめ、利用者に見せて承認を取る。確認を取るのはこの1回。

計画に含めるもの: 前提と仮定、型と並べ替えの提案、用語の対応表、区切り・目次・結びの有無、スライド一覧（種別・タイトル・結論・本文の骨組み・図・レイアウト）、分割・統合・削除の提案、結論の並びと飛躍・重複、画像の置き場所、本編に入れなかった情報、確認が必要な事項、枚数からの時間の見積もり（持ち時間が分かるとき）。

直しが入ったら計画を更新し、承認されたら slide-plan.md として slides.md の隣に保存する。以降のステップは確認なしで進める。

Step 6: 書き出し

1. Slidev プロジェクトが無ければ、assets/slidev/package.json と gitignore（.gitignore に改名）を置き場所へ書き、npm install を実行する
2. assets/slidev/ の style.css・layouts/・components/・composables/ を置き場所へコピーする。既存のものがあれば Step 0 の確認に従う
3. slides.md を書く。書式は references/components.md の「slides.md の書き方」。完成例は assets/example/slides.md（入力は assets/example/input.md、計画は assets/example/slide-plan.md）
   • 各スライドの末尾の HTML コメントが発表者ノート。1〜3行で、つなぎと要確認だけを書く。想定時間は書かない（references/writing.md の「発表者ノート」）
4. slide-plan.md を保存する（Step 5 で未保存なら）

Step 7: 一貫性と最終チェック

references/checklist.md で全スライドを点検する。特に、タイトルが話題名か、結論が1行12字程度で改行されているか、本文が見出し語と中身の階層になっているか、比喩が画面に残っていないか、用語が揃っているか、図が本文の並べ直しになっていないか、入力にない事実を足していないか、slides.md に色・サイズ・style= を直書きしていないか。違反は該当する Step に戻って直す。

Step 8: ビルドと報告

npx slidev build を実行し、部品の参照エラーや構文エラーが無いことを確かめる。通ったら dist/ を消す。失敗したら直して再実行し、直せない場合はエラーをそのまま報告する。

報告に書くこと:

• 書いたファイルと、npm run dev で開ける旨
• 本編に入れなかった情報と置き場所
• 確認が必要な事項（最新情報の確認、結論の候補のうち選ばなかった方、飛躍の指摘）
• 差し込む画像の一覧（スライド番号、Shot の todo、置き場所の public/ のパス）
• ビルドでは分からない点として、はみ出し・文字の重なり・結論欄の改行位置を実機で見てほしいこと

避けるパターン