XLSX Report Builder

xlsx-report-builder

JSON スペックから Excel 帳票を生成する。値の集計・整形は JSON スペックを組み立てる側（このスキルの呼び出し） が担当し、ビルダーは見栄えと Excel 機能（書式・合計・グラフ）を付与する。

パスはこの SKILL.md からの相対パス。コマンド実行前にこのディレクトリに cd すること。

起動手順

スキル開始時に必ず実行する:

cd .github/skills/xlsx-report-builder
uv sync

ワークフロー

Step 1: データと出力イメージを確認する

1. 元データの所在（ユーザー提示・CSV・DB クエリ結果・コード生成等）を確認する
2. 帳票の体裁を確認する: シート構成・列・数値書式（通貨/パーセント/日付）・合計の要否・グラフの要否
3. 不明点（通貨単位・小数桁・期間の粒度など）があれば確認する。勝手に数値を捏造しない

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: 検証して引き渡す

1. 生成された行数・合計・書式が意図通りか確認する（必要なら openpyxl で読み返す）
2. 出力ファイルのパスをユーザーに伝える

できること / できないこと

ガードレール