mcpField
W
work

work

github.com/hubspot生産性29115 回インストール3 週間前に更新
リポジトリ

work について

HubSpot Work のコマンドラインインターフェースで、プロジェクトのトラッカー、ドキュメント、自動化を確認・更新するスキルです。変更前にテーブルのスキーマと権限を確認し、レコード更新や完了処理をプレビューできます。

主な機能

  1. 01ワークスペースとプロジェクトの参照
  2. 02テーブルスキーマとレコードの確認
  3. 03プロジェクト文書とエージェントの閲覧
  4. 04レコードの作成、更新、完了
  5. 05書き込みのプレビューと権限確認

活用シーン

  1. 01プロジェクトの計画、状況、自動化の把握
  2. 02テーブルの項目と完了値の特定
  3. 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 のプロジェクトとは無関係です。

コメント