work について
HubSpot Work のコマンドラインインターフェースで、プロジェクトのトラッカー、ドキュメント、自動化を確認・更新するスキルです。変更前にテーブルのスキーマと権限を確認し、レコード更新や完了処理をプレビューできます。
主な機能
- 01ワークスペースとプロジェクトの参照
- 02テーブルスキーマとレコードの確認
- 03プロジェクト文書とエージェントの閲覧
- 04レコードの作成、更新、完了
- 05書き込みのプレビューと権限確認
活用シーン
- 01プロジェクトの計画、状況、自動化の把握
- 02テーブルの項目と完了値の特定
- 03プレビュー後のレコード更新や完了
インストール
コマンドをコピーしてターミナルで実行します。
npx skills add https:/ / github.com/ hubspot/ agent-cli-skills --skill workインストール後、Claude Code で/workを入力して読み込まれたか確認します。
詳細
HubSpot Work
hubspot work --help と各コマンドの --help には、フラグ、入力行、出力形式が記載されており、常に最新の状態に保たれています。コマンドが引数を拒否した場合は、--help に正確な形式が表示されます。多くのコマンドでは、フラグではなく ID 自体を引数として指定します(tables get 7-123 など)。このスキルでは、何を操作しているのか、なぜそれが重要なのかを説明します。これにより、「Pat がローンチボードで完了したものをすべてクローズして」という依頼を、適切な読み取り、適切な書き込み、そして相手に伝えるべきことへと結び付けられます。
| 知りたいこと、または変更したいこと | コマンド(位置引数の ID は大文字で表記) |
|---|---|
| 各項目の場所 | projects list、projects get PROJECT_ID(そのテーブルとエージェント)、workspaces list |
| 相手がどのテーブルを指しているか | tables search --query WORDS、tables list --project ID |
| テーブルの列、オプション、グループ | tables get TABLE_ID。オプションの一覧が長い場合は tables options TABLE_ID --column NAME |
| テーブルに含まれる内容 | records search --table ID(--filter、--group、--parent を指定できます。フィルター構文は --help に記載されています)、records get --table ID RECORD_ID |
| レコード上のやり取り | comments list --table ID --record ID |
| 計画と決定事項 | docs list --project ID、docs get DOCUMENT_ID |
| 自動で実行される処理 | agents list --project ID、agents get AGENT_ID |
| 特定の人物 | users search --query NAME --table ID、「自分」は hubspot whoami |
| レコードの変更 | records create/records update --table ID(JSONL)、records complete --table ID RECORD_ID...、comments create --table ID --record ID --message TEXT |
Work とは
Work は HubSpot のプロジェクト管理製品です。チームの計画、トラッカー、それらに関連する自動化が CRM の隣にまとめられています。パブリックベータ版のため、アカウントによってはまだ利用できない場合があります。
Workspace a team's area ("Marketing Ops") and its sharing
└── Project one initiative ("Q3 launch"): its tables, documents and agents
├── Table (7-123) a typed tracker; each row is a record
│ ├── Item a row, in one group
│ │ └── Subitem a child row of one item, with its own columns
│ └── Group a bucket of items: a phase, a week, a board column
├── Document the project's written context: briefs, plans, notes
└── Agent automation for the project: a goal plus the workflows that pursue it
- ワークスペースとプロジェクトは、単なるフォルダーではなく、人々が情報を整理するためのものです。 プロジェクトには、チームが取り組みごとのトラッカー、文書化された計画、自動化をまとめて保管します。「ローンチの状況は?」と聞かれた場合、答えはプロジェクトのテーブル(ステータス)、ドキュメント(意図と決定事項)、エージェント(自動実行される処理)に分散しています。要約する前に、3 つすべてを確認してください。
- テーブルは、チームが設計したトラッカーです。 列、オプション、グループの意味は、そのチームが決めています。「完了」を「出荷済み」や「クローズ済み」というオプションで表す場合もあれば、「ブロック中」をステータスのオプションまたはグループで表す場合もあります。また、「担当者」が担当者列の場合も、独自のラベルが付いた人型列の場合もあります。解釈、フィルター、書き込みを行う前に、テーブルのスキーマ(
tables get)を確認してください。ラベルから内部名を推測してはいけません。 - どのオプションを完了とみなすかは、テーブルの設定で決まります。 チームによっては「公開済み」を完了とみなし、「下書き完了」は完了とみなしません。どれが該当するかは
tables getで確認できます。ステータス列のオプションにはisDoneがあり、doneValueはrecords completeが書き込む値です。「完了」の件数を数えたり、フィルターしたり、報告したりする際は、ラベルの印象ではなく、この値を基準にしてください。 - グループとステータスは別のものです。 グループは項目が配置されている場所(フェーズ、スプリント、ボードの列)で、ステータスは列の値です。進捗を示すために項目をグループ間で移動するチームもあれば、ステータスだけを変更するチームもあります。どちらを指しているか判断する前に、このテーブルが実際にどのように使われているかを、グループといくつかのレコードから確認してください。
- サブアイテムには独自のスキーマがあります。 テーブルのサブアイテムには、アイテムの列とは別に独自の列(
subitemColumns)があります。サブアイテムは必ず 1 つのアイテムに属し、独自のグループはありません。 - エージェントは、プロジェクトの自動化を担います。 エージェントには目標と指示があり、テーブルイベント(アイテムの作成、列の変更、アイテムのグループ間移動、日付の到来、スケジュール)をトリガーとするワークフローを通じて実行されます。
agents getには、各ワークフローのトリガーと処理内容、有効かどうか、HubSpot(ユーザーではありません)が一時停止した場合のpausedBecauseが表示されます。Work の自動化は Work エージェント上にあり、CRM ワークフローにはありません。
値、ラベル、ID
読み取りのたびに、レコードの 2 つのビューが得られます。values は Work に保存されている値(選択肢の値、ユーザー ID、エポックミリ秒で表された日付)であり、書き込み時にそのまま受け付けられる値です。labels は画面上で人が目にする表示です。判断や書き込みには values を使い、人に説明するときは labels を使ってください。値を入れる場所にラベルを書き込むと、失敗するか、さらに悪い場合は誰のフィルターにも一致しないテキストが保存されます。
同じ区別はあらゆる場所に当てはまります。列の name(work_col_3)とラベル(「期日」)、選択肢の value とラベル、グループの name(group_1)とラベルです。7-123(テーブル)のような ID は安定した識別子ですが、名前は一意ではなく、変更されることもあります。
人はユーザー ID で指定します。所有者、担当者などの人を指定する列や、comments create --mention には、users search で取得した HubSpot ユーザー ID を使います。人は、そのレコードを開ける場合にのみ有用です。そのため、担当者を割り当てるときは、そのテーブルに絞って検索してください。テーブルを表示できない担当者も警告付きで保存されますが、テーブルを共有してもらうまではレコードを開けません。1 人だけを保持する人の列では、現在の人が置き換えられます。追加する人だけでなく、レコードから外すことになる人も伝えてください。
hasWorkAccess: false は、その人がこのアカウントで Work にまったくアクセスできないことを意味します。
アクセスと見つからない場合
すべての work コマンドは、hubspot auth login を実行した人の Work アクセス権で実行されます。その人に見えるものがあなたに見えるものであり、書き込んだ内容は HubSpot Agent CLI を通じてその人のものとして記録されます。レコードを「自分のもの」または「自分に割り当てられている」と呼ぶ前に、誰として実行しているのか(hubspot whoami)を確認してください。サービスキーは意図的に拒否されます。Work のすべての読み取りと書き込みは、1 人のアクセス権に照らして確認されます。
- 見つからないからといって、存在しないとは限りません。 その人が表示できないテーブル、プロジェクト、レコードは結果から除外され、テーブル検索はあいまい検索です。「テーブル X はありません」ではなく、「表示できる範囲では、X というテーブルが見つかりませんでした」と伝え、別の語で検索するか、プロジェクトを参照する方法を提案してください。一覧が不完全な場合は、stderr の注記で示されます。
- エラーには対処方法が記されています。 拒否された理由はエラーメッセージに示されます。アカウントにまだ HubSpot Work がない場合(Product Updates のベータ版へのリンクが示されるので、そのリンクを共有してください)、ログインに Work の読み取りまたは書き込み権限がない場合(
hubspot auth login --forceを実行して権限を付与してください)、またはその人がワークスペース、プロジェクト、テーブルにアクセスできない場合(共有できるのは所有者だけです)です。対処方法を伝えてください。再試行したり、回避策を試したりしないでください。 - コメントでは追加の権限チェックが行われます。 その人がテーブルを表示できれば、レコードの読み取りや編集はすぐにできます。一方、コメントは HubSpot のコメントサービスを経由するため、作成されたばかりのテーブルが認識されるまで 1~2 分かかることがあります。その人が明らかにアクセスできるテーブルでコメントが拒否された場合、通常はこの遅延が原因です。権限の問題と判断する前に、1 分待ってから再試行してください。
書き込みは人々の目に触れます
Work テーブルは、チームで共有するリアルタイムデータです。変更はテーブルを閲覧できる全員にすぐ表示され、レコードのアクティビティに記録され、ほかの処理を開始することがあります。
- 書き込みによって自動化が実行されることがあります。 アイテムの作成、列の変更、アイテムのグループ間の移動によって、エージェントのワークフロー(通知、新しいサブアイテム、別のレコードの更新、CRM への書き込み)が実行されることがあります。一括変更の前に、プロジェクトのエージェントを確認して、その変更が何を開始するかを把握し、担当者に伝えてください。
- メンションと割り当ては相手に届きます。
--mentionを付けたコメントはその人に通知され、誰かに割り当てられたアイテムは、すべてのプロジェクトを横断したその人の My work リストに表示されます。コメントは相手が読んでどう感じるかを考えて書き、依頼されていない人にメンションしたり、割り当てたりしないでください。 - CLI からコメントを元に戻すことはできません。 ここではコメントもレコードも編集・削除できません。何かを削除するには、レコードの
urlを相手に送り、HubSpot で操作してもらってください。
そのため、records update と records complete では、最初にプレビューが必要です。--dry-run を実行すると、各レコードの現在値と変更後の値が表示され、ダイジェストが生成されます。そのダイジェストを使って適用すると、すべてのレコードが再確認されます。その間にチームメイトがレコードを編集していた場合、適用は拒否されるため、もう一度プレビューしてください。プレビューは本来の目的に沿って使ってください。変更内容を(ラベルと件数を含めて)相手に示し、依頼どおりであることを確認してから適用します。依頼の範囲が広い場合(「すべて完了にする」「Pat のアイテムをすべて移動する」など)は、変更する前に、たとえば該当レコードのサンプルを確認して、フィルターが意図に合っていることを確かめてください。
検索と閲覧
- 相手が指定したものを起点にします。
tables searchは、相手が閲覧できるすべてのプロジェクトから、名前に含まれる語句でテーブルを検索します。相手がプロジェクト名を指定した場合やテーブル名が分からない場合は、projects listとprojects getで参照できます。projects getはプロジェクトのテーブルとエージェントを一度に返し、docs listはそのプロジェクトのドキュメントを返します。 - 検索する前にテーブルの内容を確認します。
tables getを使うと、ステータス、期限、担当者がどの列にあるか、各選択肢の値、存在するグループが分かります。そのうえで、ラベルではなく保存済みの値で絞り込みます(--filter)。 - 書き込めない列や、一部しか表示されない選択肢リストがあります。
readOnlyとマークされた列(システムフィールド、計算値、ロールアップ、編集不可の参照)は書き込みを拒否するため、編集を計画しないでください。代わりに参照元を変更するか、相手に伝えてください。列のoptionsSourceがPAGEDまたはEXTERNAL(担当者、ユーザー、人物、パイプラインのステージ)の場合、tables getには選択肢の一部しか表示されないか、まったく表示されません。tables optionsを使うと、全リストをページ分割して検索でき、書き込みに使う各選択肢のvalueと、伝える際に使うlabelが得られます。 - 要約する前に、すべてを読み取ります。 リスト、検索結果、ドキュメントは一度に1ページずつ返され、デフォルトの jsonl 出力には行だけが表示されるため、途中で切れたページも完全に見えてしまうことがあります。件数、「期限超過のものはない」という確認、計画の要約など、全件を把握する必要がある場合は、
--format jsonで読み込み、meta.nextが null になるまで--afterを使って続きのページを取得してください。 - 何を読み取ったかを伝え、推測にはその旨を示します。 「ローンチメールは Blocked」はデータにある事実ですが、「つまりローンチが遅れる」はそのデータに対する解釈です。事実と推測を分けることで、相手は事実を信頼し、推測を判断できます。
- 元の情報へリンクします。 レコード、テーブル、ドキュメント、エージェントには
urlが付いています。見つけた情報や変更した内容へのリンクを相手に共有すれば、HubSpot で確認できます。
書き込み
- 依頼された箇所だけを編集します。 更新する各行は、レコードの
idとrecordTypeに、変更するvaluesだけを加えて作成します。含めなかったフィールドの値はそのまま保持されます。レコードの行全体を返すと、変更するつもりのなかったフィールドまで書き換えてしまいます。 - 新しい項目には配置場所が必要です。 新しい項目にはグループが必要です(相手が指定したグループを選び、指定がなければテーブルの最初のグループを選びます)。新しいサブ項目には親項目が必要です。
- 完了の扱いはテーブルの定義に従います。
records completeは各テーブル独自の完了ステータスを設定するため、自分でステータス値を書き込むよりこちらを優先します。 - 1 回の呼び出しで最大 100 件のレコードを処理できます。 それを超える変更はバッチに分け、各バッチをプレビューして、進捗を分かりやすく報告します。
- 書き込み結果のレポートを確認します。 書き込みの結果として、更新後のレコードに加え、
skipped(すでにその状態で、変更なし)とwarnings(テーブルを閲覧できない担当者がいる場合など)が返されます。どちらについても相手に伝えます。
対象外
連絡先、企業、取引、チケット、CRM タスクは、それぞれ専用のスキルを持つ CRM レコードです。Work テーブルの関連付け列を通じてこれらにリンクできる場合もあります。CRM のワークフローは Work エージェントとは別の製品です。HubSpot の開発者プロジェクト(hs project)は Work のプロジェクトとは無関係です。