md-slides-creator

Helps you author a single .md file that is simultaneously:

1. A linear reference doc you can scroll top-to-bottom.
2. A clean slide deck — every ## H2 becomes one slide, and the frontmatter auto-generates the title slide and a final "links" slide.

This is the exact format used by the playbook on https://theomonfort.github.io/theomonfort/playbook/ (Astro content collection rendered by src/pages/playbook/[slug].astro). The skill captures the conventions so anyone — including an agent — can produce a new entry that fits in without manual fixup.

🎯 One rule above all: a slide is everything between two ## headings. Plan the deck slide-by-slide before you write prose.

When to use

Trigger this skill when the user says any of:

• "create a new playbook entry on X"
• "draft slides about X"
• "add an md file in src/content/playbook/..."
• "write a deck on X like the others"
• "explain X as a slide deck"
• "I need a md that breaks into slides on every H2"

If the user only wants prose (a blog post, a README), do not use this skill — pick a more general writing helper.

File layout & destination

In the playbook repo (theomonfort/theomonfort):

src/content/playbook/
  ja/<slug>.md   ← Japanese (primary; the site's default locale)
  en/<slug>.md   ← English mirror (same frontmatter shape, prose translated)

<slug> is kebab-case ASCII. The same slug must exist in both ja/ and en/.

For other projects: any single .md file works as long as the renderer splits on ## H2.

Step 1 — Plan the deck (do this BEFORE writing)

Open with the user and agree on:

1. Title (ja + en) and a 1-line summary (≤ 280 chars).
2. `category` — one of introduction | plan | develop | review | secure | operate. This drives accent color and section ordering on the index page.
3. `color` — magenta | cyan | amber | green. Pick to match category if unsure (cyan for intro/secure, magenta for develop, amber for review, green for plan/operate).
4. `icon` — single emoji or absolute path to an SVG/PNG (e.g. 🪝 or /theomonfort/github-white-icon.svg).
5. `order` — decimal so you can squeeze entries in later (e.g. 19.6).
6. 5–9 H2 slide titles — write them as a numbered outline first. Each one must stand alone on screen.

✋ Do not start writing prose until the slide list is approved. Prose without a slide outline produces walls of text that look fine in the doc but render as one giant unreadable slide.

A typical playbook entry has 6–8 slides:

Adjust freely — but keep ≤ 1 H2 per "concept", and don't let a single slide exceed ~150 words.

Step 2 — Frontmatter

Required schema (Zod-validated in src/content.config.ts):

---
title: フック（Hooks）            # JA in ja/*.md, EN in en/*.md
titleEn: Hooks                    # ALWAYS the English short label (used in TOC)
summary: 1 行説明。280 字以内。
icon: 🪝                          # emoji OR absolute path to /icon.svg
color: green                      # magenta | cyan | amber | green
order: 8.75                       # decimal — leave gaps for future inserts
category: plan                    # introduction | plan | develop | review | secure | operate
related: ['harness-engineering', 'custom-agent']  # other slugs
links:
  - group: 📖 公式ドキュメント
    label: About hooks
    url: https://docs.github.com/en/copilot/concepts/agents/cloud-agent/about-hooks
  - group: 🎓 チュートリアル
    label: Hooks tutorial
    url: https://docs.github.com/en/copilot/tutorials/copilot-cli-hooks
---

Rules

• links[].url MUST be a fully-qualified URL (Zod .url() rejects bare paths).
• Group with emoji prefix: 📖 公式ドキュメント, 🎓 チュートリアル, 📰 発表, 💰 課金, 🆓 無料, 🤖 …. Same group string = same bucket on the rendered page.
• 5–9 links is the sweet spot. <3 looks empty; >12 forces scroll on the last slide.

Step 3 — Body: the slide-splitting contract

The renderer literally does for child in <article>: if child.tagName === 'H2': start a new slide. This means:

So: every section you want as a separate slide MUST start with `##`. To group sub-points on the same slide, use ### or just bullets/tables.

Step 4 — Visual building blocks

These are the recurring patterns the deck uses. Use them — they're styled, accessible, and present-mode friendly. Don't invent new HTML wrappers.

4a. Hero-quote (the "speech bubble" lead block)

Use one per slide max, typically on the first content slide (## 一言で) and occasionally as a section divider mid-deck.

<div class="hero-quote">
  <p>
    <strong>X</strong> は ⋯ する仕組み。
  </p>
  <p>
    一番のポイントは <strong>Y</strong>。
  </p>
</div>

Variants (add a second class):

💡 The secure category auto-applies the blue monocle octocat. Use hero-quote-plain to opt out per-slide.

4b. Comparison tables

GFM tables render with retro styling. Use them for: feature comparisons, pricing, flag references, "before/after", "X vs Y".

| 項目 | A | B |
| --- | --- | --- |
| 価格 | $19/mo | $30/mo |
| 用途 | secret 検出 | コード解析 |

Tips

• Keep ≤ 5 columns and ≤ 8 rows per slide.
• Use emoji as row icons (🔑 / 🔍 / 🛡️) for scannability.
• Bold the column the reader should look at first.

4c. Callouts (> blockquotes)

Use sparingly — 1 to 3 short lines per slide. Always lead with an emoji to set the tone:

> 🎯 **要点**: PreToolUse だけが agent の動きを止められる。
> 🔑 認証は `COPILOT_GITHUB_TOKEN` が最優先。
> ⚠️ classic PAT (`ghp_…`) は使えない。

Common emojis: 🎯 takeaway · 🔑 key · ⚠️ warning · 💡 tip · 📝 note · 🤖 automation · 🔧 config · 🌐 public · 🆓 free · 💰 paid · 📦 module · ✅ do · ❌ don't.

4d. Code blocks

Use fenced code with a language hint (bash, json, yaml, js, ts, python). Each code block must fit on one slide — if it doesn't, split into two slides with ### Step 1 / ### Step 2 headings.

copilot -p "Generate a one-line conventional commit for the staged diff." -s --no-ask-user

4e. Inline external links

Inside prose / table cells / blockquotes, prefer the styled retro-link with an arrow glyph instead of plain markdown links:

<a class="retro-link" href="https://docs.github.com/..." target="_blank" rel="noopener noreferrer">label ↗</a>

Reserve plain [text](url) for the final paragraph "📘 詳細:" listing.

4f. Internal cross-links

Link to another playbook entry by slug:

<a class="retro-link" href="/theomonfort/playbook/dependabot">Dependabot ↗</a>

Step 5 — Authoring workflow (recommended order)

1. Confirm metadata with the user (title, category, color, order, summary). Use a single ask_user form if anything is ambiguous.
2. Write the slide outline as a numbered list of H2 titles. Get user buy-in.
3. Draft the frontmatter with placeholder links[] (you'll fill in URLs after the body).
4. Fill each slide in order, following the visual-blocks recipe. After each slide, mentally check: "would this fit on a 1080p screen at 1.5× font without overflow?"
5. Add 5–9 official links to frontmatter, grouped by emoji-prefix labels.
6. Mirror to the other locale (ja ↔ en). Keep the slide count and frontmatter shape identical; only the prose changes.
7. Build & preview:

   pnpm build              # 32 pages should build with 0 errors
   pnpm dev --host 127.0.0.1   # open http://127.0.0.1:4321/theomonfort/playbook/<slug>/

Press P to enter present mode and arrow through slides — confirm:

• First slide is the title (auto)
• Each ## becomes its own slide
• No slide overflows the viewport
• The final auto-slide shows the grouped links

Step 6 — Final checklist

Before declaring done, verify EVERY item:

• [ ] Frontmatter has all required fields (title, summary, icon, color, order, category).
• [ ] titleEn set (used in TOC + present-mode tag).
• [ ] order doesn't collide with an existing entry (check src/content/playbook/ja/*.md).
• [ ] All links[].url are fully-qualified URLs.
• [ ] Slide count is 5–9.
• [ ] At least one hero-quote block (typically the first content slide).
• [ ] Each slide stands on its own — no orphan H2 with no body, no body before the first H2.
• [ ] Tables ≤ 5 cols, ≤ 8 rows.
• [ ] Code blocks fit one slide each.
• [ ] No # H1 in body (frontmatter handles the title).
• [ ] Both ja/<slug>.md and en/<slug>.md exist with matching structure.
• [ ] pnpm build passes.

References

• references/example.md — a complete, minimal entry showing every block in use.
• references/style-cheatsheet.md — quick-lookup table of categories, colors, hero-quote variants, link-group emojis.