google-sheets について
google-sheetsは、既存のスプレッドシートに構造化データを書き込むスキルです。Hyper MCPとGoogle Sheets連携が必要で、実際の見出しに基づく列の対応付けと、書き込み後の読み戻し確認を重視します。
主な機能
- 01ワークブックとシートの確認
- 02見出し名によるフィールド対応付け
- 03書き込み範囲の確認
- 04狭い範囲への書き込み
- 05読み戻しによる結果確認
活用シーン
- 01既存シートへの構造化レコードの追加
- 02無関係な列や補助セルの上書き防止
MCP 対応
Hyper MCPのインストールと接続が必要で、MCPクライアントまたはHyper CLIからツールを検索、説明、呼び出します。Google Sheets連携を使ってシートを確認し、データを書き込み、読み戻して検証します。
インストール
コマンドをコピーしてターミナルで実行します。
npx skills add https:/インストール後、Claude Code で/google-sheetsを入力して読み込まれたか確認します。
詳細
Google Sheets への書き込み
既存のスプレッドシートに構造化データを書き込む必要がある場合は、必ずこのスキルを使用してください。
要件
- Hyper MCP がインストールされ、接続されていること。 https://app.hyperfx.ai/mcp
- https://app.hyperfx.ai/apps で Google Sheets 連携 が有効になっていること。
このスキルのツールの実行方法
このスキルの各ツールには、正規のツール名が付いています。利用する環境に応じた呼び出し方法で実行してください。
| 環境 | ツールを探す | 実行する |
|---|---|---|
| MCP クライアント（Claude、Cursor、Codex、ChatGPT） | search("<what you want to do>")、続けて describe("<name>") | call("<name>", {...}) |
| Hyper CLI | hyperai search "<what you want to do>"、続けて hyperai describe <name> | hyperai call <name> --json '{...}' |
ツールが見つからない場合、その連携はワークスペースに接続されていないか、有効になっていません。そこで作業を中止し、接続が必要な連携をユーザーに伝えてください。
基本ルール
推測した列文字だけを頼りに、Google Sheets に書き込んではいけません。
必ず以下を行ってください。
- ワークブックと対象のワークシートを確認する
- 実際のヘッダー行を見つける
- ヘッダー名に基づいてフィールドを対応付ける
- 書き込み先の範囲を確認する
- 書き込む
- サンプル行を読み戻して、対応関係を確認する
避けるべき重大な失敗
- 1 行目が実際のヘッダー行だと決めつけないでください。
- 列
Aが最初の業務データ列だと決めつけないでください。 Total、メモ、数式、結合されたラベル、区切り列などの補助セルを、実際のヘッダーとして扱わないでください。- 既存のデータとレイアウトを確認する前に、広い範囲を上書きしないでください。
- 書き込んだセルを読み戻すまでは、成功したと報告しないでください。
必須のワークフロー
ステップ 1：ワークブックの構造を確認する
次のツールから開始します。
google_sheets_get- 必要に応じて
google_sheets_worksheets_list
以下を確認します。
- ワークシートのタイトル
- 行数／列数
- 複数の候補タブがあるかどうか
ステップ 2：実際のヘッダーを見つけるのに十分なコンテキストを読み取る
構造が不明な場合は、複数の行を読み取ってください。
一般的な例：
google_sheets_values_get(..., range="Sheet1!A1:Z5")
次の項目を確認します。
- 実際の列ラベル
- 実際のテーブルより前にある補助列
- タイトル行、合計、数式、空白の区切り
最初の行に Total、Notes などのレコードではないメタデータが含まれている場合、その行だけを基準に書き込み範囲を決めないでください。
ステップ 3：ヘッダーの対応表を作成する
記憶ではなく、実際のシートのヘッダー名に基づいてソースフィールドを対応付けます。
例：
- ソースフィールド
business_name-> シートのヘッダーBusiness Name - ソースフィールド
contact_email-> シートのヘッダーOwner (s) Email
必要なヘッダーが存在しない、または曖昧な場合は、推測せず作業を中止し、ユーザーに確認してください。
ステップ 4：最も安全な書き込み方法を選ぶ
次を使用します。
- 検証済みの連続した範囲が 1 つの場合は
google_sheets_values_update - 検証済みの範囲が複数ある場合は
google_sheets_values_batch_update
広範囲を一括で書き込むより、範囲を絞った書き込みを優先してください。
固定された列を持つテーブルにレコードを追加する場合は、まずヘッダーの対応表に基づいて書き込み先の列を正確に特定してください。
書き込みルール
- 対応関係を確実に確認した列だけに書き込んでください。
- 関係のない列は変更しないでください。
- テーブルの前に補助列がある場合は、列
Aではなく、実際に対応付けた列から書き込みを開始してください。 - 意図的に空欄にするフィールドは、検証済みの該当列にのみ空の値を書き込んでください。
- ユーザーが数式や Sheets の解析動作を明示的に求めない限り、
RAWを使用してください。
書き込み後の確認は必須です
書き込み直後に、以下を行ってください。
- 書き込んだ範囲を正確に読み戻す
- 少なくとも 2～3 行のサンプルを確認する
- 各フィールドが意図したヘッダーの下に書き込まれていることを確認する
読み戻したデータの位置がずれていた場合は、そのことを認め、成功を報告する前に修正してください。
推奨するツールの使用順序
google_sheets_getA1:Z5など、ヘッダーを特定する範囲に対するgoogle_sheets_values_get- 必要に応じて、既存データと書き込み先エリアに対する
google_sheets_values_batch_get google_sheets_values_updateまたはgoogle_sheets_values_batch_update- 検証のため、書き込み先の範囲に対する
google_sheets_values_get
考え方の例
悪い例：
- 「最初の方に
Business Nameが見えたので、A2:F51と書き込みます。」
良い例：
- 「最初に見えている行では、列
AにTotal: 7が含まれており、Business Nameは実際には列Bにあるため、列B以降を対象に書き込み範囲を設定し、書き込み後に確認します。」