日本語 HTML ドキュメント

ドキュメントは、スタイルシートと埋め込みスクリプトを内包した単一の HTML ファイル。テンプレートを複製し、<title> と <article> の中身だけを書く。スタイルシートと埋め込みスクリプトはテンプレートのまま残す。

以下、$SKILL_DIR はこの SKILL.md があるディレクトリを指す。

文章は次のスキルの規範に従って書く。HTML ドキュメントに固有の決まりは、下の「表記規約」に書いた。

japanese-tech-writing と cognitive-rhythm-writing は、k16shikano さんが作成したスキルを取り込んだもの。引用元は各ディレクトリの SOURCE.md にある。

手順

0. 文章のルールを読み込む：japanese-base-writing と japanese-tech-writing のスキルを呼び出す。スキルとして呼び出せない環境では、$SKILL_DIR/../<スキル名>/SKILL.md を読む。そのうえで、ドキュメントの 読み手 と 目的 を決める（S-01）。読み手が決まらない場合は、依頼者に確認する。 完了条件：読み手と目的が決まっている。
1. 文書種別を決める：依頼から技術解説・手順書・提案書・報告書のいずれかを選び、references/structures.md の該当する節を読む。どれにも当てはまらなければ技術解説を土台にする。技術解説か提案書なら、cognitive-rhythm-writing のスキルも呼び出す。手順書と報告書では使わない（読み手は必要な情報を早く正確に拾いたいので、緩急よりも一覧性を優先する）。 完了条件：セクション見出しの一覧（5〜15個、最後は「用語集」）が決まっている。
2. テンプレートを複製する：作業ディレクトリに <slug>.html として複製する。slug は内容を表す英小文字とハイフン。

   cp "$SKILL_DIR/template.html" <slug>.html

   以降の編集対象は <title> と <article> の中だけ。<style> と <script> の中身は読まずに済む。
3. ドキュメントヘッダを書く：<title> と <h1> に同じタイトルを入れる。更新日は今日の日付（date +%Y-%m-%d）。「要点」ボックスには要約を2〜3行で書く。読み手が本文を読まずに結論と要旨をつかめる内容にする。
4. 本文を書く：手順 1 の構成に沿って、セクションを <section> と <h2 id="英小文字-ハイフン"> で書く。部品は references/components.md の HTML をそのまま使う。図を描くときは references/figures.md を読む。文章は冒頭の表に挙げた規範と、下の「表記規約」に従う。 完了条件：構成のすべてのセクションが本文で埋まっている。
5. 用語集を書く：最後のセクションを <h2 id="glossary">用語集</h2> とし、本文に出てきた専門用語と略語を、出てきた順にすべて dl.terms で定義する。
6. コード強調スクリプトを埋め込む：コードブロックがあるときだけ、次のコマンドで挿入する。スニペットは約 126KB の圧縮済み JS なので、コマンドで挿入し、中身は読まない。

   awk -v f="$SKILL_DIR/highlight-snippet.html" '{print} /<!-- コード強調スクリプト/{while((getline l < f)>0) print l}' <slug>.html > <slug>.tmp && mv <slug>.tmp <slug>.html

7. 仕上げを確認する：次の項目をすべて満たすまで直す。
   • grep -c '{{' <slug>.html が 0（テンプレートのプレースホルダが残っていない）
   • 最後のセクションが用語集
   • 使っている独自クラスがすべて components.md に載っている
   • CSS・JS・フォント・画像を外部から読み込んでいない（外部ページへの <a> リンクは可）
   • 表記規約をすべて守っている
   • japanese-base-writing の「文章を見直すとき」の手順で本文を見直し、違反箇所をすべて直した
   • japanese-tech-writing の「LLM っぽい表現の禁止」と「翻訳調の比喩と擬人化の禁止」で本文を点検し、該当箇所をすべて直した
   • cognitive-rhythm-writing を使ったときは、その「執筆後の点検手順」をすべて実施した

最後に、作成したファイルのパスを伝える。

表記規約

冒頭の表に挙げた規範に加えて、次の規約を守る。規範どうしがぶつかる場合は、この規約、japanese-tech-writing、japanese-base-writing の順に優先する。cognitive-rhythm-writing は、これらの規範の範囲内で使う。

• 文体は「です・ます調」。句読点は「、」と「。」。
• 英数字は半角、括弧は全角の「（）」。
• 和文と英数字は詰めて書く（例：「APIゲートウェイ」「10分」「<code>npm</code>で実行」）。間隔はブラウザが自動で調整する。
• 見出しは <h2>（セクション）と <h3>（小見出し）の2段階。
• 強調は <strong> だけを使う。
• 図と表の番号は「図1　…」「表1　…」の形で、番号のあとに全角スペースを入れる。
• 「要点」の見出しは要約専用。本文で結論を強調するときは「補足」の注記を使う。
• 画像は、ユーザーから渡されたものを base64 の data URI にして <figure><img alt="…"> で埋め込む。
• 独自クラスは components.md に載っているものだけを使う。見出し・段落・リスト・表などはクラスなしで書く。