Claude xlsxスキルの使い方 — openpyxlとpandasの使い分け

xlsxスキルは、スプレッドシートを読む・直す・作る作業を、手順書つきでClaudeに任せるためのスキルです。SKILL.mdの冒頭に作業別の早見表があり、数式や書式を含む作成・編集はopenpyxl、データの一括入出力はpandas、ざっと中身を見るだけならmarkitdownと決まっています。

使い分けの一文だけを知っていても、実際には「保存したら数式が消えた」「再計算したのに結果が空」といった事故が起きます。このスキルの価値はむしろ、そうした落とし穴の一覧にあります。ここでは分岐の考え方と、SKILL.mdが名指しで警告している箇所を順に見ます。

xlsxスキルとは何か、どこにあるか

xlsxスキルは、Anthropicのスキル用リポジトリ(anthropics/skills)のskills/xlsxにあります。中身はSKILL.md、LICENSE.txt、scriptsディレクトリの3つです。scriptsの下には再計算用のrecalc.pyと、LibreOfficeの起動を補助するofficeディレクトリが入っています。

READMEによると、このリポジトリのスキルの多くはApache 2.0のオープンソースです。ただしdocx・pdf・pptx・xlsxの4つは例外で、Claudeの文書作成機能の裏側で動いているものを参考用に公開した「source-available」(ソースは読めるがオープンソースではない)という扱いです。SKILL.mdのライセンス欄もProprietaryになっています。社内スキルの雛形として眺めるのは自由ですが、再配布の可否はLICENSE.txtで確かめる必要があります。

API側の標準スキルとしてのxlsxの呼び出し方はAgent SkillsのAPI標準スキル一覧にあります。この記事はそれとは別に、SKILL.mdの中身に絞ります。

Claude Codeで使うには

Claude Codeにはxlsxスキルは同梱されていません。READMEは、リポジトリをプラグインのマーケットプレイスとして登録する方法を示しています。

/plugin marketplace add anthropics/skills
/plugin install document-skills@anthropic-agent-skills

READMEはdocument-skillsとexample-skillsの2つのプラグインを案内しています。xlsxを含む文書系のスキルは、前者を入れる想定です。インストール後は、READMEの例のとおり「xlsxスキルを使って、この表を直して」のように名前を出して頼めます。手で配置するなら、スキルフォルダを~/.claude/skills/xlsx/(全プロジェクト共通)か.claude/skills/xlsx/(そのリポジトリだけ)に置きます。スキルの置き場所の一覧はClaude Codeのスキル解説に載っています。

作業別の分岐表を読む

SKILL.md冒頭の表は4行です。

markitdownの行には、見落としやすい注意が付いています。出力にセルの座標がないので、この結果から編集計画を立ててはいけない、という指示です。中身の把握に使い、実際の編集はopenpyxlで座標を確かめながら進める、という二段構えになります。

pandasを選ぶ場面

pandasが向くのは、表がデータとして整っていて、書式や数式を保つ必要がないときです。CSVを読み込んで集計し、結果をto_excelで書き出す、といった流れです。SKILL.mdはこの用途を「Bulk data in or out」と呼んでいます。

逆に言えば、既存のブックに手を入れる作業でpandasを通すと、書式や数式の扱いを自分で背負うことになります。SKILL.mdは、既存ファイルの編集では「ファイルの慣習に厳密に合わせる」ことを求めています。入力セルは文字色・塗り・網掛けで区別されていることが多いので、それを見つけて、書き込むのは入力セルだけにし、既存の数式には触れない、という指示です。この条件はpandasで表ごと書き戻す方法とは相性が悪く、openpyxlでセル単位に触る側の仕事になります。

pandas側の実践手順はClaude Codeでpandasのデータ処理を書く実践手順にあります。

すべての出力に求められる要件

SKILL.mdは、どの作業にも共通する要件を先に並べています。依頼文に書かなくても、スキルが読み込まれていれば守らせる前提のものです。

• フォントはArialやTimes New Romanなど、きちんとしたものに統一する(ユーザーが別に指定した場合を除く)
• 数式エラーはゼロにする。recalc.pyがerrors_foundを返しているうちは納品しない
• 集計結果をPythonで計算して値として書かず、=SUM(B2:B9)のように数式で書く。入力が変わったら再計算されるブックにする
• ユーザーの指定は文字どおりに守る。タブ名、列見出し、指定された数式のとおりに作る
• 仮定と、ベタ書きの数値は、読む人の目に触れる場所(セルのコメントや表の末尾の隣接セル)に書く
• 他人に記入してもらうブックを新規に作るときは、編集してよいセルを示す凡例と、現実的な値の入った例の行を1つ付ける。ただし既存ファイルの編集では、例の行を足さない

エラーの項で、SKILL.mdはひとつ実務的な指示を出しています。「前からあるエラーだ」と思うなら証明せよ、というものです。元のファイルをdata_only=Trueで開き、そのセルの値を見ます。自分が入れたエラーも、もともとあったエラーも、再計算後の見た目は同じだからです。

再計算は数式があれば必須

openpyxlは数式を文字列として書くだけで、計算結果(キャッシュ値)を持ちません。再計算するまでは、pandasやload_workbook(data_only=True)、多くのプレビューアーが、数式セルをNoneとして読みます。

python scripts/recalc.py output.xlsx 60

引数はファイルと、任意のタイムアウト秒数です(既定は30秒)。LibreOfficeがすべての数式を計算し、ファイルはその場で書き換えられ、結果がJSONで返ります。JSONの主なキーは次のとおりです。

• status: successかerrors_found
• total_formulas: 数式の総数
• total_errors: エラーの総数
• error_summary: エラー種別ごとの場所(最大100セル。省略された分はlocations_truncatedが数を示す)

終了コードには罠があります。statusの代わりにerrorキーが返ったときは、再計算そのものが行われていません。そしてこのときだけ非ゼロで終了します。errors_foundは終了コード0なので、「コマンドが成功したから問題ない」と読んではいけません。error_summaryの長さではなくtotal_errorsを信頼せよ、という注意も付いています。

recalc.pyの中身を見ると、sofficeがPATHにない場合のメッセージが用意されています。ローカルのClaude Codeで使うなら、LibreOfficeを先に入れておく必要があります。SKILL.mdの依存関係の節も、openpyxl・pandas・markitdown(pip)とLibreOfficeを挙げています。事前インストール済みという記述は、スキルが動く実行環境の話です。手元で動かすときは、importに失敗したパッケージだけをpip installします。

再計算が通っても「正しい」とは限らない

SKILL.mdは、緑の結果が示すのは数式が「評価できた」ことで、「正しい」ことではないと書いています。範囲が1行ずれていても、別の行を参照していても、エラーなしで間違った数字が出ます。対策は単純で、数式を2〜3本先に書いて期待する値を引いているか確かめてから、表全体を組むことです。

外部ファイルへのリンクは再保存で失われる

数式が='[1]Returns Analysis'!$B$2のような形をしているとき、[1]はシート名ではなく、別ファイルへの参照リストの番号です。openpyxlで保存し直すとキャッシュ値が落ち、LibreOfficeは参照先のファイルを見つけられず#NAME?を書き込み、リンクを消します。recalc.pyはこの状態を検知すると実行を拒みます。元のファイルから該当セルの値を先に控えてください。--forceで強行もできますが、その場合は損失を受け入れることになります。

使える関数を選ぶ

LibreOfficeはExcelより実装している関数が少なく、評価できない関数は#NAME?という文字列のまま納品物に焼き付きます。SKILL.mdの指示は3段階です。

1. 2007年以前の関数を優先する。SUMIFS、INDEX、MATCH、IFERROR、SUMPRODUCTは接頭辞が要りません。
2. 6つの関数は_xlfn.を付ければ使える。openpyxlは式をXMLにそのまま書くので、Excelが内部で付けている接頭辞を自分で書く必要があります。対象は_xlfn.TEXTJOIN、_xlfn.CONCAT、_xlfn.IFS、_xlfn.SWITCH、_xlfn.MAXIFS、_xlfn.MINIFSです。接頭辞なしで書くと#NAME?になります。
3. XLOOKUP、XMATCH、SORT、FILTER、UNIQUE、SEQUENCEは使わない。どの接頭辞を付けても、実行環境のLibreOfficeでは評価できません。

3つ目には理由が付いています。新しいビルドなら評価できる場合もありますが、これらは結果が複数セルに広がる(スピルする)関数です。openpyxlが書いたファイルにはスピルの情報がないので、範囲の左上のセルにしか値が入りません。しかもrecalc.pyはtotal_errors: 0を返します。エラーなしなのに結果が欠けている、という最も気づきにくい壊れ方です。

代わりに、検索はINDEXとMATCHを使い、並べ替え・絞り込み・重複除去はPythonで済ませてからセルに書きます。ここでpandasが効いてきます。分岐表の2行目と1行目は対立するのではなく、「データの整形はpandas、セルへの数式と書式はopenpyxl」と役割を分けて組み合わせる関係です。

LibreOfficeが構文を解釈できなかった数式は、小文字に直されて書き戻されます。#NAME?と並んで、ひと目で分かる目印になります。

openpyxlの落とし穴

SKILL.mdのopenpyxl gotchasは6項目です。

2つ目が最も被害が大きく、しかも取り消せません。数式を確認するつもりでdata_only=Trueで開き、そのままsaveすると、元ファイルの数式が計算結果の値で上書きされます。読むだけのブックと保存するブックは、変数を分けておくのが安全です。

3つ目の注記も覚えておく価値があります。数式の結果が空文字列""のセルは、再計算後でもNoneとして読み戻されます。Noneが出たからといって、必ず再計算漏れとは限りません。

財務モデルの書式規約

SKILL.mdには、ユーザーが別の指示を出さず、既存ファイルにも独自の流儀がない場合に使う「財務モデル」の規約があります。経理や事業計画のブックを作るときの既定値として読めます。

構造面の指示は3つです。仮定は1つずつラベル付きのセルに置き、=B5*(1+$B$6)のようにセル参照で使う(=B5*1.05と書かない)。予測期間の数式は全期間で揃える。分母がゼロになりうる除算は守る。SKILL.mdは、行の途中に1セルだけ違う数式が混ざるのが最もよくある沈黙のエラーだと述べています。

日本の帳票に当てはめるなら、通貨記号と書式コードは円に合わせて読み替えることになります。この読み替えはSKILL.mdには書かれていないので、依頼文で指定すると確実です。

Claudeに頼むときの依頼文

分岐を踏まえると、依頼文に入れておくと効く情報は4つに絞れます。

1. 既存のブックを直すのか、新しく作るのか
2. 数式を残す必要があるか(あるならopenpyxl側になる)
3. 使ってよい関数の範囲(古いExcelで開く人がいるかどうか)
4. 納品前に再計算させ、total_errorsを報告させること

生成されたファイルを手元に受け取る手順はSkillsの生成ファイルをダウンロードする4ステップに、Claudeがファイルを作れる範囲とセキュリティ設定はClaudeでファイル作成・編集ができる範囲とセキュリティ設定にまとまっています。

確認したい点のまとめ

xlsxスキルの分岐は「数式と書式はopenpyxl、一括入出力はpandas、中身の確認はmarkitdown」で、実作業の山場はその後の再計算にあります。recalc.pyの終了コードはerrors_foundでも0なので、JSONのstatusとtotal_errorsを読むところまでが1セットです。関数は2007年以前のものを基本にし、XLOOKUPなどのスピル関数は避けて、整形はPythonで済ませます。

既存ファイルの編集では、財務モデルの規約よりそのファイルの流儀が優先されます。最初に入力セルの見た目を探すこと、これが外せない手順です。