xlsx-report-builder
Excel 帳票を作るスキル。基本の使い方は、依頼のフレーズから流れ(フロー)を選んで進めること。個々のサブコマンドを直接呼ぶ使い方は、オプション(サブコマンド一覧)。
- テンプレート(体裁の決まった .xlsx)がある → 既存の書式を保ったまま、データを流し込む(罫線・フォント・セル色・列幅・図・グラフはそのまま)
- テンプレートが無い → JSON スペックから新規に生成する
パスはこの SKILL.md からの相対パス。コマンド実行前にこのディレクトリに cd すること。
起動手順
スキル開始時に必ず実行する:
cd .github/skills/xlsx-report-builder
uv sync
使い方: フレーズ → フロー
依頼のフレーズから、次のどれかのフローを選ぶ。判断がつかないときは、まず「テンプレートはありますか。ある場合、どこで作られたものですか」と聞く。
| # | 依頼のフレーズ(例) | フロー(→ は順に進む。【確認】はユーザーに確認する) | 使うサブコマンド |
|---|---|---|---|
| 1 | 「このExcelにデータを入れて」「テンプレートに流し込んで」「この書式のままxlsxを作って」「他のプロジェクトの成果物を元に作って」「去年の報告書を雛形にして」 | 出所を聞く【流用なら可否を確認】→ テンプレートの事実を読む → 範囲ごとに 残す/流し込む/繰り返す/無視する/文書の値 を決める【確認】→ 定義を確定して検査 → データを用意 → 再構成 → 読み返して検証 | inspect・analyze・check・render |
| 2 | 「今月分も同じ帳票で作って」「同じ形式でもう一度」(定義が確定済み) | データを用意 → 再構成(専用スクリプトがあればそれを実行)→ 検証 | render(または専用スクリプト) |
| 3 | 「列を足して」「テンプレートが更新された」「入れる欄を変えたい」 | 既存の定義(専用スクリプトなら埋め込みの定義)を取り出す → 定義を直す【確認】→ 検査 → 書き出し直す/再構成。表の構造が変わったなら #1 に戻る | export --from-script・check・render |
| 4 | 「毎回使えるスクリプトにして」「LLM なしで回せるように」「単体で動くようにして」 | 定義を確定して検査 → 専用の単体スクリプトを書き出す → 動作を確かめる | check・export |
| 5 | 「Excelを作って」「集計表を作って」「売上レポートをExcelで」(テンプレート無し) | データと体裁を確認 → JSON スペックを組む → 生成 → 検証 | example・build |
| 6 | 「このExcelの構造を教えて」「どこが入力欄か調べて」「サンプルの値が残っていないか見て」 | テンプレートの事実を読む → 結果を要約して返す(生成はしない) | inspect(analyze) |
- #1 の「流用」(他プロジェクトの成果物)は、同じフローに流用の可否の確認を足す。値・メタデータを持ち越さない決めごと(
strict・keep・properties.scrub)は、流用でなくても既定で入る。詳細は T2 の「前の文書の値・メタデータを持ち越さない」 - #1・#3 の LLM の関与は、判断(範囲の役割・定義)とデータの用意まで。
check・render・exportと、書き出した専用スクリプトは、決まった処理だけで動く - #2・#4 は、定義が確定していることが前提。無ければ #1 から
フローの詳細: 新規生成(#5)
Step 1: データと出力イメージを確認する
- 元データの所在(ユーザー提示・CSV・DB クエリ結果・コード生成等)を確認する
- 帳票の体裁を確認する: シート構成・列・数値書式(通貨/パーセント/日付)・合計の要否・グラフの要否
- 不明点(通貨単位・小数桁・期間の粒度など)があれば確認する。勝手に数値を捏造しない
Step 2: JSON スペックを組み立てる
スペックの構造は references/spec.md を参照。雛形は次で取得できる:
uv run python scripts/xlsx_builder.py example
ポイント:
columns[].keyとrows[]のキーを一致させる- 金額は
number_format: "¥#,##0"、率は"0.0%"、日付は"yyyy-mm-dd"(ISO 文字列は自動で日付型に変換) - 合計が必要なら
total_row.sumsに対象列を指定(SUM数式が入る) - 見出し固定は
freeze: "A2"、絞り込みはauto_filter: true
組み立てたスペックは作業ファイル(例 spec.json)に保存する。
Step 3: 生成する
uv run python scripts/xlsx_builder.py build --spec spec.json
# または stdin から
cat spec.json | uv run python scripts/xlsx_builder.py build
filename に指定したパスへ .xlsx が出力される。
Step 4: 検証して引き渡す
- 生成された行数・合計・書式が意図通りか確認する(必要なら openpyxl で読み返す)
- 出力ファイルのパスをユーザーに伝える
フローの詳細: テンプレートへの流し込み(#1〜#4)
テンプレートはサンプル値が入っていることが多く、表の行数も可変になる。他のプロジェクトの成果物を流用する場合は、実データやメタデータも入っている。そこで、事実を読む → 役割を決める(確認あり)→ 定義を確定して検査する → データで再構成する、の順で行う。不変部分(書式・列幅・図・グラフ・他シート)は元のままコピーされる。詳細は references/template.md。
段の一覧
T0 出所と流用の可否を確認 ──→ T1 inspect(事実を読む)──→ T2 役割を決める ──→ ユーザー確認
│
T6 検証 ←── T5 export(繰り返すなら)←── T4 render ←── T3 check(定義の検査)←──┘
| 段 | 何をするか | 誰が | コマンド |
|---|---|---|---|
| T0 | テンプレートの出所を聞く。他プロジェクトの成果物なら、流用してよいか(社外秘・個人情報・権利)を確認する | LLM → ユーザー | — |
| T1 | テンプレートの事実(値・数式・書式の種類・結合・仮値の疑い・来歴)を読む | コマンド → LLM | inspect / analyze |
| T2 | 範囲ごとに 残す・流し込む・繰り返す・無視する・文書の値 を決め、一覧をユーザーに確認してもらう | LLM + ユーザー | — |
| T3 | 定義を確定し、整合と「テンプレートの値の残り」を検査する | コマンド | check |
| T4 | データを用意して再構成する | コマンド(LLM なし) | render |
| T5 | 同じ帳票を繰り返し作るなら、専用の単体スクリプトにする(LLM なしで毎回動く) | コマンド | export |
| T6 | 出力を読み返して確かめる | LLM / コマンド | — |
LLM が関わるのは T0〜T3 だけ。T4 以降は、定義とデータが同じなら、LLM なしで同じ結果が出る。
T0: 出所と流用の可否を確認する
テンプレートの出所をユーザーに聞く。他のプロジェクトの成果物(実データが入ったもの)を流用する場合は、次を確認してから進める。
- 流用してよいか(社外秘・個人情報・権利)。許可が不明なら進めない
- 元の値を、どれだけ残してよいか(ラベルや見出しだけか、固定の文面も残すか)
- 出力を渡す相手。元のプロジェクトを知らない相手なら、持ち越しを特に厳しく検査する(T2 の「前の文書の値・メタデータを持ち越さない」)
T1: テンプレートの事実を読む
uv run python scripts/xlsx_builder.py inspect path/to/template.xlsx # 判断用の事実(--json も可)
uv run python scripts/xlsx_builder.py analyze path/to/template.xlsx -o def.yaml # 定義の下書き(自動検出)
inspect は、次を出す。
- 行ごとの値・数式・書式の種類(同じ見た目は同じ番号)・結合・条件付き書式・入力規則
- 仮の値の疑い(
サンプル・〇〇・yyyyなど)と注記の疑い(※)、同じ書式が続く範囲 - 来歴・持ち越しの注意: 文書のプロパティ(作成者・会社名・タイトル)、プレビュー画像、コメント(作成者つき)、外部リンク、マクロ、非表示のシート・行・列、変更履歴
同じ書式が長く続く行は、テキストでは先頭と末尾だけを出す(仮の値・注記の疑いがある行は省略しない。--all ですべて、--json は常にすべて)。
analyze は、そこから表を機械的に拾った下書き。下書きは確定ではない。判断は、inspect の事実を読んだこちら(LLM)が行う。
T2: 範囲ごとに、役割を決める
テンプレートの各範囲に、次の 5 つのどれかを割り当てる。機械的な検出に任せず、値の意味・書式・並びから決める。
| 役割 | 意味 | 定義での書き方 | 向く範囲 |
|---|---|---|---|
| 残す(keep) | テンプレートのまま出す | keep に明示する(analyze が見出し・ラベルを入れる) |
毎回同じタイトル・ラベル・見出し・固定の注記・ロゴ。値は入れない |
| 流し込む(fill) | データの値で置き換える(データが null なら空欄) |
cells(固定セル)、columns.<列>.key |
宛名・日付・明細の値、文書番号・版・作成者・環境情報などラベルに対する値、空欄の記入枠 |
| 繰り返す(repeat) | サンプル行を、データの件数だけ複製する | tables(pattern・block_rows)、数式は formula: true |
明細の行、1 件が複数行のカード |
| 文書の値(doc) | データ(表の行・記入欄)ではないが、文書ごとに変わる値。文の一部だけでも差し替える | cells の {text: "{文書.年度}年度 第{文書.四半期}四半期 売上報告書"}、ラベルの右の欄は 文書.作成日、header_footer、properties |
表紙のタイトル、宛名の「○○ 御中」、明細の見出しの「(2025年9月)」、対象期間、フッターの表題、作成日・作成者・版・文書番号 |
| 無視する(ignore) | 出力に残さない | clear(値だけ空にして書式は残す)、drop_rows(行ごと取り除く) |
記入例・仮の値・ダミー行・使わない注意書き |
判断の目安:
- タイトル・宛名・期間は、文字の中の可変の部分を見る。「2025年度 第2四半期 売上報告書」の年度・四半期、「株式会社○○ 御中」の宛名、「売上明細(2025年9月)」の年月は、次の文書では変わる。文全体を残す(keep)のでも、文全体をデータにするのでもなく、変わる部分だけを文書の値にする。
analyzeは年度・四半期・年月・日付・期間・版・宛名を見つけて下書きに入れ、!で挙げる。毎回同じ文字(「社外秘」・会社のロゴ文字)や、変わらない年(「創業 1990年」)は keep に戻す - 文書の値は、データの
文書:にまとめる。表紙と明細の作成日、タイトルとフッターの年度のように、いくつかの場所に出る同じ値は、1 つのキー(文書.作成日)にする。ラベルの右の作成日・作成者・版・文書番号・宛先なども文書.の下に入る - ラベルに対する値は、残さない。文書番号・版・作成日・作成者・環境情報(OS・DB・バージョン)・変更履歴は、前の案件の実データ。テンプレートとして使う以上、データから流し込むか空にする。「固定の欄だから keep」にしない
- データに書くのは、文書ごとに変わる値だけ。次はデータに書かない。
analyzeは機械的に分かるものを下書きに入れ、needs_confirmに挙げる。意味で決まるもの(会社名・発行元のように毎回同じ値、人が手で書く欄)は、下書きを読んで直す- 毎回同じ値(どの行も
式・円の列、発行元の会社名)→ 残す(列はkeep: true、固定セルはkeep) - 人が書き込む欄(押印・署名・承認・確認者・手書きの欄)→ データに入れない。前の値があれば
clear(列はclear: true) - 体裁の余白(見出しも値も無い列・空行)→ 定義にもデータにも入れない。空かどうかは、既定値を除いてから判定する。既定値は、連番・
×や-の印・どの行も同じ値・数式。見出しが無く×だけの列は余白(印は書式として残す)。連番と×だけの行は、記入例ではなく空の行
- 毎回同じ値(どの行も
- 表の見た目に頼る値は、データで意味の分かる形にする。○× の列(択一・複数選択)、1 列の ○、年・月・日に分かれた日付、コードは、データでは
判定: 合格・対象OS: [Windows, Linux]・要再試: true・実施日: 2026-10-08・優先度: 高と書き、変換は定義(when/map/part)に任せる。analyzeが見つけたものはneeds_confirmに挙がる。詳細は references/template.md の「表の見た目に頼る値」 - 空欄の記入枠も、キーを残す。今は空でも、次の文書では入れる欄。
analyzeは、ラベルの右隣のセルを、空欄でもcellsに入れる。消さない - 同じ書式が並び、値が連番や例に見える行 → 繰り返す。縞模様なら
patternに周期の行を並べる。1 件が 2 行以上(明細 + 備考など)ならblock_rowsを使う - 仮の値の疑い(
サンプル株式会社・2020-01-01)のうち、データで置き換える欄 → 流し込む。置き換えない欄 → 無視する(clear) - 記入例の行や、利用者向けの書き方の注意(
※ 記入例)→ 無視する。印刷物として残すべき注記(※ 振込手数料はご負担ください)→ 残す - 合計・小計・税などの行 → 残す。
SUMの範囲は、表の行数に合わせて自動で伸びる - 集計の表(支店別・商品別など)→ 明細から数式で出すか、集計した値をデータで流し込むかを利用者に確かめる。数式なら列は
formula: true。行を横に足す=SUM(B2:E2)の列は、合計の行ではなく表の列 analyzeの下書きに!で挙がる「前の文書の作成者・会社名を含む」文字(東邦物流様 … 設計書のタイトルなど)は、keepのまま残さない。流し込むか、利用者に確かめる- 定数の列(
円など)→keep: true。サンプルの値を持ち越したくない列 →clear: true - 迷う範囲は、決めずにユーザーに聞く。聞くときは、範囲・候補の役割・理由を 1 行ずつ示す
前の文書の値・メタデータを持ち越さない
テンプレートは、たいてい前の案件の成果物から作る。元の実データを出力に持ち越さないため、analyze の下書きは、はじめから次の形になっている。外すのは、ユーザーが望んだときだけ。
strict: trueと、見出し・ラベルだけのkeep。ラベルの右隣のセル(空欄の記入枠を含む)と、ラベルの無い数値・日付はcellsに入る。下書きを読み、値のあるセルを 1 つずつ確かめる。仮の値の疑いの印が付かない実データ(実在の顧客名・金額・日付・バージョン)も、ラベルや見出しでなければ「流し込む」か「無視する」にする。決め忘れた値が残るセルがあると、checkとrenderが、シートごとに範囲(A1, A3:A5)にまとめて挙げて止まる。挙がったものをそのまま全部keepに貼らないproperties.scrub: true。作成者・最終更新者・会社名・タイトルなどを空にし、プレビュー画像・カスタムプロパティ・コメント(メモ)を取り除く。共有文字列に残った元の値と、グラフに残った古い値のキャッシュも取り除く。残したい項目、与えたい値(title: "請求書")は、同じpropertiesに書く- **外部リンク・非表示のシート/行・変更履歴(リビジョン)**は、
inspectが挙げるが、自動では消さない。ユーザーに見せて扱いを決める(不要なら、先にテンプレートの側で消してもらう) - マクロ(VBA)つきなら、出力の拡張子は
.xlsm
決めたら、判断の一覧(範囲 | 役割 | 理由)をユーザーに見せて確認してもらう。確認前に定義を確定しない。確定した定義には、判断の記録として decisions(範囲・役割・理由の一覧)を残してよい(render は読まない)。
T3: 定義を検査する
uv run python scripts/xlsx_builder.py check --def def.yaml # テンプレートは定義の template(定義ファイルからの相対パス)から読む。--template で上書き
テンプレートと定義の整合(シート名・行・pattern・列)を確かめ、雛形データで試しに再構成する。strict: true なら、決め忘れた値の残りもここで見つかる。来歴の警告も出る。問題があれば、定義を直して、もう一度検査する。
T4: データを用意して再構成する
データは、表ごとのキーにオブジェクトの配列を持つ JSON か YAML にする(assets/template.data.example.json)。数値を捏造しない。
uv run python scripts/xlsx_builder.py render --def def.yaml --data data.yaml -o out.xlsx
データが大きくなるなら、ファイルを分けてよい。--data に複数のファイルかフォルダを渡すと、1 つにまとめて流し込む。表の行はファイルの順(フォルダなら名前順)につなぐ。同じ欄に違う値があるとき、表の同じ行が 2 つのファイルにあるとき、ほかのまとまりのデータも持つファイル(前のデータ一式を写したもの)から表の行が来たときは、ファイルの名前を挙げて止まる。書き出した専用スクリプトも同じ。データを分けて担当に渡すときは、前のデータ一式を写さず、自分のまとまりのファイルだけを直すよう伝える。分け方は、行数ではなくタブのまとまりごと。定義の sheets[].group が同じタブを 1 ファイルにし、無ければタブごとに分ける。analyze は、名前が同じ言葉で始まるタブ(受注_一覧・受注_明細)に group を入れる。意味で決まるまとまり(表紙と改訂履歴など)は、下書きを読んで group を直す。extract --split DIR は、取り出したデータをこのまとまりごとのファイルに分けて書く。
uv run python scripts/xlsx_builder.py render --def def.yaml --data head.yaml items-1.yaml items-2.yaml -o out.xlsx
uv run render_invoice.py --data data/ -o out.xlsx # フォルダの中のデータファイルを名前順に
記入済みの文書(前の案件の成果物・以前に render した文書)からデータを起こすなら、extract で取り出してから直す。○・年月日の列は 判定: 合格・実施日: 2026-10-08 の形に戻る。既定値だけの空の行は書かない。どの行も空の欄も、記入枠としてキーを残す。
uv run python scripts/xlsx_builder.py extract filled.xlsx --def def.yaml -o data.yaml
テンプレートは定義の template(定義ファイルのある場所からの相対パス。analyze がそう書く)から読む。別のパスなら --template で上書きする。列の key がデータのどの行にも無いと、その列は空欄になる。データに使われていないキーがある(綴りの違いの疑い)か、どの key も当たらないときは警告が出る。テンプレートに列を足した後に前のデータを使い回すと、足した列は黙って空欄になるので、--example-data や skeleton で足りないキーを確かめる。数値の欄に数値として読めない文字(数量「たくさん」)を入れると、警告が出る(合計などが #VALUE! になる)。定義ファイルとデータは、JSON でも YAML(.yaml / .yml)でもよい。analyze -o def.yaml のように、出力の拡張子で形式を選べる。
T5: この文書専用の単体スクリプトにする(任意)
同じ帳票を繰り返し作るなら、確定した定義を埋め込んだ、スキル不要の 1 ファイルを書き出せる。テンプレートの .xlsx は、既定では別ファイルのまま置く(スクリプトからの相対パスで読む)。書き出し時に check と同じ検査をする。
uv run python scripts/xlsx_builder.py export --def def.yaml -o render_invoice.py
uv run render_invoice.py --data data.yaml -o out.xlsx # PEP 723 で依存(lxml・openpyxl・pyyaml)を自動で入れる
- 書き出した
.pyは、スキルのディレクトリが無くても動く。テンプレートを同じ場所に置いておく - 配布を 1 ファイルにしたいときだけ
--embedを付ける(テンプレートを base64 で埋め込む) --example-dataでデータの雛形、--extract-defで埋め込みの定義を取り出せる。--helpにデータの形が出る
書き出したスクリプトの改修
スクリプトを手で書き換えない。定義を直して、書き出し直す。
python render_invoice.py --extract-def def.yaml # 1. 埋め込みの定義を取り出す
# def.yaml を直す(列の追加・キーの変更・pattern の見直しなど)
uv run python scripts/xlsx_builder.py export --from-script render_invoice.py --def def.yaml -o render_invoice.py # 2. 書き出し直す
- 定義を直さずに
--from-scriptだけを付けると、定義とテンプレートを引き継いで、最新のエンジンで書き出し直す(エンジンの更新) - テンプレートが変わったときは
--template new.xlsxを付ける。構造が変わったなら、T1 からやり直して定義を確定する(列を足した・並べ替えたテンプレートは、見出しが定義と合わないので、書き出しの検査が列を挙げて止まる)
T6: 検証する
- 出力を openpyxl で読み返し、行数・値・数式(
=SUM(E8:E12)など)が意図どおりか確認する - 書式(罫線・色・フォント)がテンプレートと同じか、サンプルの値が残っていないかを確認する
- 流用した場合は、出力の文書のプロパティ・共有文字列・コメントに、元のプロジェクトの情報が残っていないかを確認する
- 数式の結果は、Excel で開いたときに再計算される。値を確かめたいときは LibreOffice で CSV に変換する
テストの実行: uv run python -m unittest discover -s tests -v
サブコマンド一覧(個別に呼ぶ場合)
フローを使わず、個々のサブコマンドを直接呼ぶこともできる。すべて uv run python scripts/xlsx_builder.py <サブコマンド>。
| サブコマンド | 役割 | 主な引数 |
|---|---|---|
inspect <template.xlsx> |
テンプレートの事実(値・数式・書式の種類・結合・仮値の疑い・来歴)を出す | --json |
analyze <template.xlsx> |
表の自動検出による、定義の下書きを書く(確定ではない) | -o def.yaml(拡張子で JSON / YAML を選ぶ) |
check --def <def> |
定義の整合と、テンプレートの値の残り(strict)を検査する |
--template |
render --def <def> --data <data> -o <out.xlsx> |
テンプレート + 定義 + データから再構成する | --template、--data -(標準入力)、--data a.yaml b.yaml / --data DIR(分けたデータをまとめる) |
extract <filled.xlsx> --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 のサンプルスペックを出す |
— |
専用スクリプト(export の出力)の引数: --data(複数のファイル・フォルダも可)、-o、--template、--example-data、--extract-def、--extract-template。
できること / できないこと
| 対象 | 可否 |
|---|---|
| 複数シート・見出し装飾・数値書式 | ✅ |
| 合計行(SUM)・フリーズペイン・オートフィルタ | ✅ |
| 条件付き書式(カラースケール / データバー / しきい値) | ✅ |
| グラフ(棒 / 折れ線 / 円、単・複数系列) | ✅ |
| ピボットテーブル・マクロ(VBA)・複雑な相互参照数式 | ❌ 非対応(必要なら別途相談) |
| 既存 .xlsx テンプレートへの流し込み(書式・不変部分を保持) | ✅ analyze / render |
| 既存 .xlsx の任意の編集 | ❌ 流し込み以外は対象外 |
ガードレール
| 制限 | 内容 |
|---|---|
| データの事実性 | スペックに無い数値を生成しない。集計は呼び出し側で確定させる |
| 機密 | 元データのシークレット・個人情報の取り扱いに注意し、不要な列を含めない |
| スコープ | 帳票生成に集中する。データ取得・分析そのものは別スキル/別タスク |