Menu
Markdown を「人が読みやすく、かつ機械が HTML/スライドへ変換しやすい」構造に執筆・整形する。新規に調査/設計 md を書くときや、既存 md を昇華 (md→HTML→slide) の前に整えるときに使う。「読みやすい md にして」「昇華しやすく整形して」「調査 md を書いて」で起動。
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
| name | readable-md |
| description | Markdown を「人が読みやすく、かつ機械が HTML/スライドへ変換しやすい」構造に執筆・整形する。新規に調査/設計 md を書くときや、既存 md を昇華 (md→HTML→slide) の前に整えるときに使う。「読みやすい md にして」「昇華しやすく整形して」「調査 md を書いて」で起動。 |
| user_invocable | true |
| argument_hint | <target-md-path | topic> [--check-only] |
| origin | ai-research-pipeline/deep-research/readable-markdown-to-html-slide-presentation-2026 |
md→HTML→slide パイプラインの Stage 1。「読みやすい md = 機械が変換しやすい md」 という等式に基づき、md を人にとって読みやすく・後段の変換 (HTML/スライド) が 壊れない構造に揃える。
読みやすい md は、そのまま TOC 自動生成・スライド分割・アクセシビリティを成立させる。 人向けの可読性ルールと、機械向けの変換しやすさは同じもの。
| 状況 | 動作 |
|---|---|
<topic> を渡された (パスでない) | テンプレ (templates/research-skeleton.md) を骨子に新規執筆 |
既存 <path>.md を渡された | 構造を解析し、原則に沿って整形リファクタ (内容は保つ) |
--check-only | 執筆/整形せず、scripts/check-readable-md.sh の結果だけ報告 |
templates/research-skeleton.md を骨子に使う。執筆/整形時に次の 12 原則を満たす (起点レポート §A-1):
| # | 原則 | 対応ルール |
|---|---|---|
| 1 | H1 は 1 文書に 1 つ (タイトル) | MD025 |
| 2 | 見出しを飛ばさない (H2→H4 禁止) | MD001 |
| 3 | ATX 見出し (#) を使う | MD003 |
| 4 | 1 セクション 1 主題 / 1 スライド 1 メッセージ | — |
| 5 | 箇条書きは 3〜5 項目・1 項目 15 語以内 (目安) | — |
| 6 | コードフェンスに言語指定 (```lang) | MD040 |
| 7 | 要素を適材適所 (§A-2) | — |
| 8 | frontmatter で title/date/tags を構造化 | — |
| 9 | 画像に alt、リンクは意味のある語に | MD045/MD042 |
| 10 | 1 文 1 行 or 段落空行区切り (git diff が読みやすい) | — |
| 11 | markdownlint で機械強制 | — |
| 12 | 規則的・予測可能なパターン (= 機械可読性) | — |
| 内容の性質 | 使う要素 |
|---|---|
| 並列・列挙 | 箇条書き - |
| 手順・順序あり | 番号付き 1. |
| 属性 × 対象の比較 | 表 | |
| 連続した説明・論理 | 段落 |
| コマンド・コード | フェンスドコードブロック (言語指定) |
| 注意・補足・引用 | > blockquote |
| 構造図・フロー | コードブロック内 ASCII or Mermaid |
---
title: "<タイトル>"
date: 2026-06-13
tags: [research]
---
title / date は後段の変換 (HTML の <title>、slide のヘッダ) が流用する。
整形後、必ず構造チェッカを通す:
./scripts/check-readable-md.sh <path>.md
# markdownlint も併せて掛けるなら (npx 取得あり):
./scripts/check-readable-md.sh --lint <path>.md
error が出たら直してから完了とする。チェッカは次を機械検証する:
H1 単一 / 見出し非スキップ / コードフェンス言語指定 / frontmatter title・date /
未閉鎖フェンス / インライン style= (warn)。
readable-md で整形しました:
対象: <path>.md
チェック: ✓ error 0 / warn N
次段: /md-to-html <path>.md でHTML化、または Marp で slide 化
style= 等を md に持ち込まない。ai-research-pipeline の deep-research レポート
readable-markdown-to-html-slide-presentation-2026 の §A / §F を実装。Markdown を共通テーマの HTML（画面ダーク / 印刷は A4 ライトテーマ）に変換する。「HTML 化して」「HTML 版を作って」「PDF にしたい」で起動。調査/設計/レポート md の配布・印刷用途に。素早く出すなら scripts/render-html.sh、リッチな card/box レイアウトが要るときは LLM 整形。
調査/レポート md を発表スライド (Marp) に昇華する。report.md を要約・分割して slides.md を作り、HTML/PDF/PPTX に書き出す。「スライドにして」「発表資料を作って」「Marp で」で起動。文書とスライドは編集距離があるため別ファイル (slides.md) として作る。
生成した HTML / スライドが「見た目 human friendly」か、ノンデザイナーズ・デザインブックの C.R.A.P. (Contrast/Repetition/Alignment/Proximity) + タイポグラフィで品質レビューする。「デザインを見て」「読みやすい見た目か」「レイアウトをレビュー」で起動。機械監査 (design-audit.sh) を先に走らせ、静的に測れない整列・近接・視覚的印象を補う。
[2] design を実装単位に分解し、複数の [3] impl issue を起票する ([2]→[3] のブレイクダウン)。[2] を review + needs-human に遷移する。
[1] request を入力に [2] design issue を起票する ([1]→[2] のブレイクダウン)。元の [1] は close する。
status:ready の issue を claim する。遷移直前に ready を再確認してから in-progress へ atomic 遷移し、二重取得のレース窓を最小化する。issue を処理開始する直前に必ず使う。