agentleFS
k3forxk3forx/skills/read-google-sheet/SKILL.md

read-google-sheet

Skill1 starsChanged 4 months agoApache-2.0View on GitHub

Google スプレッドシート(Google Sheets / スプシ)の中身を、途中で切れずに全行・全体を確実に読み取ってデータとして取り込むためのスキル。Google Drive の read_file_content は大きいシートを黙って途中 truncate する(下のセクションや行が欠ける)ため、代わりに download_file_content で CSV エクスポート(base64)→デコードして全データを取り込む。ユーザーが「このスプシ読んで/中身教えて」「スプレッドシートのデータを取って/分析して/集計して」「Google Sheets の内容を全部見て」「シートの下の方が読めてない/途中で切れる」と言ったり、docs.google.com/spreadsheets の URL を貼ってデータの読み取り・分析・加工を頼んだときは必ず起動すること。単なる Drive のファイル検索・一覧や、Google ドキュメント/スライドの読み取りには使わない(対象は表形式データのスプレッドシートのみ)。

The file

Files
SKILL.md

Read Google Sheet — スプレッドシートを切らずに全部読む

なぜこのスキルがあるか(これを読む前に知っておくこと)

Google Drive MCP の read_file_content は、仕様として 「very large files では内容が不完全になる」。行数の多いスプレッドシートや、1 枚のシートに複数セクションが縦に積まれたシート(例:上に集計表、下に「反響内訳」)だと、下の方が警告なく truncate される。気づかずに欠けたデータで集計・分析すると結論を間違える — これが一番怖い。

確実なのは、read_file_content ではなく download_file_content で CSV としてエクスポートして受け取り、base64 をデコードして全行を取り込む経路。download 経路は truncate しない。このスキルはその経路を定型化したもの。

主目的は データを作業コンテキストに正しく全量取り込み、そのまま分析・集計・加工に使える状態にすること。

手順

1. スプレッドシートの fileId を確定する

  • URL を渡された → https://docs.google.com/spreadsheets/d/<FILE_ID>/edit#gid=<GID> の <FILE_ID> を抜き出す。末尾の #gid=<N> は「特定タブ」の指定(複数タブの節を参照)。
  • ID だけ渡された → そのまま使う。
  • 名前しか分からない → search_files で探す。例: query = "mimeType = 'application/vnd.google-apps.spreadsheet' and title contains 'Q4 sales'" 複数ヒットしたら候補を提示して確認する。

2. CSV でまるごとダウンロードする(read_file_content は使わない)

download_file_content を exportMimeType="text/csv" で呼ぶ。返り値は base64 文字列(=ファイルの中身そのもの、truncate なし)。

read_file_content を使わない理由は、上で述べたとおり大きいシートで途中で切れるから。「全部読む」が目的のこのスキルでは不適。

3. base64 をデコードして全データにする

MCP が返した base64 を Write ツールで .b64 ファイルに保存し、同梱スクリプトでデコードする。base64 の macOS/Linux フラグ差(-D vs -d)を踏まないよう、必ずこのスクリプトを使う(依存ゼロ・stdlib のみ):

python3 <このスキルの>/scripts/decode_sheet.py --b64 raw.b64 --out sheet.csv --print
  • --print は先頭 20 行のプレビューと行数を表示。全量確認は出力 CSV を Read する。
  • これで sheet.csv に完全な CSV が落ちる。この CSV を Read してコンテキストに取り込み、集計・分析に使う。
  • 注意:.b64 には MCP が返した base64 を 末尾まで丸ごと書く。ここで切ると、せっかくの download 経路でも末尾セクションが落ちて truncate と同じ事故になる(本末転倒)。大きいシートほど base64 も長いので、省略せず全量保存する。

4. 分析に使う/必要なら残す

デフォルトは「取り込んで分析に使う」。参照用に CSV を残したいときは scratchpad に置く。ユーザーが Markdown 表での提示や特定セクションだけの抽出を求めたら、取り込んだデータからそれに応える。

複数タブ(複数シート)の罠 ⚠️

Drive の CSV エクスポートは 先頭タブしか出ない。これに気づかず「全部読んだ」と誤解するのは、まさにこのスキルが防ぎたい静かなデータ欠落。以下のいずれかなら CSV ではなく xlsx で丸ごと取る:

  • URL の #gid=<N> が先頭タブ以外を指している
  • ユーザーが特定タブ名に言及している、または明らかに複数タブある

手順:

  1. download_file_content を exportMimeType="application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"(xlsx)で呼ぶ。
  2. スクリプトを xlsx モードで実行 → タブごとに CSV が出る(openpyxl/pandas 不要、stdlib だけで動く):
    python3 <このスキルの>/scripts/decode_sheet.py --b64 raw.b64 --out ./tabs/ --format xlsx --print
    ./tabs/01_<タブ名>.csv, 02_... のようにタブ順で出力される。必要なタブを Read する。

うまくいかないとき

  • 見つからない/権限エラー → search_files で ID を取り直す。自分に共有されていないシートは読めない(ユーザーに共有を依頼)。
  • それでも途中で切れて見える → read_file_content を使っていないか確認。CSV/xlsx の download 経路なら切れない。切れて見えるのは大抵 read_file_content に戻ってしまっているとき。
  • 数式の結果が欲しい → エクスポートには計算後の値が入る(式そのものではなく結果)。集計にはそのまま使える。
  • セルの改行や桁区切りカンマ → CSV は正しくクオートされて出るので、Read すればそのまま扱える。

例

例 1(今回の実例): 「このA/Bレポートのスプシ、read_file_content だと『反響内訳』が読めない。全部読んで」 → URL から fileId 抽出 → download_file_content(fileId, exportMimeType="text/csv") → デコード → 反響内訳まで含む全行を取り込み、そこから分析。

例 2: 「Q4 の売上シート(複数タブある)を月別に集計して」 → 複数タブなので xlsx エクスポート → 全タブを CSV 化 → 各タブを Read して月別集計。

例 3: 「docs.google.com/spreadsheets/d/abc.../edit#gid=88 これ見て」 → #gid=88 が先頭以外の可能性が高い → xlsx で全タブ取得し、当該タブを特定して読む。

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.