document-xlsx

Document XLSX Skill - クイックリファレンス

適用範囲： Anthropic の公式 xlsx スキルが利用できる場合は、通常の作成・編集、数式を優先した財務モデル、LibreOffice による再計算（recalc.py）、数式エラーのスキャンには、そちらを優先してください。このスキルは、次の専門分野で使用します。

• ネイティブのグラフ、ピボット、データの入力規則、条件付き書式
• Office Scripts、Microsoft Graph、xlwings による自動化
• 非常に大きな（write_only／read_only）ファイル
• 信頼できないブックの監査とサニタイズ

基本的な判断ルール

• まず実行環境を決めます： ローカルでのファイル生成、クラウド上のブック自動化（Microsoft 365）、デスクトップ版 Excel の自動化、または監査とサニタイズのいずれかです。
• XlsxWriter は書き込み専用です。 既存の .xlsx を開いたり編集したりすることはできません。「このブックを編集する」場合は、openpyxl（または Node の ExcelJS）を使用してください。編集タスクに XlsxWriter を選ぶと、すぐに失敗します。
• テーブルを優先してエクスポートします： 1 行の見出し、名前付き Excel テーブル、固定された見出し行、範囲を限定したデータを使用します。テーブルにはオートフィルターが含まれているため、同じ範囲に別途 autofilter() を設定すると OverlappingRange が発生します。
• ライブラリは数式を書き込みますが、計算するのは計算エンジンです。 openpyxl は数式を評価しません。XlsxWriter は通常、キャッシュされた 0 のプレースホルダーを書き込んで再計算を要求するか、明示的に指定された結果を受け取ります。キャッシュが空でないことは、計算済みの証拠にはなりません。数式を保持し、対象のエンジンで再計算し、その前に必要な結果を個別に計算してください。XlsxWriter の数式結果を参照してください。
• 新しい関数には、指定された OOXML 表記が必要です。 openpyxl で扱う場合は、作成者の新しい関数の一覧で関数に必要なプレフィックスを確認してください。openpyxl.utils.FORMULAE は互換性の確認には使えません。スピル数式には、デフォルトで XlsxWriter の write_dynamic_array_formula を使用してください。受け取り側の Excel ビルドが不明な場合は、INDEX/MATCH とネストした IF を優先してください。新しい関数や配列関数を書き込む場合、またはキャッシュされた結果を読み取る場合は、references/excel-formulas.md を読み込んでください。
• ライブラリのデフォルト設定では、安全側に動作しないことがあります。明示的に設定してください：
  • Excel の入力チェックでは、入力値の検証エラーアラートと errorStyle="stop" を明示的に設定してください。openpyxl 自体は、割り当てられた値を検証しません。コード内でも入力を確認してください。
  • XlsxWriter では、strings_to_formulas がオフでない限り、= で始まる文字列は数式として扱われます。
  • XlsxWriter の add_table は、例外を発生させる代わりに警告を出して負のコードを返します。
• ネイティブのピボット： Office Scripts（Microsoft 365）または xlwings（デスクトップ版 Excel）を使用してください。openpyxl と XlsxWriter では作成できません。ヘッドレスでエクスポートする場合は、事前計算済みの集計テーブルを書き込んでください。
• 信頼できないブック： keep_links=False と keep_vba=False を指定して読み込み、最初に scripts/xlsx_audit.py を実行してください。このスキルでは、マクロの作成も実行もしません。
• 大きなファイル： lxml をインストールし、Workbook(write_only=True)／load_workbook(read_only=True) を使用してください。どちらもツリー全体を構築せずにストリーミング処理します。書き込み専用ブックは一度だけ保存できます（WorkbookAlreadySaved）。
• 形式の上限： ファイル形式で定められた、シートあたり 1,048,576 行 × 16,384 列です。ページ分割または複数シートのレイアウトを、あらかじめ決めてください。

クイックリファレンス

タスク	ツール	使用場面
テーブル優先の新規エクスポート	XlsxWriter（pandas/Polars）	テーブル、書式、ネイティブグラフ、動的配列を含むレポート
既存のブックを編集	openpyxl	シート、数式、テーブル、入力規則、保護
Node/TS サービス	ExcelJS	構造とスタイル。ネイティブグラフやピボットが必要な場合は、インストール済みリリースのドキュメントを確認し、必要な往復処理をテストしてください
Microsoft 365 ブック	Office Scripts / Microsoft Graph Excel	ネイティブのピボットとテーブル、リモートセッション
デスクトップ版 Excel の機能	xlwings	Excel がインストールされたマシン。ヘッドレス CI には不向きです
共有前の監査（ゲート）	scripts/xlsx_audit.py	ブロッキング対象の検出結果がある場合、ゼロ以外の終了コードを返します
テキスト／リンクのクリーンアップ	scripts/xlsx_sanitize.py	リスクのある文字列に表示されるアポストロフィを追加し、オプションで外部リンクのパーツを削除します。エクスポート時に CSV もサニタイズしてください
再現可能なエクスポート	scripts/xlsx_export_report.py	CSV/JSON/Parquet からテーブル優先の .xlsx を作成します。入力テキストが数式に変換されることはありません

スクリプトと終了コード

python3 scripts/xlsx_audit.py workbook.xlsx --format md       # gate
python3 scripts/xlsx_audit.py workbook.xlsx --report-only     # inventory; invalid input still exits 2
python3 scripts/xlsx_sanitize.py in.xlsx out.xlsx --strip-external-links
python3 scripts/xlsx_export_report.py data.csv report.xlsx --title "Sales"
python3 scripts/test_xlsx_sanitize.py                         # atomic output and alias rejection regressions

スクリプト	0	1	2
xlsx_audit.py	ブロッキング対象の検出結果はありません（ヒューリスティックによる検出結果は確認が必要な場合があります）	ブロッキング対象の検出結果：キャッシュされたエラー値、_xlfn. のない新しい関数、危険なテキスト、外部リンクのパーツ、VBA	ファイルがない、zip 形式ではない、またはブックではない
xlsx_sanitize.py / xlsx_export_report.py	書き込み完了	該当なし	入力がない、読み取れない、または書き込みに失敗しました。部分的な出力は残りません

監査で報告されますがブロッキング対象にはならないヒューリスティックによる検出結果：数式内のハードコードされた定数、非表示または非常に非表示のシート、HYPERLINK 数式、キャッシュ値のない数式。共有前に確認してください。監査は静的なもので、数式が正しく評価されることは証明できません（下記の計算証拠ゲートを参照）。

主な操作

テーブル優先のエクスポート（XlsxWriter）

import pandas as pd

with pd.ExcelWriter("report.xlsx", engine="xlsxwriter",
                    engine_kwargs={"options": {"strings_to_formulas": False}}) as writer:
    df.to_excel(writer, sheet_name="Sales", index=False, startrow=1)
    workbook, worksheet = writer.book, writer.sheets["Sales"]
    header_fmt = workbook.add_format({"bold": True, "bg_color": "#D9E2F3"})

    worksheet.write("A1", "Sales report")
    worksheet.freeze_panes(2, 0)
    # The table brings its own autofilter; a separate worksheet.autofilter() over the
    # same range raises OverlappingRange. Rows: header=1, data=2..len(df)+1, totals=len(df)+2.
    status = worksheet.add_table(1, 0, len(df) + 2, len(df.columns) - 1, {
        "name": "SalesTable",
        "style": "Table Style Medium 2",
        "total_row": True,
        "columns": [{"header": col, "header_format": header_fmt,
                     **({"total_function": "sum"} if col in ("qty", "total") else {})}
                    for col in df.columns],
    })
    if isinstance(status, int) and status < 0:   # XlsxWriter warns instead of raising
        raise ValueError("add_table rejected the table definition")

テーブル範囲が 1 行短いと、合計行が最後のデータ行を気付かないうちに上書きします。references/excel-tables-structured-references.md を参照してください。

既存のブックを安全に編集（openpyxl）

from openpyxl import load_workbook

wb = load_workbook("input.xlsx", keep_vba=False, keep_links=False)
ws = wb["Sales"]
ws["A1"] = "Sales report"
ws.freeze_panes = "A2"
wb.save("output.xlsx")

data_only=True で読み込んでから保存しないでください。すべての数式がキャッシュ値、または何もない状態に置き換わります。

既知の制限と注意事項

• Google Sheets と LibreOffice では、Excel のすべての機能が保持されるわけではありません。対象のビューアーで、ピボット、動的配列数式、保護、高度な書式を確認してください。

• データの入力規則は UI のメタデータです。貼り付けによって回避されたり、セルのルールが置き換えられたりする可能性があります。入力規則と保護、コード内のチェックを組み合わせてください。openpyxl の入力規則に関する制限 を参照してください。

• シートとブックの保護パスワードは抑止策であり、暗号化ではありません。機密データには、ファイルレベルの暗号化またはプラットフォームのアクセス制御を使用してください。references/excel-security-protection.md を参照してください。

• pandas.read_excel() では、条件付き書式、入力規則、保護、グラフは取得できません。監査でこれらが必要な場合は、OOXML パーツを直接読み取るか、openpyxl を使用してください。

• ライブラリの動作はリリースによって変わります。信頼して使用する前に、主張されているデフォルト（たとえば、入力規則や数式のオプション）をインストール済みバージョンで再テストしてください。

デフォルトのワークフロー

1. 作成： 実行環境を選び、テーブル優先のレイアウトから始め、入力、計算、出力を分けてください。
2. ゲート： python3 scripts/xlsx_audit.py out.xlsx --format md が終了コード 0 を返すことを確認し、assets/spreadsheet-model-review-checklist.md に照らして確認してください。
3. 出荷： エクスポートしたテキストをサニタイズし、外部リンクを確認し、Excel のアクセシビリティ チェックを実行してから、Excel と対象の副次ビューアーの両方でファイルを開いてください。

推奨事項と避けるべき事項

前提条件には値、単位、ソース、日付を記録し、管理用の合計値とチェックセルを含めてください。非表示シートでは、PII やシークレットを保護できません。

計算結果の検証ゲート

リリース前に計算の仕様を定義します。正式な入力データ、想定される数式または計算値、計算エンジン、再計算モード、統制合計を明確にしてください。数式が重要な場合は、最終ブックを次の 2 回開きます。

1. 数式を表示して、一貫性を確認します。
2. 指定した計算エンジンで再計算した後、キャッシュされた結果とエラーセル（#REF!、#VALUE!、#DIV/0!、#NAME?、#N/A）を確認します。

計算エンジンを利用できない場合は、数式の結果を未検証として明記し、独立して計算した統制合計を提示します。キャッシュが空であることも、プレースホルダーのゼロも、計算が行われた証拠にはなりません。キャッシュ値を提供するのは、正式な入力データから独立して計算した場合に限ります。

ナビゲーション

参考資料

• references/excel-formulas.md - _xlfn. 接頭辞、スピル関数、配列数式、値の読み戻し
• references/excel-tables-structured-references.md - テーブル範囲の算術演算、構造化数式
• references/excel-charts.md - グラフの選択、参照の接続、openpyxl のグラフに関する注意点
• references/excel-formatting.md - 書式より先にデータ型を整えること、条件付き書式のルール、レイアウト
• references/excel-data-validation.md - 入力を強制するドロップダウン、名前付きリスト、連動する入力規則
• references/excel-pivot-tables.md - ネイティブのピボットテーブルと事前計算済みの集計の比較
• references/excel-security-protection.md - 保護の制限、暗号化、インジェクション、リンク
• references/excel-cloud-automation.md - Office Scripts、Microsoft Graph Excel、xlwings
• references/excel-accessibility-compliance.md - アクセシビリティ、Section 508、EN 301 549 の確認
• references/extraction-stack.md - LLM/RAG パイプライン向けの用途別抽出ツール候補
• data/sources.json - ベンダーおよび標準規格のリンク

アセット

• assets/financial-report.md - 財務諸表のルール：連動する諸表、符号の規則、チェックセル
• assets/data-dashboard.md - ダッシュボードのレイアウトに関する注意点（結合された KPI カード、グラフの配置、非表示データ）
• assets/spreadsheet-model-review-checklist.md - ブックの品質保証チェックリスト

関連スキル

• ../document-pdf/SKILL.md - スプレッドシートデータからの PDF 生成
• ../ai-ml-data-science/SKILL.md - データ分析とデータフレームのワークフロー
• ../data-sql-optimization/SKILL.md - データベースからブックへのパイプライン

学びのループ

過去の判断や落とし穴が関係する場合は、learnings.consolidated.md があれば参照してください。必要な履歴を確認する場合、または利用可能な代替ファイルとして使う場合に限り、learnings.md を使用します。それ以外の場合は、どちらも参照しません。

適用後、記憶しておく価値のあるパターン、防止すべきミス、または意外だった分野の事実に遭遇した場合は、agents-skills-feedback-loop/scripts/append_learning.py を使って learnings.md に日付付きの箇条書きを 1 つ追加します。SKILL.md 自体は変更しないでください。