Xlsx

Excel の .xlsx ブックと CSV を作り、読み、直します。

skill の情報

参考: SKILL.md 全文

Xlsx Skill

Python と openpyxl を使って Excel の .xlsx ブックを扱います。数式や グラフを含む、体裁の整った複数シートのブックを作り、既存のファイルの 中身を調べたり書き出したりし、セルや構造を直し、CSV との相互変換を します。補助スクリプトはすべて argparse のコマンドで、JSON を表示し、 入出力は UTF-8 をはっきり指定して行います。

こんなときに使います

• .xlsx の報告書を作るとき: 複数シート、数値の書式、体裁、

セルの結合、ウィンドウ枠の固定、フィルター、条件付き書式、 グラフ、入力規則のドロップダウン。

• ブックを読むとき: シートの一覧、データを JSON や CSV として

書き出すこと、数式と計算済みの値の一覧。

• 既存のファイルを直すとき: セルの設定、行の追加、行や列の

挿入と削除、シートの複製と名前の変更。

• 型の推測や UTF-8 以外の文字コードを含む、CSV とのやり取り。
• 古い .xls のバイナリー形式には使いません（先に LibreOffice で

変換してください: soffice --headless --convert-to xlsx old.xls）。

事前に必要なもの

• Python 3.10 以上と openpyxl（pip install openpyxl）。ほかに

外部のパッケージは要りません。あとはすべて標準ライブラリーです。

• 任意: 画面なしでの再計算や形式の変換のための LibreOffice

（soffice）。

実行のしかた

補助スクリプトは、この skill の scripts/ ディレクトリーから terminal ツールで実行します（どのスクリプトも --help に対応します）:

python scripts/xlsx_create.py spec.json report.xlsx   # build from JSON spec
python scripts/xlsx_read.py report.xlsx --sheets      # inventory
python scripts/xlsx_read.py report.xlsx --json --sheet Data
python scripts/xlsx_read.py report.xlsx --formulas
python scripts/xlsx_edit.py report.xlsx --sheet Data --set B2=42 --recalc
python scripts/csv_to_xlsx.py data.csv out.xlsx --encoding utf-8
python scripts/xlsx_to_csv.py report.xlsx out.csv --sheet Data

JSON の指定は write_file で書き、スクリプトが出す JSON は read_file か標準出力からそのまま確かめてください。

早見表

手順

1. 作ります: JSON の指定を書きます（形式は

xlsx_create.py --help とその説明文に書いてあります）。シートごとに rows（数や文字、または体裁を付けたセルの指定）、抜き差しで 上書きする cells、column_widths、row_heights、merges、 freeze_panes、autofilter、conditional_formats（cell_is の 条件とカラースケール）、charts（セル範囲からの棒・折れ線・円）、 validations（ドロップダウン）を指定できます。型のある値は、 JSON の数値と真偽値がそのまま通り、日付は {"value": "2026-01-31", "type": "date"} の形にします。 数値の書式は Excel の書式文字列です。通貨は "$#,##0.00"、 百分率は "0.0%"、日付は "yyyy-mm-dd" のように書きます。

1. 数式: 指定の中で "formula": "SUM(B2:B9)"、または編集時に

--set "C1==SUM(A:A)" で設定します。数式を書くときは、指定に "full_calc_on_load": true を足すか、編集時に --recalc を 付けてください。これでブックの fullCalcOnLoad フラグが立ち、 Excel や LibreOffice が開いたときにすべて計算し直します。 openpyxl 自体は数式を決して計算しません。

1. 読みます: 一覧（名前、大きさ、結合された範囲、グラフの数）は

--sheets、データは --json/--csv、数式の文字列と計算済みの 結果を並べて見るには --formulas を使います。計算済みの結果は、 そのファイルを最後に本物の表計算ソフトが保存したときだけ入って います。openpyxl で作ったばかりのファイルでは null が返ります。 画面なしで結果を出したいときは、 soffice --headless --convert-to xlsx file.xlsx を実行してから --data-only で読み直してください。

1. 直します: xlsx_edit.py は、名前の変更と複製を先に行い、次に

行や列の構造の変更、最後に --set/--append を行います。--out を 指定しない限りその場で書き換えるので、元のファイルが必要なら 先にコピーしてください。

1. CSV とのやり取り: csv_to_xlsx.py はセルごとに整数・小数・

真偽値・ISO 形式の日付を推測し、見出しの行に体裁を付けます。 xlsx_to_csv.py は ISO 形式の日付を書き、空のセルは空文字にします。 どちらも既定は UTF-8 で、--encoding を受け付けます（Excel と 相性のよい BOM 付きなら utf-8-sig、古い Windows の書き出しなら cp1252 など）。

つまずきやすいところ

• openpyxl は計算しません。 数式の結果を取れるのは

load_workbook(path, data_only=True) を使ったときだけで、しかも そのファイルを以前に Excel か LibreOffice が保存していた場合に 限られます。そうでなければ None が返ります。

• 挿入と削除では参照がずれません。 insert_rows や

delete_cols などはセルの値を動かしますが、結合したセルの範囲、 数式の参照、グラフの位置、条件付き書式の範囲は更新しません。 結合や数式のあるシートで構造を変えたあとは、--sheets と --formulas で見直して手で直してください。

• data_only=True で読んでから保存すると、数式がすべて何も

言わずに消えます（計算済みの値に置き換わります）。それが目的で ない限り、そうやって読んだブックを保存してはいけません。

• 読み込むとグラフや画像が落ちます: openpyxl はグラフを

そのまま往復させられないので、グラフのあるブックを直して保存すると グラフが消えます。直したあとにグラフを付け直すか、グラフのある ファイルを保存し直さないようにしてください。

• CSV の地域差の罠: 文字コードは必ずはっきり渡してください

（スクリプトはすでにそうしています）。ヨーロッパの CSV は区切りに ; を使い、小数点にコンマを使うことがよくあります。 --delimiter ';' を使い、"12,5" のような値は文字列のままに なると思っておいてください。

• 日付は日時になります: Excel は日付を連番で保存し、openpyxl は

datetime/date のオブジェクトを返します。ここでの書き出しは ISO 形式の文字列にします。

• シート名は 31 文字までで、[ ] : * ? / \ は使えません。

確認

• 作ったあと: xlsx_read.py out.xlsx --sheets を実行し、シート名・

大きさ・結合された範囲・グラフの数が意図どおりか確かめます。

• --json でデータを書き出し、元の値と比べます。
• 直したあと: 触った範囲をもう一度書き出します。数式を書いたなら、

--formulas に並ぶことと --recalc を付けたことを確かめます。

• 見た目までしっかり確かめたいときは LibreOffice で開きます:

soffice --headless --convert-to pdf out.xlsx を実行し、その PDF を 見てください。