Claude CodeでMarpの勉強会スライドをMarkdownから作る手順

勉強会のスライドは、Markdownで書いてMarpで変換すると、Claude Codeに任せやすい形になります。入力がただのテキストなので、構成の修正は差分で見え、直した結果はコマンド1本でPDFやPPTXに書き出せるからです。ここでは、勉強会の構成案をMarp用Markdownにする、marp-cliで書き出す、1枚に詰め込みすぎたスライドを見つける、スキルにして毎回同じ手順で回す、の順で進めます。

Marpは何で、Claude Codeに何を任せるのか

Marpは、Markdownからスライドを作るためのツール群です。変換を担うコマンドラインツールが @marp-team/marp-cli で、Marp / Marpit形式のMarkdownをHTML、PDF、PowerPointドキュメント(PPTX)、画像に変換できます。

役割を分けると、Claude Codeが書くのはMarkdownだけです。レイアウトの計算は変換側が持つので、Claude Codeは「何を何枚目に置くか」に集中できます。

前提は2つです。Node.jsはv18以降が必要で、PDF、PPTX、画像への変換にはGoogle Chrome、Microsoft Edge、Mozilla Firefoxのいずれかが要ります。HTMLへの変換だけならブラウザは不要です。ブラウザを入れたくない場合は、公式のコンテナイメージ(marpteam/marp-cli)を使う方法もあります。

PowerPointファイルそのものを作る別の道については、Claudeのpptxスキルの使い方で、作成・編集・読み取りの分岐を扱っています。Marpは、スライドの正本をMarkdownに置いて版管理したい場面に向く選択肢です。

勉強会の構成をMarp用Markdownに書かせる

最初にClaude Codeへ渡す指示は、スライドの枚数と1枚あたりの量を先に決めておくと外れにくくなります。次のような依頼文が出発点になります。

社内勉強会「Claude Codeのhooks入門」(30分・質疑5分)のスライドを
slides/hooks.md に書いてください。
 
- 形式はMarp用Markdown。frontmatterに marp: true と paginate: true
- 区切りは --- 。1枚の本文は箇条書き5項目以内
- 各スライドに話す内容を HTML コメントで書く(発表者ノート)
- 構成: 目的 / hooksとは / 実例3つ / 落とし穴 / 質疑

返ってくるMarkdownは、おおよそ次のような形になります。これは書き方の例で、実際の出力は指示とプロジェクトによって変わります。

---
marp: true
paginate: true
footer: "社内勉強会 Claude Code hooks入門"
---
 
# Claude Codeのhooks入門
 
社内勉強会 / 30分
 
---
 
## この勉強会のゴール
 
- hooksが何を自動化するかを説明できる
- 自分のリポジトリに1つ入れられる
 
<!-- ここで挙手: hooksを触ったことがある人 -->
 
---
 
## hooksとは
 
- ツール実行の前後で任意のコマンドを走らせる仕組み
- 設定は settings.json に書く

前書きに使うディレクティブ

Marpit形式のMarkdownでは、先頭のYAML front-matterか、HTMLコメントでディレクティブを書きます。勉強会の資料で使う機会が多いものは次のとおりです。

「全体」の指定は最後に書いた値だけが有効です。「各ページ」の指定は、書いたページ以降に効きます。そのページだけに効かせたいときは、名前の前に _ を付けて _paginate: false のように書きます。表紙のページ番号を消したいときに使います。

headingDivider: 2 を指定すると、--- を書かなくても ## の手前でスライドが分かれます。Claude Codeに書かせるときは、区切りの書き忘れが減るので扱いやすい設定です。

発表者ノートには、HTMLコメントを使います。ディレクティブとして解釈されたコメントはノートに入らず、それ以外のコメントがノートとして扱われます。

marp-cliでPDFとPPTXに書き出す

変換はインストール不要の npx で始められます。常用するなら、プロジェクトの開発依存に入れてバージョンを固定する方法が公式の推奨です。

# 開発依存に入れて、バージョンをロックファイルで固定する
npm install --save-dev @marp-team/marp-cli
 
# PDFに書き出す
npx marp slides/hooks.md --pdf
 
# PPTXに書き出す
npx marp slides/hooks.md --pptx
 
# 出力先を指定する(拡張子で形式が決まる)
npx marp slides/hooks.md -o dist/hooks.pdf

出力先の拡張子を .pdf や .pptx にすれば、--pdf や --pptx は省けます。

配布形式による違い

勉強会の資料は、当日投影するものと、後から共有するものが別になりがちです。PDFとPPTXの性質を押さえておくと、どちらを渡すかを決めやすくなります。

PPTXは、PowerPoint、Keynote、Google Slides、LibreOffice Impressで開けます。標準のPPTXは描画済みの画像で組まれるので、受け取った人が文字を直す用途には向きません。直せるPPTXが必要なら実験的な --pptx-editable がありますが、ブラウザに加えてLibreOffice Impressが必要です。再現性は通常のPPTXより下がり、発表者ノートも出ません。公式も、見た目を保ちたいときは勧めていません。

画像を使うときの落とし穴

ブラウザ経由の変換は、セキュリティ上の理由で既定ではローカルファイルを読みません。スライドにローカルの画像を貼ると、警告が出て不完全な出力になります。信頼できるMarkdownに限り、--allow-local-files で許可できます。

npx marp slides/hooks.md --pdf --allow-local-files

公式は、画像をオンラインに置く運用を勧めています。社内資料で外部に出せない画像を使うときだけ、このオプションを付ける形になります。

詰め込みすぎたスライドを見つける

勉強会のスライドで最も多い失敗は、1枚に項目を詰め込んで、文字が小さくなるか枠から出ることです。公式READMEには、はみ出しを検出するオプションの記載はありません。そこで、変換前の検査と、変換後の目視を組み合わせます。

行数を数える検査スクリプト

変換前の検査は、スライドごとの空行を除いた行数を数えるだけの簡単な方法で足ります。厳密なはみ出し判定ではなく、詰め込みの目安です。

// scripts/check-density.mjs
import { readFileSync } from "node:fs";
 
const [file, maxLines = "9"] = process.argv.slice(2);
const text = readFileSync(file, "utf8").replace(/\r\n/g, "\n");
const body = text.replace(/^---\n[\s\S]*?\n---\n/, "");
const slides = body.split(/^---\s*$/m);
 
let bad = 0;
slides.forEach((slide, i) => {
  const lines = slide
    .replace(/<!--[\s\S]*?-->/g, "")
    .split("\n")
    .filter((l) => l.trim() !== "");
  if (lines.length > Number(maxLines)) {
    bad++;
    console.log(`slide ${i + 1}: ${lines.length} lines (limit ${maxLines})`);
  }
});
console.log(bad ? `${bad} slide(s) over the limit` : "ok");
process.exit(bad ? 1 : 0);

先頭のfront-matterを取り除き、--- でスライドを分け、HTMLコメント(発表者ノート)は数えません。上限を超えたスライドがあれば終了コード1で終わるので、Claude Codeが結果を読んで直すループに乗せられます。headingDivider で区切っているデッキには、このスクリプトはそのまま使えません。区切りに --- を使う運用に揃えておくのが前提です。

画像にしてClaude Codeに見せる

行数が収まっていても、1行が長くて折り返し、枠から出ることはあります。最後の確認には、--images で各ページをPNGにします。出力ファイルにはページ番号の接尾辞が付き、公式の例では slide-deck.001.png、slide-deck.002.png のように並びます。

mkdir -p dist/preview
npx marp slides/hooks.md --images png -o dist/preview/hooks.png

Claude Codeは画像ファイルを読めるので、「dist/preview のPNGを順に見て、文字が枠からはみ出しているページを番号で挙げて」と頼めます。挙がったページの文量を減らし、もう一度書き出して同じ確認をする、という反復になります。画像を読んだ判定は完全ではないため、最後に人間が全ページをめくる前提にしてください。

手順をスキルにして毎回同じ形で回す

同じ手順を毎回プロンプトで説明するのは手間です。スキルにすれば、/study-deck と打つだけで、構成、変換、検査までを同じ順序で進められます。プロジェクトのスキルは .claude/skills/<名前>/SKILL.md に置きます。

---
name: study-deck
description: 勉強会のスライドをMarp用Markdownで書き、PDFとPPTXに書き出す。勉強会、社内発表、スライド作成を頼まれたときに使う。
allowed-tools:
  - Bash(npx marp *)
  - Bash(node ${CLAUDE_SKILL_DIR}/scripts/check-density.mjs *)
---
 
## 手順
 
1. 発表時間から枚数を決める(1枚あたり1〜2分)
2. slides/<題名>.md に書く。frontmatter は marp: true と paginate: true
3. 区切りは --- 。1枚の本文は箇条書き5項目以内
4. 話す内容は HTML コメントで書く
5. node ${CLAUDE_SKILL_DIR}/scripts/check-density.mjs slides/<題名>.md を実行し、超過を直す
6. npx marp で PDF と PPTX を dist/ に出す
7. --images png で画像にして、はみ出したページを確認する

allowed-tools は、スキルを呼び出したターンのあいだだけ、列挙したツールを確認なしで使えるようにします。次のメッセージを送ると効力は切れます。検査スクリプトはスキルのディレクトリ(scripts/check-density.mjs)に同梱し、${CLAUDE_SKILL_DIR} で参照します。スキルがほかの場所に置かれても、allowed-tools のルールと本文のコマンドが同じパスに展開されるので、許可と実行が食い違いません。

description は、Claudeがスキルを自動で選ぶ手がかりです。「勉強会」「社内発表」のような依頼で出てくる語を入れておくと、/study-deck と打たなくても読み込まれやすくなります。

CLAUDE.mdに書いておくこと

スキルを使わない場面でも、デッキの規約はCLAUDE.mdに1箇所だけ残しておくとぶれません。

## スライド(slides/)
- Marp用Markdown。区切りは --- 、1枚の本文は箇条書き5項目以内
- 変換は npx marp。PDF は dist/ に出力し、dist/ はコミットしない
- ローカル画像を使うときだけ --allow-local-files を付ける

つまずきやすい点

PDFもPPTXも出ない。ブラウザが見つかっていない可能性があります。Chrome、Edge、Firefoxのいずれかが必要で、見つからないときは --browser-path で実行ファイルのパスを渡します。--browser firefox,chrome のようにカンマ区切りで指定すると、先に見つかったものを使います。

画像が真っ白になる。ローカルファイルの参照が既定でブロックされています。画像をオンラインに置くか、--allow-local-files を付けます。

PPTXの文字を後から直せない。標準のPPTXは描画済みの画像です。直す前提の資料はMarkdown側で直して再出力するか、実験的な --pptx-editable を試します。

投影時の画質が気になる。PPTXでは、全画面で表示したときの劣化を抑えるため、既定の拡大率が2です。変えたいときは --image-scale で指定します。

変換結果をその場で見たい。 -w(--watch)で、MarkdownとテーマCSSの変更のたびに再変換できます。HTMLをブラウザで開いておけば、ページも自動で更新されます。構成を詰める段階では、この監視モードを使いながらClaude Codeに直させると往復が速くなります。

文書全体をPDFやdocxにしたい場面は、スライドではなくClaude CodeでPandocを使う手順のほうが向いています。スライドはMarp、報告書や手順書はPandocと使い分けると、どちらもMarkdownを正本にできます。

まとめ

スライドの構成と文面をClaude Codeに書かせ、見た目の計算は変換ツールに任せるのがMarpの分担です。勉強会の資料では、1枚の量を数値で決めて検査すること、PDFは共有用、PPTXは投影用と役割を分けることが、手戻りを減らします。

はみ出しの確認だけは、公式にオプションがないぶん、行数の検査と画像の目視で補う必要があります。手順をスキルに固定しておけば、次の勉強会でも同じ品質の流れを再現できます。