delegate-htmldoc · diff

git:20260910.f97ba97 to git:20260910.4f1b5e2

2 added, 2 removed. Audit A to A.

---

name: delegate-htmldoc

license: MIT

description: >

token cost の削減とデザインの一貫性確保を目標として、固定デザインテンプレートに沿った

自己完結型 HTML ドキュメントの生成を安価な subagent に委譲するスキル。

調査結果・レポート・issue まとめ・技術資料・議事録などを「HTML で」「ドキュメントにして」

「レポート化して」といった形で文書化する要求に使う。

同梱テンプレートの CSS と component 語彙に content を流し込むため、実行ごとのデザイン揺れがない。

対象は静的文書のみ。ダッシュボードなどインタラクティブ・JS を要する成果物、

デザインの新規設計、Web アプリの UI 実装には使わない（delegate-implement を使う）。

htmldoc の作業を委譲する場合は、この skill を使う。generic な subagent で代替しない。

allowed-tools: Bash(bash .claude/skills/delegate-htmldoc/scripts/run.sh:*), Bash(bash .claude/skills/delegate-htmldoc/scripts/prepare.sh:*), Bash(bash .claude/skills/delegate-htmldoc/scripts/dispatch.sh:*), Bash(bash .claude/skills/delegate-htmldoc/scripts/read-request.sh:*), Bash(bash .claude/skills/delegate-htmldoc/scripts/read-response.sh:*), Bash(bash .claude/skills/delegate-htmldoc/scripts/read-json.sh:*), Bash(test -f:*), Bash(ls:*), Read, AskUserQuestion

---

# delegate-htmldoc

固定テンプレートに沿った HTML ドキュメント生成を委譲する。task_type=`htmldoc`、既定モデル `haiku`（テンプレート固定の流し込み作業のため判断比重が低い）。実行系分岐（Codex / Devin / Cursor / Claude / OpenCode）は `dispatch.sh` が行う。`opencode/<provider>/<model>` を使う場合は `opencode` CLI（ログイン済み）が必要。

## スクリプトパス

- Claude Code: `skill_dir=.claude/skills/delegate-htmldoc`

- Codex: `skill_dir=.agents/skills/delegate-htmldoc`

以降のコマンド例は Claude Code の `.claude/skills/delegate-htmldoc` を使う。Codex で使う場合は、同じ相対構造の `.agents/skills/delegate-htmldoc` に読み替える。

## モデル価格参照

コスト分析・単価比較が必要な場合のみ、`<skill_dir>/model-token-prices.json` を読む。このデータは参照用であり、delegate の起動可否判定には使わない。

## テンプレートと component 語彙

デザインは skill 同梱の固定資産で担保する。worker に CSS やレイアウトを生成させない。

- `<skill_dir>/references/template.html`: 完成した CSS と全 component の使用例を含むテンプレート

- `<skill_dir>/references/styleguide.md`: component 語彙と執筆ルール

request の Context には両ファイルのパスを必ず記載し、worker にテンプレートをコピーして content だけを流し込ませる。main がテンプレート本文を読み込んで request に貼ることはしない（パス参照で足りる）。

### 図・画像素材

素材は親側で用意し、request にパスで渡す。worker に素材を生成・加工・取得させない。

- チャート・図解が必要なら、先に dataviz-svg（SVG 生成）や delegate-imagegen（ラスタ画像生成）で素材を作り、そのファイルパスを Context に列挙する

- SVG は worker がファイル内容を figure component へインライン埋め込みする（単一ファイル性を保つ）

- ラスタ画像は worker が出力 HTML と同じディレクトリ配下（例: `assets/`）へコピーし、相対パスで参照する。この場合の成果物は「出力ディレクトリ一式」になる

## 委譲する前に（コストゲート）

htmldoc は文書本文の生成（出力 token）が嵩むほど効果が出る。まとまった分量の調査結果・レポート・複数セクションの資料は委譲する。一方、main が既に全 content を持っていて数行の HTML 断片を書けば済む場合や、既存 HTML の 1 箇所修正は main が直接処理する。

適性ゲート: 受けるのはテンプレートの component 語彙で表現できる**静的文書だけ**。ダッシュボードやインタラクティブな画面（フィルタ・タブ・動的更新・チャートライブラリ等の JS 前提）、レイアウト・デザインの新規設計が本体の成果物は、分量にかかわらず対象外として delegate-implement へ委譲する。

## 実行フロー（one-shot）

1. **リクエスト作成**: Objective / Scope / Context / Acceptance criteria / Verification / Constraints の Markdown を stdin で渡す。request は terse に書く: 文書化する source（ファイル・issue・調査結果）はパスや URL で参照させ、本文を貼らない。Context に `references/template.html` と `references/styleguide.md` のパス、および使用する図・画像素材のパスを記載する。Constraints に出力ファイルパスを明記する（ユーザー指定がなければ `delegate-htmldoc-output/` 配下）。

- ユーザーが会話でモデルや effort を指定した場合は、run 呼び出しにインライン env を前置する（例: `DELEGATE_HTMLDOC_MODEL=gpt-5.5@high bash .../run.sh ...`）。exit 6 の場合は、許容値列挙を含む stderr の 1 行をそのままユーザーへの説明に使う。

2. **実行**: `out="$(printf '%s' "$req_md" | bash .claude/skills/delegate-htmldoc/scripts/run.sh htmldoc DELEGATE_HTMLDOC_MODEL haiku "$PARENT_TASK_TYPE_CHAIN" "$REQUESTER_SESSION_ID")"`（top-level 起動なら `$PARENT_TASK_TYPE_CHAIN` は空でよい）。

- run は内部で prepare → dispatch → read-response を順に実行し、stdout は成功・失敗とも単一 JSON（`exit_code` / `status` / `content` / `content_truncated` / `response_file` / `observe_file` / `run_dir`）を返す。

- selector 省略時の既定は `auto`。第 6 位置引数は read-response の selector であり、prepare.sh の第 6 位置引数 session_mode とは意味が異なる。

- exit code は内部スクリプトを透過する。exit 3=前提不足 / exit 4=委譲サイクルなら中止する。

- - `run.sh` は dispatch 前に `observe_file: <path>` を stderr へ先出しする。`run.sh` が Bash timeout で background へ退避した場合・強制終了された場合は**再実行しない**（再実行は worker の二重起動になり、implement / chore では同一 worktree の同時書き換えになる）。復旧は `bash .claude/skills/delegate-htmldoc/scripts/read-json.sh .state.phase "$observe_file"` が `ended` になるまで待ち、`bash .claude/skills/delegate-htmldoc/scripts/read-json.sh .run.response_file "$observe_file"` で応答パスを取得して `bash .claude/skills/delegate-htmldoc/scripts/read-response.sh` で読む。background 退避した出力ファイルは stdout と stderr が合流するが、`read-json.sh` は JSON object を囲む行を読み飛ばすのでそのまま読める。

+ - `run.sh` は dispatch 前に `observe_file: <path>` を stderr へ先出しする。`run.sh` が Bash timeout で background へ退避しただけの場合は**再実行しない**（再実行は worker の二重起動になり、implement / chore では同一 worktree の同時書き換えになる）。復旧は `bash .claude/skills/delegate-htmldoc/scripts/read-json.sh .state.phase "$observe_file"` を見て分岐する。`ended` または `stalled` なら終端なので、どちらでも `bash .claude/skills/delegate-htmldoc/scripts/read-json.sh .run.response_file "$observe_file"` で応答パスを取得して `bash .claude/skills/delegate-htmldoc/scripts/read-response.sh` で読む（stalled でも failed response が書かれる）。`running` の間は `.heartbeat.ts` が進んでいれば待つ。`running` のまま `.heartbeat.ts` が `DELEGATE_OBSERVE_HEARTBEAT_INTERVAL`（既定 10 秒）を大きく超えて進まない場合は dispatcher ごと停止しているので応答は来ない。**この場合に限り**新しい run を出してよい。background 退避した出力ファイルは stdout と stderr が合流するが、`read-json.sh` は既知の harness 行（空行 / `observe_file: ` 行 / `[exited with ...]` 行）に囲まれた JSON object を切り出して読める。

- 非対話モードの親（`claude -p` 等）では run を必ずフォアグラウンドで実行し、委譲所要時間より長い Bash timeout（Claude Code なら `BASH_DEFAULT_TIMEOUT_MS` / `BASH_MAX_TIMEOUT_MS` または Bash tool の timeout 引数）を設定する。

3. **レスポンス消費と検証**: `status="$(printf '%s' "$out" | bash .claude/skills/delegate-htmldoc/scripts/read-json.sh .status)"` / `content="$(printf '%s' "$out" | bash .claude/skills/delegate-htmldoc/scripts/read-json.sh .content)"` を読む。`content_truncated` が `true` なら `response_file="$(printf '%s' "$out" | bash .claude/skills/delegate-htmldoc/scripts/read-json.sh .response_file)"` を取り出し、`bash .claude/skills/delegate-htmldoc/scripts/read-response.sh "$response_file" <N>` で必要 section だけ段階読みする。読了後、worker の本文を **要約し直さない（echo しない）**。`status` が `failed` なら Error section をユーザーへ伝える。`completed` でも Summary 先頭に警告行があればその旨を伝える（警告は response 本体に載るので selector に関わらず Summary とともに返る）。`Changed files` のパスが存在することを `test -f` で確認し、生成 HTML 全文は main の context に読み込まない。

4. **Artifact 共有の確認**: main（Skill 実行者）が Claude で Artifact tool が利用可能な場合のみ、生成したドキュメントを artifact にもアップロードするかを AskUserQuestion で確認する。希望された場合のみ、アップロードに必要な範囲で生成 HTML を読み込んでアップロードする。相対参照のラスタ画像を同梱する成果物は単体アップロードで画像が欠落するため、その旨を伝えて提案しない。Artifact が利用できない実行系（Codex / Devin / Cursor 等）ではこの手順を行わない。

## 高度なフロー（個別スクリプト）

dispatch 中の observe 監視、background 実行など、途中で親の判断を挟むフローでは従来の個別スクリプトを使う。

1. **準備（集約）**: 前提チェック→モデル解決→チェーン確認→リクエスト生成を `prepare.sh` 1 本に畳む。Objective / Scope / Context / Acceptance criteria / Verification / Constraints の Markdown を stdin で渡す。request は terse に書く: 文書化する source（ファイル・issue・調査結果）はパスや URL で参照させ、本文を貼らない。Context に `references/template.html` と `references/styleguide.md` のパス、および使用する図・画像素材のパスを記載する。Constraints に出力ファイルパスを明記する（ユーザー指定がなければ `delegate-htmldoc-output/` 配下）。exit 3=前提不足 / exit 4=委譲サイクルなら中止。

- ユーザーが会話でモデルや effort を指定した場合は、prepare 呼び出しにインライン env を前置する（例: `DELEGATE_HTMLDOC_MODEL=gpt-5.5@high bash .../prepare.sh ...`）。prepare が exit 6 の場合は、許容値列挙を含む stderr の 1 行をそのままユーザーへの説明に使う。

- `out="$(printf '%s' "$req_md" | bash .claude/skills/delegate-htmldoc/scripts/prepare.sh htmldoc DELEGATE_HTMLDOC_MODEL haiku "$PARENT_TASK_TYPE_CHAIN" "$REQUESTER_SESSION_ID")"`（top-level 起動なら `$PARENT_TASK_TYPE_CHAIN` は空でよい）

- `model="$(printf '%s' "$out" | bash .claude/skills/delegate-htmldoc/scripts/read-json.sh .model)"` / `request_file="$(printf '%s' "$out" | bash .claude/skills/delegate-htmldoc/scripts/read-json.sh .request_file)"` / `response_file="$(printf '%s' "$out" | bash .claude/skills/delegate-htmldoc/scripts/read-json.sh .response_file)"` / `run_dir="$(printf '%s' "$out" | bash .claude/skills/delegate-htmldoc/scripts/read-json.sh .run_dir)"` / `observe_file="$(printf '%s' "$out" | bash .claude/skills/delegate-htmldoc/scripts/read-json.sh .observe_file)"`

2. **実行**: `bash .claude/skills/delegate-htmldoc/scripts/dispatch.sh "$model" htmldoc "$request_file" "$response_file" "$run_dir" "$observe_file"`。モデル名プレフィックスによる実行系分岐（Codex / Devin / Cursor / Claude / OpenCode）は dispatch.sh が行う。stdout は response_file のパスのみ。非対話モードの親（`claude -p` 等）では dispatch を必ずフォアグラウンドで実行し、委譲所要時間より長い Bash timeout（Claude Code なら `BASH_DEFAULT_TIMEOUT_MS` / `BASH_MAX_TIMEOUT_MS` または Bash tool の timeout 引数）を設定する。実行中の通常監視は `observe_file` から `state.phase` / `state.started_at` / `heartbeat.ts` / `heartbeat.stdout_bytes` / `heartbeat.stderr_bytes` / `heartbeat.last_stream_change_at` だけを read-json.sh で読む。`state.phase` は `prepared | running | superseded | stalled | ended`。`prepared` / `superseded` は dispatch されなかった observe（`state.started_at == null`、`usage` は未設定で read-json.sh では null 相当）なので、usage を集計する場合は分母から除外する。

3. **レスポンス読み取り**: `bash .claude/skills/delegate-htmldoc/scripts/read-response.sh "$response_file" auto`。`auto` は response が小さい（既定 10KB 未満）なら status と全 section を 1 回で丸読みし、大きい場合は status + index + Summary section を返すので、必要 section だけ `... "$response_file" <N>` で追加取得する。読了後、worker の本文を **要約し直さない（echo しない）**。`status` が `failed` なら Error section をユーザーへ伝える。`completed` でも Summary 先頭に警告行があればその旨を伝える（警告は response 本体に載るので selector に関わらず Summary とともに返る）。main のユーザー向け応答は Summary を指す 1 行に留める（main の出力＝課金トークンを増やさないため。spec.md §6）。

4. **検証**: `Changed files` のパスが存在することを `test -f` で確認する。生成 HTML 全文は main の context に読み込まない。

5. **Artifact 共有の確認**: main（Skill 実行者）が Claude で Artifact tool が利用可能な場合のみ、生成したドキュメントを artifact にもアップロードするかを AskUserQuestion で確認する。希望された場合のみ、アップロードに必要な範囲で生成 HTML を読み込んでアップロードする（このときだけ手順 4 の「全文を読み込まない」の例外とする）。対象はインライン SVG までで完結した単一 HTML のみとする。相対参照のラスタ画像を同梱する成果物（出力ディレクトリ一式）は単体アップロードで画像が欠落するため、その旨を伝えて提案しない。Artifact が利用できない実行系（Codex / Devin / Cursor 等）ではこの手順を行わない。

## 待ち時間の隠蔽（対話親向け）

- 対話親では体感待ち時間を隠蔽できる。経路は起動スクリプトで異なる。`dispatch.sh` 経由は `prepare.sh` で `response_file` を事前取得済みなので、`dispatch.sh` を background で実行し、`observe_file` の `state.phase` / `heartbeat` を確認して `ended` 後に `read-response.sh` する。`run.sh` 経由は `response_file` を事前に取得できないので、`run.sh` を background で実行した場合は `read-json.sh .run.response_file "$observe_file"` で応答パスを取るか、合流した出力 JSON をそのまま `read-json.sh` で読む。総所要時間（wall time）は変わらない体感改善であり、非対話モードの親では従来どおりフォアグラウンド実行必須。

+ 対話親では体感待ち時間を隠蔽できる。経路は起動スクリプトで異なる。`dispatch.sh` 経由は `prepare.sh` で `response_file` を事前取得済みなので、`dispatch.sh` を background で実行し、`observe_file` の `state.phase` / `heartbeat` を確認して `ended` または `stalled` になった後に `read-response.sh` する。`run.sh` 経由は `response_file` を事前に取得できないので、`run.sh` を background で実行した場合は `read-json.sh .run.response_file "$observe_file"` で応答パスを取るか、合流した出力 JSON をそのまま `read-json.sh` で読む。総所要時間（wall time）は変わらない体感改善であり、非対話モードの親では従来どおりフォアグラウンド実行必須。

## Worker report

report の見出しは共有 wrapper が固定する標準構成（`Summary / Changed files / Commands / Verification / Findings / Blockers / Error`）に従う。htmldoc では各見出しを次のように使う。

- `Summary`: 生成したドキュメントの短い説明

- `Changed files`: 作成した HTML ファイルのパス

- `Verification`: テンプレート CSS を変更していないこと、外部 URL 依存が無いこと（インライン SVG と同梱アセットの相対参照は可）、JavaScript を含まないこと（script 要素・イベントハンドラ属性・`javascript:` URL が無いこと）、目次 section が hero 直後にあり経緯・改訂履歴が末尾の history section に隔離されていることの確認

- `Findings`: 使用した component（hero / toc / section / table / conclusion / tasks / history 等）と文書構成、source の特記事項

- `Blockers`: source 不足・内容の矛盾・テンプレートで表現できない要求

## 制約

- 書き込みは指定された出力ディレクトリ配下（出力 HTML と素材コピー）と response の生成のみ。それ以外のリポジトリファイル編集・push はしない

- 図・画像は request で渡された素材のみ使用する。worker は素材を生成・加工・取得しない

- テンプレートの CSS・component 構造を変更しない。content の流し込みだけを行う（デザイン揺れを排除するため）

- 目次（toc）を hero 直後に、経緯記録（history）を footer 直前に必ず置く。時系列ログ・改訂履歴など経緯は history にのみ記載し、他 section は常に最新の仕様・事実だけを記載する

- JavaScript（script 要素・イベントハンドラ属性・`javascript:` URL）を含めない。テンプレートで表現できない要求は作らずに Blockers で報告させる

- 単発生成の種別のため session reuse（resumable / follow-up）は使わない。修正が必要なら新しい delegate run として出し直す

- task_type_chain 内種別への再委譲はしない（別種別 delegate は可）

- main は worker 出力を echo / 再要約しない。ユーザー向けは生成ファイルパスと Summary を指す 1 行に留める（出力＝課金トークンを増やさないため。spec.md §6）

- OpenCode: cwd 外への出力は保証されない（direct な edit / write と明示パスの読み取りは拒否され、bash のリダイレクトは通る）。出力先を cwd 外に指定すると成功は保証されない。request が `DELEGATE_REQUEST_INLINE_MAX` を超えると child 起動前に fail-closed する

- OpenCode の read-only 抑止は管理者設定のない環境を前提とする（管理者設定は注入した permission を override し得る）

- この種別は常に `--pure` で起動し、OpenCode の project plugin を読み込まない（plugin は任意コード実行で prompt 制約を迂回し得るため）。`DELEGATE_OPENCODE_PURE` が `1` / `true` / `yes` なら implement / chore を含む全 task type へ広げる。`DELEGATE_OPENCODE_MCP_SOURCE`（`claude` / `cursor` / `codex`）で MCP 入力元を明示し、未指定なら注入しない