2026-05-2611分

【続編】SKILL.md は .md、成果物は HTML — Anthropic の両方推奨を3レイヤーで読み解く

Claude Code PMBOK-AI AIエージェント AI活用生成AI MCP AI開発

Summary

私は2026年5月7日に「AIエージェント10種の正体は.mdファイルだった」を公開した。その翌日、Anthropic Claude Code エンジニアリングリードの Thariq Shihipar が「HTML が AI 成果物の新デフォルト」と提唱し、16時間で440万viewを叩き出した。一見矛盾する2つの主張。だが両者は補完関係にある。答えは「3レイヤー」で考えること——A: エージェント定義、B: 中間生成物、C: 最終成果物。AレイヤーとBレイヤーは Markdown、C レイヤーは HTML。同じ Anthropic がなぜ両方を推奨するのか、レイヤーを切り分ければすべてが整合する。本記事ではこの3レイヤー設計を、panda-hq での6つの実例（私が今朝のFDE記事で実際にHTML→PNGで作った挿絵を含む）で具体的に示し、AIエージェント設計者・SKILL.md作者が明日から使える設計指針までまとめる。

2026年5月7日、私は「AIエージェント10種の正体は.mdファイルだった」を公開した。 Anthropic 金融エージェント10種の GitHub リポジトリを全部解剖し、「正体は.md ファイル集だ」と論じた記事だ。

その翌日。Anthropic の Claude Code エンジニアリングリードである Thariq Shihipar が X で 「HTML が AI 成果物の新デフォルト」 と提唱した。16時間で 440万view・8,200 likes・15,700 bookmarks。AI業界が一斉に「Markdown の時代は終わった」と騒いだ。

私の記事と、Thariq の主張。一見、完全に矛盾している。

だが結論を先に書く。両者は矛盾しない。レイヤーが違うだけだ。AIエージェント設計者にとって本当に必要なのは「.md か HTML か」の二択ではなく、3つのレイヤーで考えることだ。本記事ではこの3レイヤー設計を、Anthropic 公式情報と私自身の panda-hq での6つの実例で示す。

答えを先に：3レイヤーで考える

AIエージェントの周辺で動くテキストには、3つのレイヤーがある。

レイヤー	推奨フォーマット	根拠	例
A. エージェント定義・スキル	Markdown (.md)	SKILL.md 公式推奨。機械可読+人間可読の最適解	`.claude/agents/*.md`、SKILL.md、CLAUDE.md
B. 中間生成物・エージェント間ループ	Markdown	トークン4-8倍効率、git friendly、ML親和性	リサーチノート、要件定義、GitHub Issue
C. 最終成果物（人間が読む）	HTML	レイアウト・スタイル・インタラクティブ。Anthropic内部の新デフォルト	レポート、ダッシュボード、ブログ挿絵、スライド

これだけ覚えて帰ってもらえれば、本記事の80%は達成だ。残りはこの3レイヤーを「なぜそうなのか」「どう実装するか」で具体化する。

A レイヤー：エージェント定義は今も Markdown

私が直前記事で書いた「.mdが正体」は、このレイヤーの話だ。

Anthropic 公式の anthropics/skills リポジトリで規定されている SKILL.md フォーマットは、Markdown + YAML frontmatter の構造を採用している。Anthropic は公式ドキュメントで 「SKILL.md は機械可読+人間可読の最適バランスとして Markdown を意図的に選択した」 と明言している。

これは Thariq の HTML 推奨が出た後も変わっていない。SKILL.md フォーマットの公式仕様は依然 Markdown だ。

ずんべぇ

でも「HTMLが新デフォルト」なら、SKILL.md も HTML に書き換えるべきですよね？

うぉんば

いや、それは読む相手が違う。SKILL.md を読むのはエージェント、HTML を読むのは人間だ。

ずんべぇ

えっ、読む相手…？

うぉんば

エージェントに読ませるテキストは、軽くて機械可読な Markdown が最適。装飾はいらない。

ずんべぇ

なるほど…だから公式仕様も Markdown のまま、と。

うぉんば

そう。HTML が勝ったのは人間が読む成果物だけ。定義ファイルは別レイヤーだ。

panda-hq の A レイヤー実例

私の会社では、AI社員（ずんべぇ・すいっぺ・あざらす・うぉんば）の定義を .claude/agents/*.md に置いている。

例1: .claude/agents/script-writer.md

YMM4 動画用の台本を書くエージェント定義。name description の YAML frontmatter + Markdown 本文で、キャラ設定・口調ルール・ファイル所有権を記述している。Claude Code がセッション起動時にこれを読み、必要な時にこのエージェントを呼び出す。HTML にする理由がない。エージェントが「読む」だけだからだ。

例2: .claude/skills/skill_manage_calendar.md

Google Calendar 操作のスキル定義。MCP 接続情報・予定 CRUD の手順・HitL ゲート（create/update/delete は承認必須）を Markdown で書いている。エージェントから呼び出される時、Claude はこの Markdown をそのまま読んで実行する。

A レイヤーの本質は、「テキストはエージェントが消費する」 こと。人間が読むのは「設計時」と「デバッグ時」だけ。Markdown で十分どころか、最適だ。

B レイヤー：中間生成物も Markdown

エージェントが動く過程で生まれる中間ファイル——リサーチノート、要件定義、Issue、プロンプトのテンプレート——これも Markdown が圧倒的に強い。

理由はシンプルだ。トークンコストが HTML の1/4〜1/8。Cloudflare の解析では、同じ内容のドキュメントを HTML から Markdown に変換すると 約80%のトークン削減になる。1,000語のドキュメントが、Markdown 250トークン vs HTML 1,500トークン。

エージェント間でファイルを引き渡したり、コンテキストに大量のドキュメントを積む B レイヤーでは、このコスト差が累積する。私がSaaS開発1人体制で 4,000ターン超の Claude Code を回した時、Bレイヤーが HTML だったら API コストが破綻していた。

panda-hq の B レイヤー実例

例1: business/research/2026-05-26-fde-japan-4companies.md

今朝公開した FDE 記事を書く時、リサーチ素材をこのファイルに 250 行近く書き溜めた。比較表・差別化インサイト・SEO キーワード・Sources 全件——すべて Markdown。これを /pmbok-b2-write が読み込んで企画書に変換する。ここで HTML を使う合理的理由はゼロ。表は Markdown の | 記法で十分、編集も diff も git friendly。

例2: GitHub Issue 駆動の開発フロー

SaaS開発で 1機能 = 1 Issue の粒度に分解し、Claude Code に投げる運用をしている。Issue 本文は Markdown 一択。GitHub がネイティブにレンダリングし、Slack 通知でもそのまま読める。

B レイヤーは「エージェントと人間が交互に触る」場所だ。git で diff が読めること、ターミナルで grep できること、トークンが軽いこと——これらの要件を全部満たすのは Markdown だけだ。

C レイヤー：最終成果物は HTML

ここからが Thariq の主張する領域だ。人間が「読んで判断する」最終成果物——プラン、レビュー、レポート、ダッシュボード、監査結果——これは HTML が圧倒的に強い。

Thariq が示した HTML の4つの優位性を整理する。

情報密度 — テーブル / SVG / CSS / JavaScript / 画像を1ファイルに埋め込める。Markdown では不可能
可読性閾値 — 100行を超えると Markdown は事実上読めなくなる。HTML は折りたたみ・タブ・ナビで対応可能
共有効率 — HTML はブラウザで即レンダリング。Markdown はエディタが必要で、ステークホルダーが読まない
インタラクティブ性 — スライダー・トグル・ボタンで「ユーザー操作 = 次のプロンプト」になる探索ツール化

Thariq 本人の 20 件 head-to-head 比較では、HTML が 17 件で勝利したとのこと。Anthropic 内部の Claude Code チームは既に HTML を新デフォルトとして採用している。

panda-hq の C レイヤー実例

例1: ブログ挿絵 HTML → PNG（今朝、本記事の前段で実証済み）

今朝公開した FDE 記事で、私は挿絵 4 枚を book/figures/blog/fde-three-paths-japan-4companies-*.html として HTML で書き、Puppeteer で PNG 化した。共通 CSS（book/figures/common/figure.css）には --accent --sub --success といったデザイントークン、.fig-card .compare-container といったコンポーネントクラスが定義されている。

この記事の挿絵 4 枚も、同じ仕組みで生成している。Markdown では絶対に作れない図表が、HTML なら制御可能だ。これは Thariq の言う「情報密度」「視覚的表現」の典型例だ。

例2: YMM4 動画スライド HTML → PNG

書籍 PMBOK-AI の動画版（CH01-04 公開済み）で、スライド18 枚を book/video/chXX/slides/*.html として作成している。1920×1080 のキャンバスに、CSS Grid と Flex でレイアウト、step アニメーション用に data-step 属性を使う。最終出力は PNG 18 枚 × 章数。

動画素材も「人間が見る最終成果物」だ。だから HTML で作る。Markdown で書いたら、デザインの自由度が崩壊する。

C レイヤーでも Markdown が残る6シナリオ

ただし、C レイヤーが常に HTML 一択ではない。Thariq 本人が「Markdown を残すべき」と挙げた 6 シナリオを引用する。

Repository ドキュメント（GitHub/GitLab がネイティブにレンダリングし、検索インデックスにも乗る）
Slack / Discord スニペット（code-fence の汎用性）
ML training データ（学習データのパターン親和性）
Git 中心ワークフロー（line-by-line blame の明確性）
個人ノート（単独著者・編集頻度高）
RSS / Email newsletter（クライアントレンダリング不安定性）

ブログ記事の本文（このMDXを含む）も、実質「リポジトリドキュメント」の特性が強い。だから本文は Markdown のままで、挿絵だけ HTML→PNG が最適解になる。

「C レイヤーは HTML」と言っても、機械的な置き換えではない。「人間が一度限り読んで判断する深いコンテンツ」が HTML、「継続的にバージョン管理する文書」は Markdown という線引きが本質だ。

ずんべぇ

じゃあ人間が読む成果物は、全部 HTML にすればいいんですね！

うぉんば

そこも一段深い。同じ人間が読む文書でも、一度きりか継続管理かで分かれる。

ずんべぇ

一度きり…？

うぉんば

レポートや監査結果は、読んで判断したら終わり。だから HTML。

ずんべぇ

このブログ本文は…毎回 git で更新してますよね。

うぉんば

そう、だから Markdown のまま。軸は「読む回数と管理方法」だ。

エージェント設計者への実践指針

AIエージェント設計者・SKILL.md 作者向けに、3レイヤー設計のチェックリストをまとめる。

A レイヤー設計時

SKILL.md フォーマット（YAML frontmatter + Markdown body）に準拠する
エージェント定義は短く、責務を1つに絞る
HitL ゲート（破壊的操作の承認）を Markdown 内に明文化する
HTML 化の誘惑に負けない（人間ではなくエージェントが読むため）

B レイヤー設計時

エージェント間で引き渡すドキュメントは Markdown 統一
git で diff が読める粒度に分割する
トークン消費を意識し、不要な装飾を避ける
中間生成物には日付プレフィックスをつけて履歴化する（私の business/research/YYYY-MM-DD-*.md 流儀）

C レイヤー設計時

「誰が、いつ、どの場面で読むか」を最初に決める
一度限りの判断材料なら HTML、継続管理なら Markdown を選ぶ
HTML 化する場合、デザイントークン（CSS variables）を統一する
PNG 化する場合、Puppeteer などで自動化する
トークンコストの増加を見越して、生成頻度を最適化する

全体設計

3レイヤーを混在させない（A の中に C のスタイルを混ぜると保守が崩れる）
レイヤー間の境界（Markdown→HTML 変換ポイント）を明示する
レイヤーごとに別ディレクトリで管理する（私の .claude/ / business/ / book/figures/ がそれ）

まとめ：論争ではなく補完

ここまでをまとめる。

Anthropic の Thariq が提唱する「HTML が AI 成果物の新デフォルト」は事実
だが SKILL.md は依然 Markdown 公式推奨で、変わっていない
両者は矛盾しない。3レイヤー（A定義 / B中間 / C成果物）で切り分ければ整合する
A と B は Markdown、C は HTML（ただし C にも Markdown が残る6例外あり）
AIエージェント設計者は、3レイヤーを意識して設計すれば、Anthropic の主張も自分の運用も両立できる

私が直前に書いた「.mdが正体」記事は A レイヤーの話で、Thariq の主張は C レイヤーの話だ。同じ Anthropic から出てきた2つのメッセージは、対立ではなく、設計レイヤーの違いとして読むのが正しい。

panda-hq では、.claude/agents/*.md（A）、business/research/*.md（B）、book/figures/blog/*.html → PNG（C）の3層を厳格に分けて運用している。本記事の挿絵 4 枚も、Thariq が言う通り HTML で作って PNG にした。論争を経た上での、最も Anthropic 公式な答えがこれだ。

「.md か HTML か」で迷ったら、自分が今書いているのはどのレイヤーかを問え。答えは自然に出る。