mcpField
M
markdown-html-orchestrator

markdown-html-orchestrator

github.com/alirezarezvaniドキュメント28.9k46 回インストール2 日前に更新
リポジトリ

markdown-html-orchestrator について

markdown-html-orchestratorは、長いMarkdownを分類して適切な変換スキルに振り分け、出力先と要約を返します。文書、レビュー、スライド案を単一ファイルのHTMLにする用途向けです。

主な機能

  1. 01文書の決定論的な分類
  2. 023種類の変換スキルへの振り分け
  3. 03100行未満の入力を拒否
  4. 04デザインシステムの導入確認
  5. 05出力先とファイル競合の解決
  6. 06単一HTMLファイルの生成委譲

活用シーン

  1. 01長い仕様書やレポートの変換
  2. 02差分を含むコードレビューのHTML化
  3. 03Markdownのスライド案のHTML化

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/alirezarezvani/claude-skills --skill markdown-html-orchestrator

インストール後、Claude Code で/markdown-html-orchestratorを入力して読み込まれたか確認します。

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

references/
information_density_canon.md
orchestrator_routing_patterns.md
single_file_html_discipline.md
scripts/
doctype_classifier.py
output_path_resolver.py
route_explainer.py

詳細

Markdown → HTML — ドメインオーケストレーター

Thariq Shihiparの主張（Claude CodeのHTML出力に関するエッセイ、Medium 2026）：**エージェントが生成した成果物では、100行を超えるとMarkdownでは不十分になります。**長い仕様書、コードレビュー、アーキテクチャの解説は、テキストが画面に収まらなくなった途端に、情報密度、階層構造、軽量なインタラクションが失われます。HTMLなら、その3つすべてを取り戻せます。単一ファイルで、ブラウザーに標準対応し、共有も可能です。

このオーケストレーターはコンテキストをフォークし、入力のMarkdownを決定論的に分類して、適切なコンバーターのサブスキルに振り分け、出力パスを含む要約を返します。大量の入力データ（Markdown本文全体、差分、スライドデッキ）はフォークしたコンテキスト内に保持されます。

**ドメインの状態（完了）：**5つのスキルすべてが利用可能です。オーケストレーター、design-system（オンボーディング＋共有ブランドトークン）、3つのコンバーターサブスキル（md-document、md-review、md-slides）です。変換は必ず提供済みコンバーターのスクリプトに振り分けてください。HTMLをその場で手動生成してはいけません。

呼び出すタイミング

症状サブスキル
「このRFC／仕様書／レポート／解説をHTMLに変換して」— 長文ドキュメントmd-document
「このPRの説明／コードレビューをHTMLにして」— 差分ブロックを含むMarkdownmd-review
「このMarkdownからスライドデッキを作って」— --- 区切りまたはH1の一定間隔md-slides

事前チェック（厳格な拒否条件）

  1. **100行のしきい値未満。**100行未満ならMarkdownが適しています（Shihipar）。分類器は below_min_lines: true を出力し、route_explainer.py は拒否します。入力はMarkdownのままにするようユーザーに伝えてください。
  2. デザインシステムのオンボーディングが未完了。~/.config/markdown-html/design-system.json が存在しない場合（または setup_completed_at がnullの場合）は拒否します。ユーザーに python3 markdown-html/skills/design-system/scripts/onboard.py を案内してください（手間をかけずに実行する場合は --defaults を指定します）。
  3. **書き込み不可の保存先。**設定済みの default_output_dir（または --out の上書き先）が書き込み不可の場合、output_path_resolver.py は拒否します。

振り分けロジック（決定論的）

research-ops/skills/research-ops-skills/SKILL.md から採用した、2シグナルのしきい値パターンです。ファイル名のヒントは2ポイント、各コンテンツシグナルは1ポイントです。勝者が3ポイント以上で、かつ（次点が0ポイント、または勝者が次点の2倍以上）の場合は、確認なしで振り分けできます。しきい値未満の場合は、推奨回答を添えて確認質問を1つ行います。

シグナル一覧
シグナルの種類ファイル名のヒントコンテンツシグナルサブスキル
DOCUMENTreport.md、*-doc.md、spec.md、rfc-*.md、*-analysis.md、*-explainer.md## Table of Contents（2）、^# 、^## 、Markdownの表の行、> [!NOTE]/[!TIP]/[!IMPORTANT] のコールアウトmd-document
REVIEWreview.md、*-pr-*.md、*.diff.md、code-review*.md```diff（2）、^[-+]{3} （2）、^@@（2）、> [!BLOCKER]/[!MAJOR]/[!MINOR]/[!NIT]（2）、LGTM／nit:／blocker:md-review
SLIDESdeck.md、slides.md、*-talk.md、presentation*.md^---$ が3個以上（2＋区切りごと）、<!-- notes:（2）、H1の数が5以上で、間隔の中央値が12行以下（2）md-slides

パイプライン：

python3 markdown-html/skills/markdown-html-orchestrator/scripts/doctype_classifier.py \
    --input <path>.md --output json \
  | python3 markdown-html/skills/markdown-html-orchestrator/scripts/route_explainer.py

route_explainer.py はデザインシステムの状態を確認し、100行未満の場合の拒否処理を適用したうえで、次のいずれかを出力します：ROUTE_SILENTLY -> md-<type>、ASK_USER one question: ...、または REFUSE — fix the issues above。

ワークフロー

ステップ1 — オンボーディングを確認する

ユーザーがオンボーディングを一度も実行していない場合は、初回セットアップを案内します：

python3 markdown-html/skills/design-system/scripts/onboard.py

質問は10項目で、所要時間は1～2分です。ブランドのプライマリーカラーとアクセントカラー、見出し用／本文用のGoogle Fonts、デザインスタイル（エディトリアル／テクニカル／ミニマル／遊び心のあるデザイン）、既定の出力ディレクトリ、構文テーマ、目次の動作、任意のロゴ／会社情報を設定します。設定は ~/.config/markdown-html/design-system.json に保存されます。--scope project を指定すれば、リポジトリごとの上書き設定として再実行できます。

ステップ2 — 入力を分類する

Markdownに対して doctype_classifier.py を実行します。判定結果を確認してください。

ステップ 3 — 振り分けるか、質問する

分類結果を route_explainer.py に渡します。ROUTE_SILENTLY と判定された場合は、元の Markdown とデザインシステム設定を、フォークしたコンテキスト内で指定されたサブスキルのレンダラーに渡します。ASK_USER と判定された場合は、推奨回答を添えて質問を 1 つだけします。

ステップ 4 — 出力パスを解決する
python3 markdown-html/skills/markdown-html-orchestrator/scripts/output_path_resolver.py \
    --input <path>.md --doctype <document|review|slides>

衝突時のデフォルト処理では -2 / -3 / ... のサフィックスを付けます。タイムスタンプ付きの名前にするには --on-collision timestamp を指定します。

ステップ 5 — サブスキルに引き継ぐ

振り分け先のコンバーターサブスキルのレンダラー（md-document/scripts/、md-review/scripts/、または md-slides/scripts/）が、入力 Markdown、デザインシステム設定、解決済みの出力パスを受け取り、自己完結型の HTML ファイルを 1 つ書き出します。オーケストレーターは 100 語以内の要約を返します。内容は、入力行数、出力パス、適用したデザインスタイル、使用した主な機能 3 つ（目次、検索、コードのコピーなど）、ユーザーへの判断を促す質問 1 つです。HTML を手動でレンダリングしてはいけません。レンダリングはコンバータースクリプトが担当します。

判断を促す質問集（Matt Pocock のドキュメントを使った問い詰めパターン）

質問は 1 つずつ進め、それぞれに推奨回答を添え、根拠となる文献を引用します。このリストを /cs:grill-markdown-html に取り込み、計画段階の質問に使います。

  1. この HTML によってどんな判断ができますか。読み手はざっと目を通すのか、判断するのか、それとも発表するのですか？ 推奨：まず用途を明確にします。情報密度は目的に応じて決まります。根拠：Shihipar —「出力形式を利用状況に合わせる」、Tufte — 『定量情報の視覚的表示』第 1 章。
  2. 入力 Markdown は 100 行以上ですか？ 推奨：はい。100 行未満なら Markdown のままにします。根拠：Shihipar — 100 行未満では Markdown が依然として最適です。
  3. デザインシステムはオンボーディング済みですか？ 推奨：はい。グローバル設定としてオンボーディングします（~/.config/markdown-html/design-system.json）。根拠：research-ops のオンボーディングパターン（research-ops/CLAUDE.md §8）、WCAG 2.2 §1.4.3（テキストのコントラスト比 4.5:1）。
  4. 出力先はどこですか。既存のファイルを上書きしますか？ 推奨：設定済みの default_output_dir を使い、--on-collision suffix を指定します。根拠：Matt Pocock の handoff スキル — 作業中の成果物を黙って上書きしてはいけません。
  5. ドキュメント種別の確度は十分ですか。黙って振り分けますか、それとも質問を 1 つしますか？ 推奨：分類器の判定が document/review/slides のいずれかで、かつ silent_route_allowed: true の場合に限り、黙って振り分けます。それ以外の場合は質問します。根拠：research-ops の 2 シグナルしきい値（research-ops/skills/research-ops-skills/SKILL.md §"Routing logic"）。

レーンが確定する前に、サブスキルを実行してはいけません。

前提

  1. ユーザーは変換したい 100 行以上の Markdown ファイルを持っています。
  2. ユーザーはオンボーディングを一度実行済みです（~/.config/markdown-html/design-system.json が存在し、setup_completed_at が設定されています）。
  3. 単一ファイルの HTML 出力で問題ありません（複数ファイルのサイト、埋め込みサーバー、ビルド手順は不要です）。
  4. 外部リソースは Google Fonts CSS と Prism.js CDN（jsdelivr / cdnjs）に限定します。

対象外

  • ランディングページ生成ツールではありません（marketing/landing/ を使用してください）。
  • 対話型のプロンプト調整用プレイグラウンドではありません（Anthropic の公式 playground プラグインを使用してください）。
  • 静的サイトジェネレーターではありません（複数ファイルの出力やサイトのインデックスはありません）。
  • PDF 生成ツールではありません（スライドは @media print を使用し、ユーザーがブラウザーから印刷します）。
  • 監視やライブリロードのパイプラインではありません（変換は 1 回限りです）。

次のものとは異なります

  • Anthropic Playground プラグイン（/playground） — プロンプト調整用の対話型コントロール（スライダー、ノブ、ドラッグ＆ドロップ）を構築し、プロンプトをコピーして戻すループを備えています。このプラグインは既存の Markdown ドキュメントを HTML に変換します。目的に応じて異なるツールを使います。
  • marketing/landing/ — ランディングページをゼロから生成します（Phase-0 の聞き取り → 3 セクション → ブランドに合わせた TSX/HTML）。このプラグインは、すでにある既存の Markdown ファイルを変換します。
  • engineering/handoff/ + productivity/handoff/ — Claude の会話間でセッションの継続性を保ちます。成果物の種類が異なります（引き継ぎ概要とドキュメント変換）。

出力成果物

サブスキル成果物ステータス
md-documentdoc-<slug>.html（単一ファイル、固定目次、折りたたみ表示、検索、コードのコピー、スクロール位置追跡）✓ 稼働中
md-reviewreview-<slug>.html（2 列の差分＋重要度の余白注釈＋ジャンプナビゲーション）✓ 稼働中
md-slidesdeck-<slug>.html（矢印キーでのナビゲーション＋プレゼンターモード＋PDF 印刷）✓ 稼働中

アンチパターン（禁止事項）

  • ❌ 100 行未満の Markdown を変換する — Markdown のほうが適しています。断り、ユーザーに伝えてください。
  • ❌ デザインシステムをオンボーディングする前にオーケストレーターを実行する。トークンがないと、出力が崩れて見えます。
  • ❌ 2 つのサブスキルを黙って連続実行する（例：「ドキュメントを変換して、さらにスライドも作成する」）。1 つを選んで完了し、次を連続実行する前に確認してください。
  • ❌ 外部 JavaScript フレームワーク（React/Vue/Svelte）を使う。Vanilla JS と IntersectionObserver のみ使用してください。唯一の例外は Prism.js CDN です。
  • ❌ 複数ファイルに出力する（CSS の抽出、アセットディレクトリなど）。単一ファイルでなければ出力しない — それが全体の要点です。
  • ❌ 既存の出力ファイルをデフォルトで上書きする。パスリゾルバーは -2、-3、…を付加します。--on-collision overwrite は明示的に指定された場合のみ有効です。

参考資料

  • 仕様：Thariq Shihipar — 「Claude Code HTML output」（Medium、2026 年）
  • フォークのパターン：research-ops/skills/research-ops-skills/SKILL.md（context: fork、2 シグナルルーティング）
  • カスタマイズのパターン：research-ops/skills/clinical-research/scripts/（onboard.py、config_loader.py）
  • ブランドパレットの計算：marketing/landing/skills/landing/scripts/brand_palette_validator.py（WCAG ＋ HSL による導出）
  • 情報密度の規範：Tufte、Shihipar の thariqs.github.io/html-effectiveness/ ギャラリー、Wattenberger のインタラクティブエッセイ、Maggie Appleton のデジタルガーデン

コメント

Markdown 対応