docx-document-builder
Word の文書を作るスキル。xlsx-report-builder・pptx-presentation-builder の docx 版で、考え方とサブコマンドは同じ。基本の使い方は、依頼のフレーズから流れ(フロー)を選んで進めること。個々のサブコマンドを直接呼ぶ使い方は、オプション(サブコマンド一覧)。
- テンプレート(体裁の決まった .docx、前の案件の文書)がある → 文書のスタイルをそのまま使い、内容を流し込む
- テンプレートが無い → JSON スペックから新規に生成する
docx ならではの約束が 3 つある。
- 文書のスタイルを保つ。文字を差し替えるときは、段落(スタイル・字下げ・行間・番号)と文字(フォント・大きさ・色・太字)の書式を、テンプレートの見本の段落から取る。章(見出しのスタイルと番号)はそのまま続き、繰り返した節の中の番号つきリストは節ごとに 1 から振り直す。データの改行(
\n)は段落の中の改行、空行(\n\n)は段落の区切りになる。件名:のようなラベルは、太字などの書式ごと残して後ろだけを差し替える - サンプルと同じ粒度に収める。文字の大きさ・字下げ・余白は変えず、データの量の方を合わせる。サンプルの文字数・段落の数・項目数(
max_chars・max_items)を超えると、renderはどの欄を何字・何段落減らせばよいかを挙げて止まる。量を調整する(要約する・まとめる)のは LLM の仕事 - サンプルと同じ書きぶりにする。段落ごとの役割、章(部分)ごとの趣旨と論理構成、文書全体の章の流れを定義に書き、データはそれに沿って書く。文末(です・ます/だ・である/体言止め)・1 文の長さ・数字と句読点の表記は
analyzeがサンプルから測り、違う文があるとrenderが挙げて止まる
パスはこの SKILL.md からの相対パス。コマンド実行前にこのディレクトリに cd すること。
起動手順
スキル開始時に必ず実行する:
cd .github/skills/docx-document-builder
uv sync
使い方: フレーズ → フロー
依頼のフレーズから、次のどれかのフローを選ぶ。判断がつかないときは、まず「テンプレート(元にする文書)はありますか。ある場合、どこで作られたものですか」と聞く。
| # | 依頼のフレーズ(例) | フロー(→ は順に進む。【確認】はユーザーに確認する) | 使うサブコマンド |
|---|---|---|---|
| 1 | 「このWordに流し込んで」「この文書と同じ形式で作って」「前回の報告書を雛形にして」「他のプロジェクトの文書を元に作って」 | 出所を聞く【流用なら可否を確認】→ テンプレートの事実を読む → 段落・表ごとに 残す/流し込む/繰り返す/無視する を決める【確認】→ 定義を確定して検査 → データを用意(粒度に合わせて量を調整)→ 再構成 → 見て確かめる | inspect・analyze・check・render |
| 2 | 「今月分も同じ文書で作って」「同じ形式でもう一度」(定義が確定済み) | データを用意 → 再構成(専用スクリプトがあればそれを実行)→ 確かめる | render(または専用スクリプト) |
| 3 | 「この文書の内容を差し替えたい」「前の報告書を直して出し直したい」 | 記入済みの文書からデータを取り出す → データを直す → 再構成 | extract・render |
| 4 | 「章を足して」「テンプレートが更新された」「入れる欄を変えたい」 | 既存の定義を取り出す → 定義を直す【確認】→ 検査 → 書き出し直す/再構成。文書の構成が変わったなら #1 に戻る | export --from-script・check・render |
| 5 | 「毎回使えるスクリプトにして」「LLM なしで回せるように」 | 定義を確定して検査 → 専用の単体スクリプトを書き出す → 動作を確かめる | check・export |
| 6 | 「報告書を作って」でテンプレートが無く、見出し・本文・箇条書き・表で足りる | データと構成を確認 → JSON スペックを組む → 生成 → 確かめる | example・build |
| 7 | 「このdocxの構造を教えて」「どこが入力欄か調べて」「サンプルの値が残っていないか見て」 | テンプレートの事実を読む → 結果を要約して返す(生成はしない) | inspect(analyze) |
- #1 の「流用」(他プロジェクトの文書)は、同じフローに流用の可否の確認を足す。値・メタデータを持ち越さない決めごと(
strict・keep・properties.scrub)は、流用でなくても既定で入る - LLM が関わるのは、判断(段落の役割・定義)と、データの用意(量の調整を含む)まで。
check・render・extract・exportと、書き出した専用スクリプトは、決まった処理だけで動く - #2・#5 は、定義が確定していることが前提。無ければ #1 から
フローの詳細: テンプレートへの流し込み(#1〜#5)
詳細は references/template.md。
段の一覧
| 段 | 何をするか | 誰が | コマンド |
|---|---|---|---|
| T0 | テンプレートの出所を聞く。他プロジェクトの文書なら、流用してよいか(社外秘・個人情報・権利)を確認する | LLM → ユーザー | — |
| T1 | テンプレートの事実(段落・見出し・リスト・表・書式・収まる量・章の構成・同じ形の節・仮値の疑い・来歴)を読む | コマンド → LLM | inspect / analyze |
| T2 | 段落・表ごとに 残す・流し込む・繰り返す・無視する を決め、段落・章・全体の趣旨と論理構成を書き、一覧をユーザーに確認してもらう | LLM + ユーザー | — |
| T3 | 定義を確定し、整合と「テンプレートの値の残り」を検査する | コマンド | check |
| T4 | データを用意する。趣旨・論理構成・文体に沿って書き、粒度(max_chars・max_items)に合わせて要約する・まとめる |
LLM | — |
| T5 | 再構成する。収まらない欄があれば、挙がった欄だけ T4 に戻って直す | コマンド(LLM なし) | render |
| T6 | 同じ文書を繰り返し作るなら、専用の単体スクリプトにする | コマンド | export |
| T7 | 出力を見て確かめる(画像にして見る) | LLM | — |
T1: テンプレートの事実を読む
uv run python scripts/docx_builder.py inspect path/to/template.docx # 判断用の事実(--json も可)
uv run python scripts/docx_builder.py analyze path/to/template.docx -o def.yaml # 定義の下書き(自動検出)
inspect は、本文の段落・表を順に番号(ブロック #1・#2 …)を振って出す。定義はこの番号で段落・表を指す。
- 段落の種類(段落・見出しの段・リストの記号か番号と段・表・コンテンツコントロール)、スタイル、フォントと文字の大きさ、配置
- 収まる量(1 行の字数、文字の大きさ)と、いま使っている行数。段落の中の改行・改ページ・セクションの区切り・図・フィールド
- 用紙と余白、本文の幅、行の格子、ページ数の見積もり
- 章の構成(見出しと、その章が持つブロックの範囲)と、同じ形の節の並び(繰り返しの候補と、その手がかり)
- 仮の値の疑い(
サンプル・〇〇・yyyyなど)と注記の疑い(※) - 来歴・持ち越しの注意: 文書のプロパティ(作成者・会社名・タイトル)、プレビュー画像、コメント、変更履歴、ヘッダー・フッター、脚注、外部へのリンク、埋め込みのオブジェクト、元にした Word テンプレートの場所、隠し文字、目次のフィールド、マクロ
analyze の下書きは確定ではない。判断は inspect の事実を読んだこちら(LLM)が行う。
T2: 段落・表ごとに、役割を決める
定義は、文書を見出しごとの**部分(parts)**に分け、部分ごとに次の役割を書く。
| 役割 | 意味 | 定義での書き方 | 向く段落・表 |
|---|---|---|---|
| 残す(keep) | テンプレートのまま出す | keep |
章の見出し、目的: だけの段落、固定の注記 |
| 流し込む(fill) | データの文字で置き換える(null なら空) |
texts・lists・表の cells |
表題・日付・宛名・本文の段落・箇条書き・件名:〇〇 の後ろ |
| 繰り返す(repeat) | 見本を、データの件数だけ複製する | 部分の repeat、表の key・columns |
1 件 1 節(見出し + 本文)、表の行 |
| 文書の値(doc) | データではないが、文書ごとに変わる値。文の一部だけでも差し替える | texts の {text: "{文書.年度}年度 第{文書.四半期}四半期 業務報告書"}、件名: の後ろは 文書.件名、header_footer、properties |
表題の年度・四半期、日付、宛名の「○○ 御中」、見出しの「(2025年9月)」、フッターの表題、作成日・作成者・版・件名 |
| 無視する(ignore) | 出力に残さない | clear(文字だけ空に)、部分の drop(部分ごと取り除く) |
記入例・使い方の説明・見本の 2 つめ以降の節 |
判断の目安:
- 表題・日付・宛名・フッターは、文字の中の可変の部分を見る。「2025年度 第1四半期 業務報告書」の年度・四半期は次の文書では変わるが、「業務報告書」は変わらない。文全体をデータにせず、変わる部分だけを文書の値(データの
文書:)にする。analyzeは表紙・見出し・ヘッダー/フッターの中から年度・四半期・年月・日付・期間・版・宛名を見つけて下書きし、確認の項目に挙げる。毎回同じ文字はkeepに戻す。作成日・作成者・版・件名などのラベルの後ろの値も文書.のキーになり、文書全体で 1 つの値が入る(xlsx-report-builder と同じ) - 同じ形の節が続く(施策ごとに 1 節など)→ 1 つめを
repeatの見本にし、残りはdrop。analyzeは、見出しに共通の言葉があるか、どの節にも同じラベル・表の見出しがあるときだけそう下書きする。形だけが同じ節(「概要」と「背景」)は繰り返しにせず、確認の項目に挙げる - 見出しの番号は、スタイルの自動の番号ならそのまま続く。
2.1 施策 Aのように手で打った番号はformat: "2.{n} {}"で振り直す({n}が 1 始まりの番号、{}が値) - ラベルと値が 1 つの段落にある(
件名:〇〇)→after: "件名:"で、ラベルの書式(太字など)ごと残して後ろだけを差し替える - 本文の段落の続きは 1 つの欄(
#6-#8)にする。データは空行で段落を分けた文字。段落の数はmax_items - **表の最後の行(合計・小計)**は残し、値はデータに書く(
合計.件数のような欄)。合計は計算しないので、足した値を書く - ラベルに対する値は、残さない。日付・宛名・作成者・版・顧客名は前の案件の実データ。流し込むか空にする
- データに書くのは、文書ごとに変わる値だけ。どの行も同じ文字の列は
keep: true、押印・承認・確認者の列はclear: true - 様式の名前・欄の名前は残す。
備品購入申請書のような表題と、入力欄・表のすぐ前の備考はkeep。印の欄だけの表もそのまま残す - 表の見た目に頼る値は、データでは意味の分かる形にする。○× の列は
完了: trueと書き、変換は定義(map・when・part)に任せる - 迷う段落は、決めずにユーザーに聞く。聞くときは、ブロックの番号・文字・候補の役割・理由を 1 行ずつ示す
文章の型を書く(趣旨・論理構成・文体)
書式だけでなく、サンプルの書きぶりも写す。inspect の文字を読み、段落・章・文書全体の 3 つの単位で定義に書く(書き方は references/template.md)。
| 単位 | 書くもの | 定義 |
|---|---|---|
| 段落(欄) | 文末と 1 文の長さ(analyze が測る)、段落ごとの役割(1 段落め: 結論、2 段落め: 理由、など) |
欄の ending・sentence_chars・logic |
| 章(部分) | 趣旨(その章で言いたいこと)、論理構成(結論から書くか、背景から積み上げるか、根拠に何を使うか) | 部分の intent・logic |
| 文書全体 | 章の流れ(概要 → 施策 → 進捗、など)、数字と句読点の表記(表記は analyze が測る) |
style.logic・style.digits・style.punctuation |
- 段落の役割は、接続の言葉(まず・一方・したがって)や、数字・例の使い方も見て書く
analyzeが測った文末は、サンプルが仮の文や書き方の説明なら外す- 判断の一覧と一緒に、趣旨・論理構成もユーザーに見せる
前の文書の値・メタデータを持ち越さない
analyze の下書きは、はじめから次の形になっている。外すのは、ユーザーが望んだときだけ。
strict: true。文字を持つ段落・表が、texts・lists・keep・clear・表のどれにも入らないまま残ると、checkとrenderがブロックの番号と文字を挙げて止まる。挙がったものを、そのまま全部keepに貼らないproperties.scrub: true。作成者・最終更新者・会社名・タイトルなどを空にし、プレビュー画像・カスタムプロパティ・コメントを取り除き、変更履歴を承諾して作成者の名前を消し、元にした Word テンプレートの場所を外す。与えたい値(title: "第3四半期 報告")は同じpropertiesに書く- ヘッダー・フッター・脚注・グラフの値・埋め込みのオブジェクト・外部へのリンク・隠し文字は、
inspectが挙げるが、自動では書き換えない(ヘッダー・フッターの年度・表題などの可変の部分だけは、analyzeがheader_footerに下書きする)。ユーザーに見せて扱いを決める(テンプレートの側で直す)
決めたら、判断の一覧(ブロック | 文字 | 役割 | 理由)をユーザーに見せて確認してもらう。確認前に定義を確定しない。
T3: 定義を検査する
uv run python scripts/docx_builder.py check --def def.yaml # テンプレートは定義の template(定義ファイルからの相対パス)から読む。--template で上書き
整合(ブロックの範囲・段落か表か・after のラベル・表の見出し)を確かめ、雛形データで試しに再構成する。最後に、データの書き方と収まる量(施策[].points[]: 最大 5 項目・1 項目 12 字まで)の一覧が出る。T4 はこの一覧を見て書く。
T4〜T5: データを用意して再構成する
データは、部分のキー(表紙・概要 …)ごとの欄を持つ JSON か YAML(assets/template.data.example.yaml)。繰り返す部分は配列。数値・事実を捏造しない。
check の一覧に出る趣旨・論理構成・文体に沿って書く。段落は役割の順に、章は文書全体の流れ(style.logic)の順に並べる。章の趣旨に合わない内容は、別の章に押し込まずにユーザーに聞く。
uv run python scripts/docx_builder.py render --def def.yaml --data data.yaml -o out.docx
収まらない欄があると、次のように挙げて止まる(終了コード 1)。フォントを小さくしたり、余白を狭めたりしない。挙がった欄の文章を要約する・段落や項目をまとめる、のどちらかでデータを直し、もう一度 render する。文体の違いは、その文をサンプルの文末・表記に書き直す。
収まらない値があります。テンプレートの粒度に合わせて、データの量を減らすか言い換えてください:
表紙.title(#1): 30 字。サンプルの粒度は 18 字まで(12 字減らす)
概要.body(#6-#7): 4 段落。サンプルの粒度は 3 段落まで(1 段落減らすか、まとめる)
施策[0].points(#12-#13): 6 項目。サンプルの粒度は 5 項目まで(1 項目減らすか、まとめる)
サンプルの文体と違う文があります。定義の文体(ending・sentence_chars・style)に合わせて書き直してください:
概要.body(#6-#7) 1 段落め: 「夜間バッチの遅延が 2 回ありました。」はです・ます調。サンプルはだ・である調
概要.body(#6-#7) 2 段落め: 1 文が 61 字(「来月から監視の間隔を…」)。サンプルの 1 文は 26 字まで(文を分けるか短くする)
- 1 ページに収める様式なら、定義に
max_pages: 1を書く。ページ数の見積もりが超えると止まる - 粒度の上限そのもの(
max_chars・max_items)を変えるのは、ユーザーが望んだときだけ --allow-overflowは、止めずに警告にする(下書きを見せるときだけ使う)
データが大きくなるなら、ファイルを分けてよい。--data に複数のファイルかフォルダを渡すと、1 つにまとめて流し込む。繰り返す部分・リスト・表の行はファイルの順(フォルダなら名前順)につなぐ。同じ欄に違う値があると止まる。書き出した専用スクリプトも同じ。分け方は章のまとまりごと。定義の parts[].group が同じ部分を 1 ファイルにし、無ければ部分ごとに分ける。analyze は、見出し 1 の章の名前を group に入れる。extract --split DIR は、取り出したデータをこのまとまりごとのファイルに分けて書く。
uv run python scripts/docx_builder.py render --def def.yaml --data 01-表紙.yaml 02-概要.yaml -o out.docx
uv run render_report.py --data data/ -o out.docx # フォルダの中のデータファイルを名前順に
記入済みの文書(前の案件の文書・以前に render した文書)からデータを起こすなら、extract で取り出してから直す。
uv run python scripts/docx_builder.py extract filled.docx --def def.yaml -o data.yaml
T6: この文書専用の単体スクリプトにする(任意)
uv run python scripts/docx_builder.py export --def def.yaml -o render_report.py
uv run render_report.py --data data.yaml -o out.docx # PEP 723 で依存(lxml・python-docx・pyyaml)を自動で入れる
- テンプレートは既定では別ファイルのまま、スクリプトからの相対パスで読む。1 ファイルにしたいときだけ
--embed --dataには、分けたデータの複数のファイルかフォルダも渡せる--example-dataでデータの雛形と収まる量、--extract-defで埋め込みの定義を取り出せる- 改修は、スクリプトを手で書き換えず、定義を直して
export --from-script render_report.py --def def.yaml -o render_report.pyで書き出し直す。--defを付けなければエンジンだけを最新にする
T7: 確かめる
- 出力を画像にして、ページごとに見る(
soffice --headless --convert-to pdf out.docx→pdftoppm -png -r 50 out.pdf page)。フォント・見出しの番号・リストの番号・段落の間隔・改行・表の書式がテンプレートと同じか確かめる - サンプルの値(
サンプル・前の顧客名・前の日付)が残っていないか確かめる。ヘッダー・フッターも見る - 流用した場合は、文書のプロパティ・コメント・変更履歴に、元のプロジェクトの情報が残っていないか確かめる
- 目次があれば、Word で開いてフィールドを更新する(
renderは、開いたときに更新を求める設定にする)
テストの実行: uv run python -m unittest discover -s tests -v
具体的な文書で依頼から出来上がりまでを通すシナリオは tests/scenarios/ にある。エージェントに「このシナリオを再生して」と頼んで回す。
フローの詳細: 新規生成(#6)
- 内容と構成を確認する。数値・事実は捏造しない
- JSON スペックを組む。構造は references/spec.md。雛形は
uv run python scripts/docx_builder.py example - 生成する:
uv run python scripts/docx_builder.py build --spec spec.json - T7 と同じく、画像にして確かめる
ブロックの種類は title・heading(見出し 1〜3。章の番号はスタイルで振る)・paragraph(\n は改行、空行は段落の区切り)・bullets・numbered・table・page_break。作った文書は、そのままテンプレートとして #1 に使える。
サブコマンド一覧(個別に呼ぶ場合)
すべて uv run python scripts/docx_builder.py <サブコマンド>。
| サブコマンド | 役割 | 主な引数 |
|---|---|---|
inspect <template.docx> |
テンプレートの事実(段落・見出し・表・書式・収まる量・章の構成・仮値の疑い・来歴)を出す | --json |
analyze <template.docx> |
定義の下書きを書く(確定ではない) | -o def.yaml(拡張子で JSON / YAML を選ぶ) |
check --def <def> |
定義の整合と、テンプレートの値の残り(strict)を検査し、収まる量の一覧を出す |
--template |
render --def <def> --data <data> -o <out.docx> |
テンプレート + 定義 + データから再構成する | --template、--data -(標準入力)、--data a.yaml b.yaml / --data DIR(分けたデータをまとめる)、--allow-overflow |
extract <filled.docx> --def <def> |
記入済みの文書から、定義に沿ってデータを取り出す(render の逆) |
-o data.yaml(省略時は標準出力に JSON)、--template、--split DIR(章のまとまりごとのファイルに分ける) |
export --def <def> -o <render.py> |
定義を埋め込んだ、単体で動く専用スクリプトを書き出す | --embed、--template、--from-script <旧.py> |
build --spec <spec.json> |
テンプレート無しで、JSON スペックから新規生成する | stdin も可 |
example |
build のサンプルスペックを出す |
— |
できること / できないこと
| 対象 | 可否 |
|---|---|
| 段落の文字の差し替え(段落・文字の書式、段落の中の改行を保つ)、ラベルの後ろだけの差し替え | ✅ |
| 本文の段落の数・リストの項目数と段の増減(同じ位置・同じ段の見本の書式で) | ✅ |
| 節(見出し + 本文)の繰り返し・見本の節の削除。見出しの番号は続け、番号つきリストは節ごとに振り直す | ✅ |
| 表の行の増減(見出し・合計の行は残す)、○× などの変換、2 列の記入欄 | ✅ |
| コンテンツコントロール(ブロックのもの)への記入 | ✅ |
| 収まる量の検査(サンプルの粒度・高さの決まったセル・ページ数の見積もり) | ✅ |
| 文体の検査(文末・1 文の長さ・数字と句読点の表記)と、段落・章・全体の趣旨と論理構成の書き添え | ✅ 趣旨・論理構成は LLM が書き、データを書くときに使う |
| 前の文書のコメント・変更履歴・プロパティの除去 | ✅ |
| ヘッダー・フッターの段落の差し替え(年度・表題・宛名などの文書の値) | ✅ header_footer |
| 脚注・テキストボックスの中の文字の差し替え | ❌ そのまま残す(inspect が挙げる) |
| 1 つの段落の中の、一部だけの書式(途中の太字) | ❌ 差し替えた値は 1 つの書式になる(ラベルは after で残せる) |
| 画像・グラフの差し替え | ❌ そのまま残す |
ガードレール
| 制限 | 内容 |
|---|---|
| データの事実性 | 依頼に無い数値・事実を作らない。量を減らすときは要約・統合し、意味を変えない |
| スタイル | フォント・文字の大きさ・字下げ・行間・余白をデータに合わせて変えない。合わせるのはデータの量 |
| 章 | 章の見出しのスタイルと番号はテンプレートのまま。番号を文字で打ち直さない(手で打った番号は format で振る) |
| 書きぶり | サンプルの文末・表記・章の趣旨を、データに合わせて変えない。合わない内容は、ユーザーに聞く |
| 機密 | 流用元の実データ・コメント・変更履歴・プロパティを持ち越さない |