Clay テーブル — 識別子（レコードを特定するID）からレコードを探し出し、その時点での状態をスナップショット（現在の姿をそのまま記録）として表示します。具体的には、そのレコードがどのテーブル（データ表）に保管されているのか、各セル（項目）の状態がどうなっているのかを確認できます。 **次のような場合に使用:** - ユーザーが ID を持っていて、「{ID} の履歴を調べて」「{ID} はどこにある？」「このリード（見込み客）にはどんなデータ補強が行われた？」「このレコードは完了している？」といった質問をしたとき
Clay tables — locate a record by identifier and snapshot its state: which table(s) hold it and each cell's status. Use when the user has an id and asks "trace {id}", "where is {id}?", "what enrichments ran for this lead?", or "is this record done?".
次のような場合に使用: 識別情報を手がかりに、レコードを探し出してその現在の状態を確認したいとき — 「12345を追跡して」「jane@acme.comはどこにある？」「このリードに対してどの処理が実行された？」「このレコードは完了した？」など。このスキルは場所の特定 + 状態確認です：レコードがどのテーブルに存在し、各セルがどのような状態にあるかを示します。ただし、あるセルがなぜそのような値を持っているのかという理由については説明しません — それは /tables-value-trace スキルの役割です。
対象範囲内の各テーブルは独立したものとして扱います。テーブル同士は識別情報を共有したり関連性を持たないため、あるテーブルにレコードが存在する（または存在しない）という事実だけでは、別のテーブルについて何も言えません。
テーブル検索スキル（「テーブルを見つける」）の手順に従い、どのテーブルを対象にするかを決めるか、t_... 形式のテーブルIDを直接指定します。{id} はユーザーが入力した識別情報です（メールアドレス、HubSpot ID、行ID など）。
{id} が既に r_... 形式の行IDで、テーブルが判明している場合は、検索をスキップしてステップ4の行取得に直接進みます。
対象範囲内の各テーブルについて、以下の作業を行います：
clay tables columns list <tableId> — このタイプの識別情報を含むカラムをカラム名で照合して見つけます（メールアドレスなら Email、HubSpot IDなら HSID/HubSpot ID など）。f_id → name のマッピングをキャッシュし、カラムのタイプを記録します。値でフィルタリングするカラムは basic タイプである必要があります。複数のカラムが当てはまる可能性がある、または該当するカラムがない場合は、カラムの一覧を示して、どのカラムで検索するか確認します。
clay tables get <tableId> — archive の情報を読み込みます。archive が空でない場合は、archive.searchableFieldFormula（{{f_xxx}} 形式）をカラム一覧から対応するカラムに解決します。その識別情報がそのインデックス済みカラムの値である場合のみ、アーカイブの検索を計画してください。そうでない場合、このアーカイブはその識別情報では検索できません。
アクティブテーブル（通常運用中のテーブル）が queryEnabled の場合、tables query でレコードを探してください — サーバー側のフィルタリングがより柔軟（contains や大文字小文字を区別しないマッチング）で拡張性も高いため、クエリが有効な場合の主要な方法です。検索結果には、一致した各行の全セルの内容（値、fields、status、error メッセージなど）が含まれます。これ自体が状態確認用のスナップショットになるため、続く呼び出しは不要です：
echo '{"tables":[{"id":"t_abc123"}],"filter":{"field":"f_abc123","op":"contains","value":"jane@acme.com"}}' | clay tables query --query - | jq .
そうでない場合は、clay tables rows list を識別情報カラムに対する値フィルタで使用します（詳細はコマンドの --help を参照）：
clay tables rows list <tableId> --filter f_abc123="jane@acme.com" | jq .
rows list --filter は完全一致であり、大文字小文字を区別します。結果が空（{ "data": [] }）の場合、予測可能な代案（メールアドレス・ドメインは小文字、空白をトリム、サンプル行に合わせた大文字小文字）を1回だけ試して、その後は推測をやめてください — そのテーブルでは見つからなかったことを伝え、ユーザーに正確なスペルと大文字小文字の確認を促します。
常に識別情報で検索してください。位置（順番）では検索しないでください。rows list が返す行の順序は、Clay アプリ上に表示される順序とは異なるため、出力の「3番目の行」はユーザーが画面で見ている内容とは何の関係もありません。
アーカイブが適用される場合（ステップ2）、rows list でアーカイブを検索してください — アーカイブは決して queryEnabled ではないため、tables query は使用できません。また、固定の f_archive_index カラムでのみ検索可能です。インデックス値でフィルタリングします（フィルタ1つ、ページは上限1、カーソルなし。255文字を超える値は拒否されるため、最初の255文字を渡してください）：
clay tables rows list <archiveTableId> --filter f_archive_index="jane@acme.com" | jq .
レート制限を守ってください — 小グループでまとめて処理し、終了コード4では控えめに対応します。
スナップショット用に、各セルの status（および値またはエラー）をキャプチャしてください。tables query の結果には既に fields と完全な error メッセージが含まれています。rows list の場合、アクションセルは fields: null と短縮されたエラーラベルを表示します — 詳細内容はステップ4で取得してください。（rows list / rows get には行の id と updatedAt も含まれますが、tables query には含まれません。）
tables query で検索した場合は、ステップ3で既に完全なスナップショットを取得しているため、このステップをスキップしてください。rows list の場合は、以下の条件で clay tables rows get をフォローアップします：
error 状態 — 完全な error メッセージが必要です（リストは短縮ラベルのみ）。またはfields（構造化されたアクション出力）は rows get でのみ取得されます。clay tables rows get <tableId> <rowId> | jq '.cells | to_entries | map({col: .key, status: .value.status, value: .value.value, err: .value.error})'
ステップ2で取得したマッピングを使用して、col IDをカラム名に変換します。（err はエラーメッセージ文字列で、error ステータスのセルにのみ存在します。）
どこにあるか、全体的な状態を最初に示し、アクション・派生カラムをステータス付きでリストアップします（必要に応じて値またはエラーも含める）。各テーブルをアクティブかアーカイブかラベル付けしてください。ステータスをグループ化して、スナップショットが一目でわかるようにします。
r_ 行IDは内部用の識別子であり、レポートには含めないでください — ビジネス上の識別情報でレコードを見つけているため、まずそれを示してください。r_ IDは既に手元にある場合（rows list / rows get を実行した場合）にのみ表示します。updatedAt も tables query の出力には含まれないため、以下のような場合のみ識別情報で rows list --filter を1回実行して取得してください — アクティブとアーカイブの比較時、またはユーザーがデータの鮮度について質問した時。その他の場合は省略します。
Lead Enrichment — archive (updated 2026-04-10):
Find Email success → "jane@acme.com"
Enrich Person success → {name, title, company}
Push HubSpot success
Account Match — active (updated 2026-04-12):
Match Account queued
Map Fields empty
アクティブとアーカイブ両方で見つかった → おそらく再処理済み。updatedAt を比較して、どちらが新しいかを示してください。
対象範囲のテーブルで見つからない → はっきり述べてください。別のテーブルに存在する可能性もありますし、識別情報が正確でない可能性もあります。あるテーブルに存在しないという事実を、別のテーブルについての証拠として使用しないでください。
ユーザーが理由を知りたがっている error や予外の・空の値 → ここがこのスキルの終わりであり、/tables-value-trace の出番です。
特定のセルがエラーになった理由、空だった理由、実行されなかった理由、またはその値を持つ理由を説明する → /tables-value-trace。
テーブル全体の障害（単一レコードではなく） → /tables-error-sweep。
「ここにはなく、何も追加されていない」という状態 → /tables-capacity。
Use when: you have an identifier and want to find the record and see its overall state — "trace 12345", "where is jane@acme.com?", "what enrichments ran for this lead?", "is this record done?". This is a locate + snapshot: which table(s) hold it, and each cell's status. It does not explain why a cell holds what it holds — that's /tables-value-trace.
Treat each in-scope table independently. Tables may not share identifiers or have any relationship; presence (or absence) in one says nothing about another.
Resolve which table(s) to look in as in the tables entry-point skill ("Finding a table"), or pass a t_... id directly. {id} is whatever the user gave (email, HubSpot ID, row id, etc.).
If {id} is already a r_... row id and the table is known, skip discovery and go straight to get the row (step 4).
For each in-scope table:
clay tables columns list <tableId> — find the column that holds this kind of identifier by matching names (Email for an email, HSID/HubSpot ID for a HubSpot id, etc.). Cache the f_id → name map and note column types. The match column must be basic to value-filter on it. If several columns could match, or none does, show the columns and ask which to search.clay tables get <tableId> — read archive. If archive is non-null, resolve archive.searchableFieldFormula (a {{f_xxx}}) to its column via the columns list. Plan to search the archive only if {id} is the value of that indexed column; otherwise the archive isn't searchable by this identifier.If the active table is queryEnabled, locate the record with tables query — its server-side filter is more forgiving (contains, case-insensitive matching) and scales, so it's the primary tool when query is on. The result carries each matching row's full cell content — value, fields, status, and any error message — so it doubles as the state snapshot; no follow-up call needed:
echo '{"tables":[{"id":"t_abc123"}],"filter":{"field":"f_abc123","op":"contains","value":"jane@acme.com"}}' | clay tables query --query - | jq .
Otherwise, use clay tables rows list with a value filter on the identifier column (shape in the command's --help):
clay tables rows list <tableId> --filter f_abc123="jane@acme.com" | jq .
rows list --filter is exact match, case-sensitive. If it comes back empty ({ "data": [] }), retry once with a single predictable variant (lowercase for emails/domains, trim whitespace, or the casing a row sample shows), then stop guessing — say it wasn't found in this table and ask the user to confirm exact spelling/casing.
Always locate by identifier, never by position: the order rows list returns rows in is not the order they appear in the Clay app, so "the 3rd row" in the output tells you nothing about what the user sees on screen.
Where the archive applies (step 2), search it with rows list — archives are never query-enabled, so tables query is not an option; they're searchable only on the fixed f_archive_index column. Filter it by its indexed value (single filter; single capped page, no cursor; values over 255 characters are rejected — pass the first 255):
clay tables rows list <archiveTableId> --filter f_archive_index="jane@acme.com" | jq .
Respect the rate limits — batch in small groups, back off on exit 4.
Capture each cell's status (and value or error) for the snapshot. A tables query result already includes fields and full error messages. On the rows list path, action cells show fields: null and abbreviated error labels — get the full detail in step 4. (rows list / rows get also carry the row's id and updatedAt, which tables query does not.)
If you located via tables query, you already have the full snapshot from step 3 — skip this. On the rows list path, follow up with clay tables rows get when:
error — you need the full error message (list only carries an abbreviated label), orfields (structured action output) is only populated on rows get.clay tables rows get <tableId> <rowId> | jq '.cells | to_entries | map({col: .key, status: .value.status, value: .value.value, err: .value.error})'
Map col ids to names from step 2. (err is the message string, present only on error cells.)
Lead with where it is and its overall state; list action/derived columns with status (and value or error where useful). Label each table active vs archive. Group statuses so the snapshot reads at a glance.
The r_ row id is an internal handle, not a report field — you found the record by its business identifier, so lead with that; only show a r_ id when you already have one (the rows list / rows get path). updatedAt isn't in tables query output either, so fetch it with a single rows list --filter on the identifier only when freshness matters — the active-vs-archive comparison below, or the user asking how recent the data is. Otherwise omit it.
Lead Enrichment — archive (updated 2026-04-10):
Find Email success → "jane@acme.com"
Enrich Person success → {name, title, company}
Push HubSpot success
Account Match — active (updated 2026-04-12):
Match Account queued
Map Fields empty
updatedAt and say which is newer.error or surprising/empty value the user wants explained → that's where this skill ends and /tables-value-trace begins./tables-value-trace./tables-error-sweep./tables-capacity.原文・著作権は Anthropic および各プラグイン作者に帰属します。日本語訳は Claude API による自動翻訳です。