cargo

██████    ████    █████    ██████   ██████
██    ░  ██  ██░  ██  ██   ██    ░  ██  ██░
██       ██████░  █████ ░  ██ ███   ██  ██░
██       ██  ██░  ██ ██    ██  ██░  ██  ██░
██████   ██  ██░  ██  ██   ██████░  ██████░
 ░░░░░░   ░░  ░░   ░░  ░░   ░░░░░░   ░░░░░░

Cargo CLI — スキルの概要

このリポジトリには、リポジトリのルートに19個のスキルがあります。内訳は、このルーター（cargo）、1つのオンボーディングスキル（cargo-quickstart）、1つの成果スキル（cargo-gtm）、16個の機能スキルです。

• cargo-quickstart — 初回実行をガイドするデモです。新しいワークスペースから、2分以内に実際の成果物（ユーザーのペルソナに合った25件のリードと、費用の明細）を作成し、最後にデモを繰り返し実行できるプレイとして保存します。新規ユーザー、デモやツアーの依頼、空のワークスペースで読み込みます。
• cargo-gtm — アプリケーションライブラリです。あらゆるGTMタスク（「TAMリストを作成する」「フィンテック企業のCTOを5人見つける」「転職を監視する」など）の窓口です。内部レシピ（../cargo-gtm/recipes/*.md）とプロバイダーのプレイブック（../cargo-gtm/provider-playbooks/*.md）を介してルーティングします。
• 機能スキル — 標準ライブラリです。CLI の各ドメイン（オーケストレーション、ストレージ、セグメンテーション、接続、AI、コンテンツ、コンテキスト、分析、課金、オブザーバビリティ、ホスティング、プロジェクト、メールボックス管理、ワークスペース管理）に1つずつあり、これに加えて、実行、バッチ、クレジット消費を複数のドメインにまたがって調査する cargo-diagnostics と、ホスト型MCPサーバー（CLIではない唯一のインターフェース）である cargo-mcp があります。cargo-gtm によって読み込まれるほか、特定のCLIドメインが必要な場合は直接読み込めます。
• cargo-project — 宣言型のスキルです。他の機能スキルが一度限りの命令型の cargo-ai <domain> 呼び出しをラップするのに対し、cargo-project はプロジェクト（cargo.json を格納するフォルダー）にワークスペース全体を宣言し（define* ビルダー + cargo-ai project deploy）、その状態を調整します。あらゆる種類のリソースに対応します。命令型スキルとの使い分けについては、以下の「宣言型と命令型」を参照してください。

cargo-gtm は機能スキルに処理を委任します。機能スキルから cargo-gtm を参照することはありません（依存関係は一方向です）。

用語集： 用語ごとの定義（UUID、スラッグ、conjonction、実行／バッチ／プレイ／ツール、シグナル／ペルソナ／ICPなど）については、references/glossary.md を参照してください。

インタラクションの規約： いつ停止して確認するか（構築前の計画確認、推奨されるデフォルトの選択）と、結果の提示方法（状況を説明して要約し、生のJSONをそのまま出力しない）に関するパック全体のデフォルト設定については、references/interaction.md を参照してください。

インストール

npm install -g @cargo-ai/cli

# Recommended: emailed code, no browser at any point.
# Creates the account and a workspace on first use — there is no separate sign-up step.
cargo-ai login --email [email protected]            # sends the code, then exits
cargo-ai login --email [email protected] --code 123456

# Alternatives
cargo-ai login --oauth                            # browser sign-in (OAuth device flow)
cargo-ai login --agentid                          # an agent signing in as itself, through AgentID
cargo-ai login --token <your-api-token>           # existing workspace-scoped API token (CI)

# Optional: pick the workspace at login instead of being prompted
cargo-ai login --email [email protected] --workspace-name "Acme GTM"

# Verify
cargo-ai whoami

登録する前に確認できます。 アカウントがなくても、cargo-ai orchestration action list <keywords>、connection integration list|get、orchestration action execute … --dry-run（コネクターとネイティブアクションの場合：--data を検証し、クレジット料金とともに、実行完了時の形式でサンプル出力を表示します。呼び出しは行いません）は公開カタログに対して実行できます。project plan と project types も同様です。

**新規アカウントには100クレジットが無料で付与され、カードも不要です。**そのため、エージェントはユーザーを登録させ、同じターン内に実際の成果物を作成できます。インストールから最初の価値を得るまでに、購入の手続きはありません。クレジットで実行できることの目安は、リードの情報源調査が約500件（salesNavigator.searchLeads、1件あたり0.2クレジット）、プロフィールと確認済みメールアドレスのエンリッチメントが約1,000件（aiArk.enrichPerson、0.1クレジット）、メールアドレスの検証が約1,000件（waterfall.verifyEmail、0.1クレジット）、完全なエンリッチメントを行った連絡先が約50件（waterfall.enrichContact、2クレジット）です。クイックスタートのデモで使うクレジットは約 5 です。新規アカウントで最初の有料呼び出しを行う前に、無料残高を必ず明示してください。

エージェントまたはサンドボックスのシェルでは、--email を使用してください。ブラウザーが開くことはありません。また、入力を求めるターミナルがない場合、最初の呼び出しではコードを送信して終了するため、--code を付けて再実行します。コードをシェルの履歴に残さないようにするには、標準入力で渡してください：echo 123456 | cargo-ai login --email [email protected] --code -。すでにアカウントがあるメールアドレスでサインインすると、新しいアカウントを作成せず、既存のワークスペースが選択されるため、何度実行しても安全です。

最初のサインイン時に、Personal という名前のワークスペースが作成されます（スターターコネクター、データセット、ツール、エージェントがバックグラウンドで追加されます。新しいワークスペースは、しばらくの間、実際より中身が少なく見えることがあります）。--workspace-name <name> を指定すると、同じ名前のワークスペースがあれば（大文字と小文字を区別せず）それを再利用します。なければ、そのアカウントのワークスペースが1つだけで、作成から10分以内であり、メンバーが自分だけの場合に限り、その Personal ワークスペースの名前を変更します。いずれの条件も満たさない場合にのみ、新しいワークスペースを作成します。そのため、新しいアカウントで login --email … --workspace-name "Acme GTM" を実行すると、ワークスペースは2つではなく1つになります。

--oauth は従来どおり同じOAuth 2.0 Device Authorization Flowを実行し、引き続き検証URLにアクセスする人間が必要です。--agentid はエージェントを独自のIDでサインインさせます。AgentID接続用のAuth0 URLを表示し、http://127.0.0.1:52701/callback で待機します（タイムアウトは5分です）。URLを開くのは1回だけにしてください（2回目にアクセスすると、別のサインインが開始されます）。AgentIDの案内に従ってトークンを承認してください（コマンド名は cargo-ai login --help に記載されています）。--email、--oauth、--agentid はいずれも、自己更新されるセッションを ~/.config/cargo-ai/credentials.json に保存します（ホームディレクトリに書き込めない場合はシステムの一時ディレクトリに保存され、サンドボックスが存続する間有効です）。CIでは、Settings > APIで発行したワークスペーススコープのトークンを使って --token を指定してください。トークンの値はシークレットマネージャーに保存してください（token list は自分のトークンの値も返すため、その出力は秘密情報として扱ってください）。

グローバルインストールを行わない場合は、すべてのコマンドで cargo-ai の代わりに npx @cargo-ai/cli を先頭に付けてください。

これらのスキルは、Claude Code、Codex、Cursor向けのネイティブなエージェントプラグインとしてもインストールできます（1つのリポジトリで3つの対象に対応）。プラグインを使うと、同じスキルに加えて、承認フックとセッションライフサイクルフックもまとめてインストールされるため、別のインストーラーは不要です。対象ごとのインストール手順はリポジトリの README.md を参照してください。利用する方法はどちらか1つにしてください。プラグインか skills add のいずれかであり、両方を使ってはいけません（すべてのスキルが重複します）。

すべてのコマンドはJSONを標準出力に出力します。コマンドが失敗すると、ゼロ以外の終了コードを返し、{"error": "...", "status": ..., "body": {...}} を標準エラーに出力します（API独自の errorMessage は body の中にあります）。各機能スキルからリンクされている、セットアップ全般の規約（トークンスコープ、非同期ポーリング、管理者専用コマンド）については、references/prerequisites.md を参照してください。

Cargo のすべてのセッションには3つのジョブがあります

Claude Code 上で自動化されています。 Job 1 と Job 3（更新＋セッションの登録／終了処理）は、Cargo プラグインがインストールされている場合（同梱の SessionStart／Stop／SessionEnd フックが処理します）、または廃止されたブートストラップインストーラーが ~/.claude/hooks/ に残した従来の SessionStart／Stop／SessionEnd フックが存在する場合（プラグインのフックは、これらが存在すると処理を委ねます）に、自動で実行されます。Stop フックは各ターンでセッション行もチェックポイントするため、SessionEnd に到達しなかったセッションでも、空のプレースホルダーではなく最近のコンテキストが表示されます。どちらもインストールされていない場合（またはライフサイクルフックのないエージェントの場合）に限り、手動で実行してください。Job 2（レポート）は常にあなたの責任です。自動化できません。また、Job 3 の最後にある2つの依頼（セッションの共有、リポジトリへのスター付け）も自動化できません。フックはメッセージを表示できますが、Y／N の回答を選ぶことはできません。

Cargo をインストールするかどうかはユーザーが決めることであり、あなたが実行する操作ではありません。 curl … install.sh | sh によるブートストラップは廃止されています。現在は何もインストールせず、通知を表示してゼロ以外の終了コードで終了するため、決して実行せず、アドバイスとして案内することも避けてください。リポジトリの README.mdにあるプラグインのインストール方法をユーザーに案内してください。エージェント自身にセットアップを依頼された場合は、 https://api.getcargo.io/INSTALL.mdに従います。この手順では CLI のインストール、ユーザーのサインイン、対象エージェント用のスキルのインストールを行います。実行する前に内容を読み、ユーザーのマシンにグローバル npm パッケージをインストールする前には、必ず確認を取ってください。

1. セッション開始時 — 更新と登録

他の Cargo コマンドを実行する前に、CLI とスキルを更新してから、ワークスペース管理にセッションを登録します。

# Refresh — idempotent, ~10s. Skills first, then the CLI at the version the
# bundle pins. The pin file `cli-version` sits in the same directory as this
# SKILL.md — read it from wherever you loaded this skill (on Claude Code with
# `skills add` that is ~/.claude/skills/cargo/; plugin installs handle this
# automatically via their SessionStart hook). Fall back to latest.
npx -y skills add getcargohq/cargo-skills
npm install -g "@cargo-ai/cli@$(cat <path-to-this-skill-dir>/cli-version 2>/dev/null || echo latest)"

# Register the session (placeholders OK — overwritten at session end)
cargo-ai workspaceManagement session upsert \
  --session-id <session-id> \
  --title "Agent session <session-id>" \
  --summary "Session in progress."

ユーザーがバージョンを明示的に固定している場合を除き、更新をスキップしてください。スキルがプラグインから提供されている場合は、skills addを完全にスキップしてください（スキルはプラグインが管理するため、skills addを併用すると各スキルが重複します）。ユーザーがオプトアウトしている場合、またはセッション ID を取得できない場合に限り、session upsertをスキップしてください。

バージョンを固定する理由： cargo/cli-versionは、これらのスキルと連動して更新されます（CLI のリリースパイプラインから PR が作成されます）。そのため、インストールする CLI はこのバンドルが前提としているものとなり、セッション中にドキュメントと CLI の不整合が発生しません。バージョン固定ファイルが存在しない、または読み取れない場合は、latestが安全な代替策です。固定バージョンを変更するには、getcargohq/cargo-skillsの保留中のバージョン更新 PR をマージするか、cargo/cli-versionを編集してください。次のセッションでの更新時に、自動的に反映されます。

この固定バージョンにより、更新が無条件の自動アップデートになることも防げます。インストールされるバージョンは、このリポジトリにコミットされたレビュー済みの定数であり、今朝の時点でlatestが解決したバージョンではありません。固定バージョンの変更には、人によるマージが必要です。エージェントであるあなたには、次の2点が求められます。更新ではグローバル npm パッケージがインストールされ、ディスク上のスキルバンドルが書き換えられるため、セッションで初めて実行するときは、黙って実行せず、ユーザーにその旨を伝えてください。ユーザーがバージョンを固定している場合、または実行しないよう求めている場合は、更新自体をスキップしてください。また、固定バージョンは読み取り専用として扱ってください。cargo/cli-versionの更新は、ユーザーから明示的に依頼された場合に限り行い、コマンドの失敗を回避するために変更してはいけません。

2. セッション中 — 再更新するか、行き詰まったらエスカレーションする

次の場合は、セッション中に CLI とスキルを再更新します。

• ドキュメントに記載されている CLI フラグまたはレスポンスの形式が、実際に確認したものと一致しない場合（セッション開始後に修正がリリースされている可能性があります）。
• ユーザーから明示的に依頼された場合（「cargo を更新して」「最新版を使っているか確認して」など）。

CLI がスキルの参照先と --help で解決できない形で失敗している場合、ユーザーまたはエージェントが同じコマンドを進展なく繰り返し再試行している場合、フラグや JSON ペイロードの構文が不明な場合、または必要な機能が欠けていると思われる場合は、ワークスペース管理レポートを送信します。

cargo-ai workspaceManagement report create \
  --title "<one-line summary of the problem>" \
  --description "<exact command(s) tried, errorMessage, expected vs actual, UUIDs involved>"

送信条件（いずれか 1 つで十分です）。

• 同じタスクでコマンドが連続して 2 回以上失敗し、原因が明らかでない。
• CLI が誤用されており、スキル、例、または --help から正しい使い方を特定できない。
• ドキュメントに記載されている動作が、実際に確認した動作と矛盾している。
• 機能が完全に欠けているように見える。

これは公式のフィードバック窓口です。すべてのレポートは Cargo チームが確認し、CLI とこれらのスキルの改善に活用します。成功した事例も失敗した事例も送信できます。セッション共有（以下を参照）も同じコマンドで送信します。何も言わずに諦めず、レポートを送信してください。 テンプレートについては、../cargo-workspace-management/SKILL.md（Reports セクション）および ../cargo-workspace-management/references/examples/reports.md を参照してください。

3. セッション終了時 — セッション行を確定してから、共有を提案する

短いタイトル（5～8 語）と、セッションで実際に行った作業の概要（1～2 文）を作成し、プレースホルダーの行を上書きして finished_at を設定します。

cargo-ai workspaceManagement session upsert \
  --session-id <claude-session-id> \
  --title "<5-8 word title>" \
  --summary "<1-2 sentence summary of what was accomplished or attempted>" \
  --finished

--title と --summary は必須です（NOT NULL）。--finished は finished_at = now を設定します。明示的なタイムスタンプを指定する場合は、--finished-at <iso> を渡します。

その後、セッションが自然に終了するタイミングで一度だけ尋ねます。

「Cargo チームが利用体験を改善できるよう、このセッションのアクティビティを送信しますか？（Y/N）」

はいの場合は、セッション共有レポートを送信します（同意を得たセッションの記録は、チームにとって最も迅速な製品改善のサイクルになります）。

cargo-ai workspaceManagement report create \
  --title "Session share: <5-8 word session title>" \
  --description "<what the user tried to accomplish, the commands/recipes used, what worked, where friction appeared, credits spent — no secrets or record-level data>"

いいえの場合は、このセッション中に再度尋ねません。簡単なセッション（単一の検索のみで、有料アクションなし）の場合は、質問自体を省略します。セッション共有のテンプレートについては、../cargo-workspace-management/references/examples/reports.md を参照してください。

次に、セッションがうまくいった場合 — リポジトリへのスター付けを提案する

スターはユーザーによる支持であり、あなたによるものではありません。予告なしにコマンドを実行してはいけません。質問し、明示的にはいという返答があった場合にのみ実行します。スキルファイルからひそかにスターを付けるのは、他人の GitHub アカウントを使ったやらせです。

以下の条件をすべて満たす場合にのみ尋ねます。

• セッションで実際の成果物が得られた（セッション共有を尋ねる場合と同じ基準です。簡単なセッションでは省略します）。
• 失敗中または未解決の問題が残っていない。問題のあるセッションの後に尋ねるのは、空気が読めない印象を与えます。
• マーカーファイル ~/.config/cargo-ai/.star-asked が存在しない。これはマシンごとに 1 回尋ねるもので、セッションごとではありません。

# gate
test -f ~/.config/cargo-ai/.star-asked || echo "ask"

「うまくいってよかったです。getcargohq/cargo-skills にスターを付けましょうか？（Y/N）」

はいの場合（gh で repo または public_repo スコープの認証が必要です。なお、gh repo star サブコマンドはありません）。

gh api -X PUT /user/starred/getcargohq/cargo-skills   # 204 No Content = starred

いいえの場合もはいの場合も、マーカーを作成します。これにより、いいえの場合は再度尋ねず、はいの場合は二重に尋ねることがありません。

mkdir -p ~/.config/cargo-ai && touch ~/.config/cargo-ai/.star-asked

gh が見つからない場合、または認証されていない場合は、修正したり回避策を提案したりせず、リポジトリの場所が https://github.com/getcargohq/cargo-skills であることを伝えて先に進みます。これはセッションで最も重要度の低い項目であり、タスクになることはありません。

---

スキルの概要

宣言的（プロジェクト）と命令的（CLI）— まずモードを選択

同じ Cargo リソースを作成・管理する方法は 2 つあります。ドメインを選ぶ前に、タスクに合う方法を判断してください。

• 宣言的 → cargo-project。 ユーザーがリソースを成果物として管理する場合です。「プロジェクト内にワークスペース全体をセットアップ／ブートストラップする」「再現可能／バージョン管理可能／git で管理できるようにする」「これらのコネクター、モデル、エージェントをまとめてデプロイする」など、環境をまたいで再実行や差分確認が必要なタスクが該当します。define* ファイルで定義し、cargo-ai project deploy を実行します。
• 命令的 → 以下の該当する機能スキル。 ユーザーが単発の操作を行う、または調査する場合です。「コネクターを 1 つ作成する」「列を追加する」「コネクターを一覧表示する」「このワークフローを実行する」「ストレージをクエリする」「メモリーを読む」などが該当します。コードに残す必要のない読み取り、アドホックなクエリ、または単一の変更です。

判断に迷った場合は、結果をコミットして再デプロイできる必要があるかを考えてください。必要ならプロジェクト、すばやく実行する操作や読み取りなら機能スキルです。

オンボーディングスキル

初めて利用するユーザーや、空のワークスペースで読み込みます。

スキル	次の用途で読み込みます
cargo-quickstart	ガイド付きの初回デモを実行します。ペルソナに関する質問 1 つから、2 分以内に 25 件のリードを作成し、費用の領収書を確認して、繰り返し使えるプレイとして保存します。その後、cargo-gtm に誘導します。

成果スキル

ユーザーが現実世界の目標を示したときに読み込みます。

スキル	次の用途で読み込みます
cargo-gtm (要約)	あらゆる GTM タスクに対応します。ソーシング、エンリッチメント、検証、スコアリング、シーケンス化、CRM 同期、シグナル監視（転職、資金調達、技術スタック／採用意向）などが該当します。レシピ（recipes/）、ガイド（guides/）、プロバイダー別プレイブック（provider-playbooks/）を通じて誘導します。

機能スキル

特定の CLI ドメインで読み込みます。各行の最初のリンクから実際の SKILL.md に移動し、括弧内のリンクからこのページの要約に移動します。

スキル	次のことが必要なときに読み込みます
cargo-orchestration (概要)	アクションの実行、ワークフローの実行、バッチのトリガー、エージェントとのチャット、SQL（ClickHouse）によるオーケストレーションのクエリ
cargo-analytics (概要)	実行結果のダウンロード、セグメントデータのエクスポート、エラー率とメトリクスの監視
cargo-billing (概要)	クレジット使用量の確認、サブスクリプションの詳細の表示、ワークフローまたはコネクターごとのコストの追跡
cargo-diagnostics (概要)	事後診断：ある実行で問題が起きた原因の追跡、根本原因ごとに分類したエラーをバッチ／プレイ全体で調査、プレイのクレジット使用先のプロファイリング
cargo-observability (概要)	アラートの作成と管理 — スパン／実行／レコード、モデルの健全性、または SQL クエリに対するスケジュール済みのしきい値チェックです。しきい値を超えるとアクション（コネクター／ツール／エージェントの実行）を発動します。診断のプロアクティブな対となる機能です
cargo-storage (概要)	データモデル、列、データセット、リレーションシップの確認または変更、SQL によるワークスペースストレージのクエリ
cargo-segmentation (概要)	セグメントの作成と管理 — バッチ、プレイのトリガー、またはエクスポートの対象者を指定する保存済みフィルターです。また、その変更（差分）フィードを読み取ります
cargo-connection (概要)	コネクター認証の管理、利用可能なインテグレーションとそのアクションの確認
cargo-ai (概要)	エージェントの作成と設定、リリースの設定、RAG 用ナレッジの追加、MCP サーバーとメモリの管理
cargo-content (概要)	ナレッジファイルのアップロードと整理、RAG 用のネイティブ／コネクター連携型ナレッジライブラリの構築、署名付きまたは公開リンクを使ったパス指定によるあらゆるファイルの保存／提供（content ドメイン）
cargo-context (概要)	ワークスペースの Git 管理された GTM コンテキストリポジトリの閲覧／読み取り／書き込み／編集、そのランタイムサンドボックスでのコマンド実行、ナレッジグラフの確認
cargo-hosting (概要)	ホスト型アプリ（Vite SPA）とエッジワーカー（サーバーレス HTTP ハンドラー）のひな形作成、デプロイ、昇格、それらのデプロイの管理、ワーカーへの環境変数とシークレットの付与
cargo-project (概要)	宣言型 — あらゆるリソースタイプに対応します。 プロジェクト内でワークスペース全体を宣言（define* ビルダー）し、cargo-ai project（init → types → plan → deploy）でデプロイします。GTM as Code／再現可能／バージョン管理されたセットアップに使用します。上記の「宣言型と命令型」を参照してください。
cargo-mailbox-management (概要)	Cargo が所有する送信用メールボックスのプロビジョニング、ウォームアップと 5→40/日の送信ランプの実行、sendEmail アクションによる送信、スレッド、返信、配信イベント、抑制の読み取り
cargo-workspace-management (概要)	ユーザーの招待、API トークンの作成、フォルダーの整理、ロールの管理、CLI の問題の管理チームへの報告
cargo-mcp (概要)	https://mcp.getcargo.io/mcp のホスト型 MCP サーバーから Cargo を操作し、CLI をインストールせずにクライアントを接続、アクションを確認して料金を調べ、1 件のレコードまたはバッチを実行して結果をポーリングし、モデルを読み取ります。また、MCP ツールと CLI の使い分けにも対応します

RAG 用のエージェントナレッジ： ファイルとライブラリはcontentドメインにあります → cargo-content。これらをエージェントに関連付ける方法については → cargo-ai。（ファイル／ライブラリは、CLI ≥ 1.0.19 で従来のai file …のパスから移動しました。）

これらのスキルと MCP サーバーの違い

ここでは、MCP という名前が付くものが3種類あります。 それぞれ回答が異なるため、返信する前にどれを指しているか確認してください。

	内容	スキル
ホスト型サーバー	Cargo 独自のエンドポイント https://mcp.getcargo.io/mcp です。17個の固定プラットフォームツール（検出、価格、実行、ポーリング、モデルの読み取り、コンテキストの読み取り、使用状況）を備えています。ワークスペースがキュレーションしたサーバーは、/v1/ai/mcpServers/<uuid>/mcp で別途提供されます。CLI をインストールせずに Cargo を操作する方法です。	cargo-mcp
ワークスペースサーバー	このワークスペースが公開するキュレーション済みのセット（ai mcp-server create --actions … --resources …）で、cargo-ai mcpを介して、あらゆる stdio クライアントに提供されます。	cargo-ai
エージェント MCP クライアント	Cargo エージェントに接続された、他者が提供する MCP サーバーです（release update-draft --mcp-clients）。	cargo-ai

1つ目は新しいもので、「Cargo に MCP サーバーはありますか？」という質問が現在指すのはこちらです。自身の401チャレンジから検出される OAuth、またはワークスペーススコープのベアラートークンで認証します。

claude mcp add --transport http cargo https://mcp.getcargo.io/mcp

2つ目はキュレーションの方法です。ワークスペース全体ではなく、承認済みのツールを1つ公開したい場合は、引き続きこちらが適切です。

claude mcp add cargo -- cargo-ai mcp                    # the platform MCP
claude mcp add cargo -- cargo-ai mcp --server <uuid>    # a curated server instead

--serverを指定しない場合、ブリッジはCARGO_MCP_SERVER_UUIDが設定されていればその値を使用し、そうでなければプラットフォームの/mcpを使用します。（以前の CLI では「ワークスペースにある唯一の MCP サーバー」にフォールバックし、サーバーがちょうど1つでない場合は処理に失敗していました。）

リクエストの形式に応じて、CLI とどちらかの MCP インターフェースを使い分けてください。

	これらのスキル（CLI）	MCP サーバー
内容	すべてのドメインを網羅する CLI 全体	プラットフォームのランタイムツールに加えて、ワークスペースが公開することを選んだもの
最適な用途	ワークフロー、プレイ、スキーマ変更、プロジェクトのデプロイ、診断、エクスポート、ウェアハウス SQL など、再利用可能なものを構築するあらゆる作業	会話中の実行：このレコードを検索する、このリストを拡充する、承認済みのこのツールを実行する
コスト管理	完全なパイロット → 承認 → レシートの規律（../cargo-gtm/references/cost-discipline.md）	呼び出し単位。search_actionsは各アクションの実行前にクレジットコストを返します
再現可能性	はい。コマンド、プレイ、プロジェクトファイルが成果物として残ります	いいえ。ツール呼び出しの後に成果物は残りません

目安：ユーザーが再実行やバージョン管理を望むものは、すべて CLI に含めます。 MCP ツールをレコードごとにリスト全体へ呼び出してはいけません。そのためにexecute_action_batch（および CLI のorchestration action execute-batch）があり、より低コストで、実行状況も把握できます。反対に、ワークスペースがすでにその用途のツールをキュレーションしている場合は、ロウアクションから同じものを手作業で組み立てるより、そのツールを呼び出すほうが適切です。

専用スキルがまだない CLI ドメイン

CLI には、まだ対応する機能スキルがないドメインがいくつかあります。タスクで必要な場合は直接実行し（cargo-ai <domain> --help）、機能の範囲が不明確な場合は workspaceManagement report を作成してください。

CLI ドメイン	対象
expression	テンプレート／JS 式をノード設定で記述します。eval evaluate --expression '<json>' --variables '<json>' は、サンプル変数を使って式を評価します（実行前に {{…}} を確認する最も手早い方法です）。eval generate --prompt "…" --variables '<json>' は、平易な英語の指示から式を作成します。レシピは、保存して再利用できる式です。recipe list、recipe get <uuidOrShortId> [version]、recipe create --name … --kind jsExpression|templateExpression --expression … [--instruct-to ai|none] [--placeholders '<json>']、recipe create-new-version、recipe archive <uuid> を実行できます。favorite-recipe create|delete は、ワークスペースで使う式をお気に入りに登録します。
system-of-record	ワークスペースのストレージが存在するデータウェアハウス（bigQuery または snowflake）です。sor list|get|create --kind … --config '<json>'|update|remove を実行できます。sor migrate <uuid> は、Cargo の保留中のスキーママイグレーションを順番にデータウェアハウスへ適用し、失敗した時点で停止します。sor cutover <uuid> は、バックグラウンドでテーブルをコピーし、ワークスペースをそのシステム・オブ・レコードへ移行します（各ワークスペースで同時に実行できるカットオーバーは 1 つです）。どちらも稼働中のストレージに対する管理者操作です。実行前に必ず確認してください。client query "<sql>"、client fetch、client download、client get-documentation <slug> は、データウェアハウスに直接アクセスします。log list／log get-metrics は、同期ログを読み取ります。モデルに対する日常的な SQL には、storage query execute（cargo-storage）を使用してください。
revenue-organization	営業チームのテリトリーとキャパシティを計画します。member list|get|update|archive|unarchive と member sync --connector-uuid <crm-connector>（CRM から営業担当者を取り込みます）、territory list|get|create|update|remove、capacity list|get|create|update|remove、allocation list|get|remove を実行できます。allocation は、ワークフローがレコードを営業担当者に割り当てる際に、ネイティブの allocate アクション（{"kind":"native","actionSlug":"allocate"}、「チームのメンバーを選択」）が書き込む割り当てです。
user-management	ワークスペースのコンテキストを必要としない、現在のユーザーに関する操作です。

すべてのドメインの外側にあるトップレベルコマンド

CLI のルートに、ドメイン配下ではないコマンドが 5 つあり、これらを扱うスキルはありません。 ユーザーがコマンド名を挙げたときに認識できるよう、ここに記載しています。ルーティング先ではありません。

コマンド	内容
cargo-ai doctor	セットアップを 1 つの JSON オブジェクトで診断します。インストール済みバージョンと最新バージョンの比較、skills-bundle pin、認証情報、API への到達可能性を確認します。最も重大なエラーをもとに終了します。スキルを読み始める前に「このコマンドが動かない理由」をすばやく確認できます。
cargo-ai start（エイリアス onboard）	必要に応じてユーザーをサインインさせた後、次のいずれかに進みます。コーディングエージェント（--continue claude|cursor|codex|gemini）、プロジェクトのひな形を作成する code、パレットを開く cli、またはガイド付きツアーの demo。--email／--code／--oauth、--workspace-name、--directory、--icp を指定できます。
cargo-ai ask	ターミナルでチャットします。デフォルトでは、このマシン上の Claude Code を作業ディレクトリに対して実行します（--dir）。--agent-uuid を指定すると、ワークスペースエージェントを同じローカルセッションに接続します。--print を指定すると、1 ターン分を JSON として標準出力に出力し、--continue を指定すると最後のチャットを再開します。cargo-ai --chat としても利用できます。
cargo-ai book-demo	Cargo の営業担当者とのデモを予約するため、カレンダーを開きます。--no-open を指定すると、代わりに URL を出力します。
cargo-ai（引数なし）	ターミナルが表示に対応している場合、インタラクティブなパレットを開きます。引数なしの cargo-ai project はグループのヘルプを表示します。info や init は実行しません。

これらのうち 2 つは、スキルが手順を説明している作業と重複します。doctor はピンを手動で確認するよりも先に実行するのがおすすめです。また、start --continue demo は CLI 独自の cargo-quickstart ツアーです。費用をかける範囲を自分で管理したい場合はスキルを、ユーザーがすぐに済ませたい場合はコマンドを優先してください。

---

スキルの関係

            ┌─────────────────────────────────────┐
            │              cargo-gtm              │
            │   Outcome / front door for GTM      │
            │   Recipes, guides, provider-playbks │
            └─────────────────┬───────────────────┘
                              │ delegates to ↓ (one-way)
       ┌──────────────────────┴──────────────────────┐
       │                                             │
┌──────────────────────────────────────────────────────────────┐
│              cargo-workspace-management                      │
│         Authentication, users, tokens, folders               │
└──────────────────────────────────────────────────────────────┘

  ┌─────────────────┐   ┌────────────────────┐   ┌─────────────────┐
  │  cargo-storage  │   │  cargo-connection  │   │    cargo-ai     │
  │ Models, columns,│   │ Connectors,        │   │ Agents, docs,   │
  │ datasets        │   │ integration actions│   │ MCP, memory     │
  └────────┬────────┘   └─────────┬──────────┘   └────────┬────────┘
                                              (cargo-content feeds
                                               files/libraries to agents)
           │                      │  (UUIDs flow down)    │
           └──────────────────────┼───────────────────────┘
                                  ▼
             ┌───────────────────────────────────────┐
             │          cargo-orchestration          │
             │   Runs, batches, plays, tools, SoR    │
             └───────────────┬───────────────────────┘
                             │
              ┌──────────────┴──────────────┐
              ▼                             ▼
 ┌────────────────────────┐  ┌───────────────────────────┐
 │    cargo-analytics     │  │       cargo-billing       │
 │  Results, metrics,     │  │    Credit usage, costs    │
 │  exports               │  │                           │
 └────────────────────────┘  └───────────────────────────┘

             ┌───────────────────────────────────────┐
             │             cargo-context             │
             │  Git-backed GTM markdown knowledge:   │
             │  personas, plays, proof, signals…     │
             └───────────────────────────────────────┘
           (orthogonal: not part of the workflow flow)

             ┌───────────────────────────────────────┐
             │               cargo-project               │
             │  Declarative authoring layer: define  │
             │  connectors/models/plays/agents/… as  │
             │  code, deploy with `cargo-ai project`.    │
             └───────────────────────────────────────┘
    (cross-cutting: PRODUCES the same resources the imperative
     skills manage — an alternative mode, not a workflow stage)

             ┌───────────────────────────────────────┐
             │        cargo-mailbox-management       │
             │  Sending inboxes Cargo owns: warm-up, │
             │  send ramp, threads, replies, events, │
             │  suppressions. The send itself is the │
             │  `sendEmail` orchestration action.    │
             └───────────────────────────────────────┘
   (owns the mailbox; orchestration owns the send — and every
    send is gated by cargo-gtm's acceptable-use checks)

             ┌───────────────────────────────────────┐
             │           cargo-observability         │
             │  Scheduled threshold alerts over the  │
             │  telemetry above (spans/runs/records), │
             │  a model's health, or a SQL query —    │
             │  fire actions as runs on breach.       │
             └───────────────────────────────────────┘
     (watches orchestration/storage; fires orchestration
      actions — proactive counterpart to cargo-diagnostics)

依存関係の実際のルール：

• cargo-gtm は相対パス（../cargo-orchestration/...）を使って、機能スキルに処理を委譲します。機能スキルが cargo-gtm を参照することはありません。
• cargo-workspace-management はすべてのスキルに認証コンテキストを提供します。最初に設定してください。
• cargo-storage、cargo-connection、cargo-ai は、cargo-orchestration に UUID を提供する同列のスキルです。互いに依存しません。
• cargo-content はワークスペースのファイルとライブラリ（content ドメイン）を管理します。ファイル／ライブラリの UUID を生成し、それを cargo-ai がエージェントリリースの resources（RAG）として使用します。また、ファイルストアでもあります。パスを指定して書き込みと読み込みを行い、フォルダーを一覧表示し、署名付きリンクまたは公開リンクを発行します。これは CLI、ワーカー（createCargoObjects）、プレイ（writeFile／readFile／getFileUrl ノード）、またはエージェント（書き込み可能なフォルダー）から行えます。mirrorToContext: true（アップロードと defineFile ではデフォルト、パス指定の書き込みではデフォルトではありません）のファイルは、コンテキストリポジトリの .files/ にもコミットされます。cargo-context ランタイムからは読み取り専用です。
• cargo-mailbox-management は送信用受信トレイ（mailboxManagement ドメイン）を管理します。プロビジョニング、ウォームアップ、送信ランプ、スレッド、イベント、ワークスペースの抑制リストが対象です。意図的に送信機能は提供しません。配信は cargo-orchestration のネイティブアクション sendEmail が担うため、送信には cargo-orchestration の送信間隔調整、再試行、クレジット計上が適用されます。メールボックス自体は、送信ドメイン用の defineDomain とともに defineMailbox を使ってプロジェクト内で宣言することもできます。
• cargo-project は横断的なスキルです。宣言型の作成モードであり、命令型の機能スキルが一度に 1 つずつ管理するコネクター／モデル／プレイ／エージェントなどを生成します。「プロジェクトからワークスペースを管理する」（GTM as Code：再現可能、Git 管理、複数リソース）タスクでは、cargo-project にルーティングしてください。単発の操作、読み取り、アドホックなクエリでは、命令型のドメインスキルにルーティングしてください。「スキルの概要」の「宣言型と命令型」を参照してください。
• cargo-context はワークフロー実行フローとは独立しています。ストレージやワークフローの実行ではなく、Git 管理された GTM ナレッジベース（markdown／MDX）を扱います。ペルソナ、プレイ、実績、反論、シグナルなど、ワークスペースの文章形式のコンテキストを記録／編集するときや、型付きナレッジグラフを調べるときに使用してください。
• ストレージに対する SQL クエリには、cargo-ai storage query execute "<sql>" を使用してください（テーブルは <datasetSlug>.<modelSlug> 形式です）。データセットとモデルのスラッグを確認するには cargo-storage を読み込み、列の型や SQL 方言が必要な場合は DDL を取得してください。
• オーケストレーションのランタイムテーブル（runs、batches、spans、records）に対する SQL クエリ（エラー率、ノードごとの失敗、時系列など）には、cargo-ai orchestration query execute "<sql>" を使用してください。ワークスペースのスコープは自動的に適用されます。テーブルはスキーマ接頭辞なしで参照します。
• ワークフローのノードグラフを作成する前に、cargo-connection を読み込み、connectorUuid と actionSlug を取得してください。ノードがクレジット制のプロバイダーアクションを呼び出す場合は、cargo-gtm も読み込み、そのプロバイダーのプレイブック（../cargo-gtm/provider-playbooks/<slug>.md）を確認してください。ワークフローがスケジュールされたツールまたはプレイの場合は、定期利用セクションも必ず確認してください。設定ミスや誤った実行頻度があると、実行のたびに再請求されるためです。タスクが GTM の文脈なしに cargo-orchestration または cargo-project を通じて直接届いた場合も、同様に適用されます。
• エージェントノードを使用するワークフローを実行する前に、cargo-ai を読み込み、agentUuid を取得してください。
• 実行完了後は、cargo-analytics を読み込んで結果をダウンロードするか、パフォーマンスを測定してください。アクション出力の取得には、run download よりも cargo-ai orchestration run download-outputs を優先してください。後者は、出力ノードのデータのみを含む署名付き URL の CSV／JSON を返します。
• 上記のいずれかにおけるクレジット消費を把握するには、cargo-billing を読み込んでください。
• 実行が失敗した場合、実行が「成功したが結果がおかしい」場合、バッチにエラーがある場合、またはプレイのコストが高すぎる場合は、cargo-diagnostics を読み込んでください。run get、オーケストレーション SQL、課金情報の各機能を順に使うフォレンジック実行手順（1 回の実行のトレース、バッチの一括調査、クレジット消費の分析）を提供します。
• エラー率の急上昇、コスト上限への到達、ノードの遅延、同期の停止、ワークフローの停止など、問題を調べに行く前に通知を受けたい場合は、cargo-observability を読み込んでください。これはアラートを作成します。同じテレメトリ（spans／runs／records）、モデルの健全性、または SQL クエリを対象に、スケジュールに従ってしきい値をチェックし、条件に達するとアクションを実行します。診断は事後対応（何が起きたかを説明）であり、可観測性は事前対応（問題が起きないか監視）です。アラートは defineAlert を使ってプロジェクト内で宣言することもできます。

---

スキルごとの重要なルール

各スキルで見落としやすいルール、つまり、推測で進めると気付かないまま失敗したり、費用がかかったりするポイントです。各スキルの SKILL.md に全容が記載されていますが、選ぶ前に知っておく価値のあるものを紹介します。

cargo-gtm

同梱されているレシピ：

レシピ	使用する場面…
recipes/source-planning.md	費用をかける前にソースを決めます。候補を調査し、1件あたりの費用を確認します。
recipes/prospecting.md	検索 → エンリッチ → 検証 → 同期を最初から最後まで実施します（P1/P2/P3 の各バリエーション）。
recipes/build-tam.md	Total Addressable Market のリストを大規模に作成します（100～10,000 社）。
recipes/linkedin-url-lookup.md	厳格な検証を行い、名前と会社名から LinkedIn URL を特定します。
recipes/portfolio-prospecting.md	投資家／アクセラレーター → 投資先企業 → 担当者を特定します。
recipes/job-change-monitoring.md	連絡先セグメントに対して waterfall.detectJobChange（cargo 固有）を実行します。
recipes/funding-watch.md	最近資金調達を行った企業を追跡します。
recipes/tech-intent.md	テクノロジースタックまたは採用意向のシグナルから企業を特定します。
recipes/icp-discovery.md	Closed-Won と Closed-Lost のセグメントを比較し、ICP のシグナルを見つけます。
recipes/custom-datapoints.md	実在するソースと費用を確認したうえで、収集するカスタム属性とリアルタイムシグナルを設計します。
recipes/outreach-activation.md	シグナルセグメントをすぐに送信できるアウトリーチに変換します（エンリッチ → 検証 → パーソナライズ → シーケンサーへの引き渡し）。
recipes/ads-audience-activation.md	セグメントを Google Ads Customer Match／LinkedIn Matched Audiences に送信します。
recipes/review-and-iterate.md	判断を伴う出力を人間がレビューするループです。修正内容は恒久的なルールになります。
recipes/re-engagement.md	求職先の変更、資金調達、テックインテントなどの新しいシグナルが発生した場合に限り、古い連絡先に再アプローチします。
recipes/lost-deal-revival.md	lost_reason（担当者の退職、予算、タイミング）に応じて分岐し、Closed-Lost の CRM 案件を再活性化します。
recipes/account-expansion.md	顧客アカウントで複数の担当者と関係を築きます。新規購入者を特定し、Contacts モデルとの重複を除外します。

優先プロバイダースタック（レシピではこれらを優先します）：salesNavigator（ソーシング）、aiArk（LinkedIn を基点としたエンリッチ、およびカタログ内で最も安価な企業エンリッチと検索）、waterfall（複数ソースからのエンリッチ、メール検証、求職先の変更）、FullEnrich（プレミアムな連絡先検索）、apolloio（ニッチなカバレッジ向けの 1 クレジットのエンリッチ）、theirStack（テクノロジースタックと採用意向）、peopleDataLabs（大規模なバックフィル）。すでに LinkedIn URL（またはイベント URL）をお持ちですか？ ソーシングは不要です。直接 aiArk.enrichPerson（0.1、プロフィール ＋検証済みメールアドレス、メールアドレスがない場合は 0 課金）を使うか、メールアドレスが不要な場合は linkedin（enrichProfile／enrichCompany は 0.25、extractEventAttendees）を使います。これらは URL を基点とした最安のエンリッチで、上記のスタックはソーシング優先のため見落としがちです。 重要なルール：

• 人に関わるすべての手順には、適正利用のゲートが適用されます（../cargo-gtm/references/acceptable-use.md）：ライセンスを受けたプロバイダーから取得したB2Bの業務用アイデンティティのみを使用し、アウトリーチの各手順に進む前に、無料のブロックチェック3項目（根拠、抑止リスト、関連性）を実施します。また、無差別な一斉配信、消費者を対象としたターゲティング、出所が明記されていないリスト、抑止対象レコードへの連絡、フィルターやアイデンティティの回避、自動ダイヤル、LinkedInでのエンゲージメント操作の一括送信、ユーザーのXアカウント（xAccount）からの一括または自動の投稿／返信／いいね／DMを拒否対象とします。このパックは送信を行いません。アウトリーチは、ユーザー自身のシーケンサーで使う送信準備済み変数の生成までで終了します。
• すべてのレシピはクレジット制のアクションを使用します。カタログで公開されている594件のうち190件が対象で、価格は../cargo-gtm/references/credits-cost-table.mdに記載されています。価格表はcargo-ai orchestration action list --kind connector／--kind native（無料でカタログを読み取ります）から再生成されます。これらのコマンドは、課金対象の各アクションについてcredits配列を返します。残る404件のアクションにはプロバイダー料金はありませんが、ワークフロー内で実行されるものに無料のものはありません。構造用ネイティブ（branch、filter、switch、variables）を含め、ノードの実行ごとに0.01クレジット（100回で1クレジット）が課金されます。価格表に記載されているのはアクションの料金であり、ステップの料金ではありません。../cargo-billing/SKILL.mdの「The execution charge」を参照してください。
• アクションの形式：{"kind":"connector","integrationSlug":"<slug>","actionSlug":"<slug>"}。トップレベルのアクションにconfigは指定せず、connectorUuidをその中にネストすることもありません。これはノードのトップレベルに置きます。
• 出力の取得：cargo-ai orchestration run download-outputs --output-node-slug <slug>（run downloadではありません）。
• peopleDataLabsのフィルター形式：searchXではcargoの{conjonction, groups, conditions}形式を使用します。queryXではPDLのSQL文字列を指定します。Elasticsearchは使用しません。

cargo-orchestration

重要なルール：

• action execute、run create、batch create のどれを使うべきかは、../cargo-orchestration/SKILL.md の冒頭にある判断フローチャートを参照してください。
• 初回の試行でバッチ全体を登録しないでください。 batch create／action execute-batch は、ソース内のすべてのレコードに対して処理を展開します。10～20 件のレコードをサンプルとして処理し、確認できたコストと成功率を報告してから、レコード数とクレジットの見積もりを伝えたうえで、全件の登録についてユーザーの承認を求めてください。手順：../cargo-orchestration/SKILL.md →「Create a batch」。利用ルール：../cargo-gtm/references/cost-discipline.md §1。
• アクションは検索してください。カタログを参照して探してはいけません。 cargo-ai orchestration action list <keywords> [--kind connector|native|tool|agent] [--integration-slug <slug>] [--limit 20] は、インテグレーションカタログ、Cargo のネイティブアクション、ワークスペースツール、エージェントを、無料の 1 回の呼び出しで検索できます。また、すぐに貼り付けられる action オブジェクト（connectorUuid を解決済み）と、アクションのクレジットコストを返します。これに対応する cargo-ai connection action search <keywords> はコネクターのみが対象ですが、action list にない唯一のフィルターである --credits-only を指定できます。どちらも connection integration list でページをめくるより便利です。アクションを選んで完全な入力スキーマが必要になった場合に限り、integration get <slug> を使用してください。
• action execute／action execute-batch では config を省略してください。入力は --data／--records に指定します。これは action list が返す形式で、その結果をそのまま貼り付けて使えます。action get-output-schema も同じ形式です（スキーマが入力に依存する場合は、入力を --data に指定します）。ワークフローのノード、アラートの --actions、プレイの healthAlertActions、エージェント／MCP サーバーの --actions では、引き続き config を指定します。入力を誤って config に入れると、config に関するエラーが出ないまま削除されるため、入力は処理に届きません。必須入力があるアクションは、そのフィールドがないため実行前に拒否され、必須入力がないアクションは入力なしで実行されます。入力キーの誤記や未宣言のキーは、実行の作成前に拒否されます（invalidData、Unknown field: <key>。ネストされたキーも含みます。バッチではレコードが 1 件でも不正ならバッチ全体が拒否されます）。ただし、ツールアクション、バッチのトップレベルにある余分な列、ワークフローノード内では、未知のキーは引き続き通知なく削除されます。
• 操作の実行には action execute を既定で使い、node execute はデバッグ専用としてください。 node execute を使うのは、作成中のワークフローにある単一ノードをテストする場合に限ります。このコマンドでは --workflow-uuid、--release-uuid、--node、--computed-config、--context の 5 つすべてが必要です。それ以外（レコードのエンリッチ、コネクターアクションの呼び出し、ツールやエージェントの起動）には、action execute／action execute-batch を使ってください。
• ノードグラフは、専用アクションと式をこの順番で組み合わせて構築してください。（1）orchestration action list <keywords> で最初に見つける専用アクション（コネクターアクションや、agent、modelUpsert、branch、group などのネイティブアクション）。（2）値が必要なフィールド内に直接記述する JavaScript である、つなぎ込み用の式。（3）その API に対応するアクションがない場合に限り、HTTP。（4）ロジックを式に収められない場合に限り、script／python ノード。../cargo-orchestration/references/node-selection.md を参照してください。
• ノードグラフは説明文ではなく、図で示してください。 ドラフトをデプロイする前と、ワークフローやプレイの内容をユーザーから尋ねられたときは、cargo-ai orchestration node diagram --workflow-uuid <uuid> --raw を実行してください（無料で、何も実行せず、CLI ≥ 1.0.54。references/node-diagram.md）。ルーティング、フォールバックのエッジ、課金対象となるノードは、承認の対象です。手作業で転記せず、コマンドで図を生成してください。ノードのスラッグは同じリリース内で重複するため、スラッグを基準に手描きした図では、別のノードが 1 つにまとめられてしまいます。
• フィルター JSON では、conjunction ではなく conjonction を使います。必須キーのため、誤記すると 400 エラーで拒否されます。
• オーケストレーションのランタイムテーブル（ClickHouse）を検索するには、runs、batches、spans、records に対して cargo-ai orchestration query execute "<sql>" を使います（スキーマプレフィックスは不要です。ワークスペースのスコープは自動的に適用されます）。
• ワークスペースストレージ（Companies、Contacts、…）に対する SQL には、cargo-storage に記載されている cargo-ai storage query execute "<sql>" を使ってください。
• すべての操作は非同期です。ポーリングするか、--wait-until-finished を指定してください。非同期ポーリングを参照してください。

cargo-analytics

重要なルール：

• segment download には --segment-uuid ではなく、--model-uuid が必要です。
• バッチ結果をダウンロードするには、release get <release-uuid> → nodes[].slug から output-node-slug を取得します。
• 請求額とクレジット使用量については、代わりに cargo-billing を使用します。
• Analytics は「何が起きたか」（メトリクス、件数、エクスポート）に答えます。質問が「なぜ」なのか（実行の失敗、エラーだらけのバッチ、予想外のコスト）を問う場合は、cargo-diagnostics に引き継ぎます。そのスイープ手順書は、Analytics のエラー件数を起点に調査を続けます。

cargo-billing

重要なルール：

• 管理者アクセス権を持つトークンが必要です。
• 請求額はセント単位です。ドルに換算するには 100 で割ります。
• subscription get の .subscription の下にある subscriptionAvailableCreditsCount + additionalAvailableCreditsCount - subscriptionCreditsUsedCount が、残りのクレジット数です。
• ノードの実行ごとに 0.01 クレジット（100 回につき 1 クレジット）が請求されます。 構造的なネイティブノードも、エラーになった実行も含まれます。この料金はどのノードにも割り当てられません（executions[].creditsUsedCount はプロバイダーのコストのみです）。そのため、この料金を含めずに作成した見積もりやノードごとのプロファイルは、実際より少ない値になります。確認できるのは usage get-metrics --unit orchestration.executions のみです。--unit に指定できるのは billing.credits ／ orchestration.executions ／ storage.records ／ hosting.events のいずれかのみで、--unit を指定しない場合は、意味の異なる count を持つこれら 4 種類が 1 つの items[] 配列に混在します。

cargo-diagnostics

重要なルール：

• 調べるべき実行がわからない場合は、スイープから始めます。最後に、トレースに使う代表的な UUID が示されます。UUID がまったくない場合は、orchestration trace list --started-after <iso> --statuses error,degraded を実行すると、子実行全体でトリガーごとに 1 行ずつ、失敗したものが一覧表示されます。span list ／ span count を使えば、SQL を使わずにバッチ、プロバイダー、アクション、エラーテキストでノード実行を絞り込めます。どちらにも開始日時（--started-after ／ --execution-started-after）が必要です。
• degraded は、フォールバックが失敗を吸収したことを意味します。 実行は成功していますが、ノードでエラーが発生しています。error と合わせてスイープしてください。
• ノードが生成した内容の正本は runContext です。実行の title は要約が切り詰められたものなので、証拠として扱わないでください。
• クレジットの割り当て（billing …）には管理者トークンが必要ですが、SQL と run get の手順には必要ありません。
• 有料ノードを再実行する修正は、すべて ../cargo-gtm/references/cost-discipline.md のパイロットゲートを通す必要があります。
• Diagnostics は調査結果を説明しますが、エクスポートは行いません。診断後に一括取得する場合（run download-outputs、batch download、segment download）は、cargo-analytics に戻ってください。
• cargo ルータースキルの references/interaction.md に従い、結論を先に示し、根拠は簡潔な表で提示してください。

cargo-observability

重要なルール：

• create の前に preview を実行してください。 alert preview --scope … --threshold … [--window-minutes 60] はアラートを発火させずに現在の状態を評価します。これは、しきい値が実際の状況に適しているか確認し、無効なスコープとしきい値の組み合わせ（outcome: "notComputed"）が、毎回の実行でエラーになるスケジュールになる前に検出する唯一の方法です。
• スコープとしきい値は対応する組み合わせで指定してください。 テレメトリーメトリクス（errorRate、duration+集計、credits+集計、count）には spans／runs／records が必要です。query にはクエリスコープが必要です。recordsCount／recordsShare／freshness／syncDuration には model が必要です。完全な対応表と単位については、references/scopes-and-thresholds.md を参照してください。
• 空のウィンドウと実際のゼロを区別してください。 ほとんどのメトリクスは、アイドル状態のウィンドウを empty（正常、発火なし）として報告します。実際の 0 を返すのは count と recordsCount のみです。これらを lte 0 と組み合わせると、デッドマンスイッチとして使用できます（ワークフローが停止したときや、モデルが空になったときにアラートを発火します）。
• 発火は最大 1 回で、クレジットを消費します。 アクションは実行として発火し、イベントには runUuids が含まれます。違反が続く場合は、条件が成立している各ティックにつき 1 回再発火しますが、同じ行に対して 2 回発火することはありません。アクションが有料プロバイダーを呼び出す場合は、../cargo-gtm/references/cost-discipline.md を適用してください。スケジュールされたアラートは、違反が発生するたびに再課金されます。
• --enabled で指定できるのは厳密に true／false のみです。モデルスコープの filter では、セグメンテーション形式の綴りである conjonction を使用します。
• 権限は observability:read／observability:write です（管理者専用ではありません）。宣言的な同等機能は、プロジェクトの defineAlert です。cargo-project を参照してください。

cargo-storage

重要なルール：

• <datasetSlug>.<modelSlug> 形式のテーブル名（例：default.companies）を使用して、cargo-ai storage query execute "<sql>" でクエリを実行します（全件エクスポートには storage query download --query "<sql>" を使用します）。model get-ddl は任意ですが、列の型や SQL 方言の確認に役立ちます。
• オーケストレーションのランタイムテーブル（runs／batches／spans／records）に対する SQL には、cargo-ai orchestration query execute "<sql>" を使用します。詳しくは cargo-orchestration に記載されています。
• レコードの高度なクエリ（フィルタリング、並べ替え、ページネーション）には、segmentation segment fetch を使用します。詳しくは cargo-segmentation に記載されています。
• storage relationship set は、データセットのリレーションシップ全体を置き換えます。ペイロードに含まれていないものはすべて削除されます。まず list を実行し、配列全体を送り返してください。

cargo-segmentation

重要なルール：

• フィルター JSON では conjunction ではなく conjonction を使用します。フィルターとグループの両方のレベルで必須です。綴りを間違えると 400 エラーとなり、conditions: [] のグループも拒否されます。
• 費用をかける前にサイズを確認してください。 segment fetch --fetching-limit 1 は、インラインフィルターの件数を無料で数えます（count を確認してください。--limit は対象レコード数に上限を設定するため、--limit 1 では 1 と報告されます）。保存済みセグメントの recordsCount が正式なサイズです。オーディエンスに対して有料の実行を提案する前に、その件数を伝えてください。
• segment download に必要なのは --model-uuid とフィルターです。--segment-uuid は指定しないでください。
• change list には --segment-uuid が必要です。change fetch には変更の UUID と --kinds（added／updated／removed／unchanged）が必要です。
• セグメントの作成時に --tracking-column-slugs を指定しない限り、updatedRecordsCount は 0 のままです。これらの列によって「更新」の定義が決まります。
• GENERATED_PLAY_SEGMENT という名前のセグメント（fromPlay: true）は、プレイが所有しています。手動で編集または削除しないでください。

cargo-connection

主な概念：

• インテグレーション ＝ 外部サービスの種類（HubSpot、Clearbit、Salesforce、…）
• コネクター ＝ インテグレーションの認証済みインスタンス（ノードでは connectorUuid で参照）

cargo-ai

重要なルール：

• RAG用のナレッジは、リリースのresourcesを介してエージェントに追加します。ファイルとライブラリは cargo-content から取得します。release update-draft --resources …で関連付けてから、release deploy-draftを実行してください。
• --serverを指定せずにcargo-ai mcpを実行すると、最初のパーティープラットフォームMCP（mcp.getcargo.io/mcp）にブリッジします。「ワークスペース唯一のMCPサーバー」ではありません。 ai mcp-serverは引き続き、用途を絞ったサーバーを構築します。--serverにそのuuidを指定してください。上記の「これらのスキルとCargoのMCPサーフェス」を参照してください。
• コーディングエージェント（リリースまたは新しいチャットでの--harness-slug + --repository）は、Cargo GitHubアプリとしてプッシュします。このアプリは対象リポジトリにインストールされている必要があります。 トークンのスコープはそのリポジトリに限定され、cargo/<name>ブランチ上で作業し、デフォルトブランチには決してプッシュしません。また、そのエージェントのPRでメンションすると、チャットが続行されます。ハーネスとリポジトリはチャット作成時に固定されます。--chat-uuidと一緒に指定すると拒否されます。
• CLI ≥ 1.0.19： ファイルとライブラリはaiドメインからトップレベルの**content**ドメインに移動しました（現在はcargo-contentスキル）。従来のcargo-ai ai file …コマンドは存在しません。

エージェントの_利用_（メッセージの送信、マルチターンチャット、ポーリング）には、cargo-orchestrationを使用してください。

ユースケースごとのモデルと温度設定については、../cargo-ai/SKILL.mdを参照してください。

cargo-content

重要なルール：

• CLI ≥ 1.0.19では、トップレベルに**content**ドメインが追加されています。cargo-ai content file … / cargo-ai content library …を使用してください。従来のcargo-ai ai file …パスは廃止されました（unknown commandが表示される場合は従来のパスを使用しています。CLIを更新してください）。
• ファイルまたはライブラリは、エージェントのデプロイ済みリリースのresourcesに関連付けるまで機能しません。この関連付けはcargo-aiで行います。
• uploadとputではデフォルトの動作が異なります。 upload（およびdefineFile）はファイルをエージェント検索用にインデックス化し、コンテキストリポジトリ内の.files/にもミラーリングします（コミットされ、プッシュされます）。一方、content file putとその他すべてのパス書き込みはファイルの保存のみを行います。--index vectorStoreを指定して書き込むまでエージェントは検索できず、Gitにも含まれません。
• リンクには認証がありません。 content file urlは、期限切れになるまで誰でも開ける署名付きリンクを返します（デフォルトは1時間、最大3時間）。publicファイルには、非公開に変更するまで有効な、認証不要の固定リンクがあります。ユーザーがそのファイルの共有を求めた場合にのみ、いずれかを共有してください。
• バッチ実行の入力ファイル（バッチを駆動するCSV）には、cargo-ai workspaceManagement file upload（別のサーフェス）を使用してください。cargo-workspace-managementを参照してください。

cargo-context

主な概念：

• コンテキストリポジトリ = ワークスペースのコンテキストを支える GitHub リポジトリです。代表例：getcargohq/cargo-workspaces。ファイル名には kebab-case.md を使用し、必須の title と description を含む YAML フロントマター、および domain/slug 形式の相互参照（.md なし）を使用します。
• ランタイムサンドボックス = コンテキストリポジトリをチェックアウトした、実行可能なコピーです。runtime write と runtime edit はデフォルトブランチにプッシュしますが、runtime execute はプッシュしません。
• ナレッジグラフ = すべての md/mdx ファイルを対象とする型付きグラフです。各ノードにはフロントマターと外部への相互参照が含まれます。cargo-ai context graph get で構築します。

重要なルール：

• runtime write / runtime edit はコミットしてプッシュします。runtime execute は一時的なものです。grep / ls / 調査に使用し、永続的な変更には使用しないでください。
• runtime edit --old-string は、ファイル内の内容と完全に一致する箇所が1つだけである必要があります（--replace-all を指定する場合を除く）。先に読み込み、空白も含めてそのままコピーしてください。
• すべての .md / .mdx ファイルに title + description のフロントマターを設定してください。これは強く推奨される慣例ですが、強制ではありません。フロントマターがない、または形式が不正でも runtime write / edit によってコミットされますが、インデックスの精度が下がります（グラフはファイル名と最初の段落にフォールバックし、description ではなく summary を読み取ります）。プロジェクトで宣言されたコンテキスト（defineContext）には、より厳しい条件が適用されます。フロントマターを解析できない場合や、宣言済みのファイルに一致しない references: エントリ、[[wikilink]]、相対 .md リンクがある場合、project check / plan / deploy は失敗します（title / description がなくても問題ありません）。
• グラフのエッジは、フロントマターの references:、Markdown リンク、または Wikilink からのみ生成されます。本文中にパスだけを記載してもエッジは作成されません。ソースファイルは references: に記載してください。
• ドメイン、規約、ドメインごとのテンプレートについては、../cargo-context/references/conventions.md を参照してください。

ライフサイクル：

• ドメイン（ICP、ペルソナ、証明、シグナル）から新しいワークスペースのコンテキストをブートストラップする方法については、../cargo-context/references/examples/bootstrap-from-domain.md を参照してください（べき等で、すでにシード済みのドメインはスキップします）。
• ブートストラップと、その後の呼び出しに応じた継続的な更新の手順書（フェーズ1 + フェーズ2 + 実施頻度）全体については、../cargo-context/references/examples/lifecycle.md を参照してください。

cargo-hosting

ライフサイクル： init（ローカルのひな形を作成）→ create（スロットとワークスペース内で一意のスラッグを作成）→ deployment create（ビルドしてアップロード）→ deployment promote（公開）。

重要なルール：

• --slug はワークスペースごとに一意です。公開ホストは <slug>-<workspace prefix>.<root> で、アプリとワーカーではルートが異なります。URL を組み立てるのではなく、get から url を読み取ってください。そのため、アプリからワーカーへの呼び出しはクロスオリジンとなり、ワーカーは CORS に応答する必要があります。
• CARGO_API_TOKEN はデフォルトでは注入されません。 設定されていないと createCargoApi はエラーをスローします。例外は、サービスユーザーが設定されたワーカー（hosting worker update --uuid <uuid> --run-as-user-uuid <service-user-uuid>）です。この場合、各公開時にそのユーザーの一時トークンが CARGO_API_TOKEN として設定されます。ただし、ワーカーまたはワークスペースの環境変数ですでにこのキーが設定されている場合を除きます。それ以外の場合は、トークンを発行してシークレット環境変数として保存してください。ワークスペース全体に設定するには workspaceManagement envVar create --secret を使用します。ワーカーごとに設定するには hosting worker env set --worker-uuid <uuid> --key CARGO_API_TOKEN --secret を使用します（値は標準入力の --value -、または同名のローカル変数から指定します）。プロジェクトでは defineWorker({ env }) を使用します。環境変数は昇格時にバインドされるため、変更後は再デプロイして昇格してください。
• ワーカーの catch でサニタイズしたエラーを返す場合は、先に console.error(err) を実行する必要があります。捕捉されなかったエラーだけがスタックトレース付きでログに記録されます。
• デプロイしても公開されるわけではありません。 deployment create はビルドを実行します。URL が切り替わるのは deployment promote の実行後です。公開中の内容は deployment get-promoted で確認できます。
• --source は dist/ ではなくパッケージのルートを指定します。ビルドはサーバー側で実行されます。package.json に build スクリプトが宣言されている場合はアプリ独自のスクリプト（ビルド全体を担当します）が実行され、そうでない場合は検出されたフレームワークのデフォルト（vite build、next build など）が実行されます。ワーカーの場合はバンドルされます。
• アプリの環境変数には公開用のプレフィックス（VITE_、NEXT_PUBLIC_ など）が必要で、公開バンドルにコンパイルされるため、シークレットにはできません（secretNotSupportedForApp）。
• Cargo が所有するホストは X-Robots-Tag: noindex を送信します。アプリがインデックス可能になるのは、カスタムドメイン（POST /v1/hosting/custom-domains）を使い、HTML がプリレンダリングされている場合のみです。
• ビルドは非同期です。昇格する前に、終端状態になるまで deployment get をポーリングしてください。
• デプロイコマンドでは --app-uuid と --worker-uuid は同時に指定できません。remove を実行するとデプロイも連鎖的に削除されます。
• フォルダーについては cargo-workspace-management を参照してください。--folder-uuid null を指定するとルートに移動します。

cargo-project

cargo.json を保持するフォルダーであるプロジェクト内に、TypeScript の宣言（defineConnector/defineModel/defineAgent/ definePlay/defineTool/defineMcpServer/defineContext/defineSegment/ defineFolder/defineFile/defineWorker/defineApp/defineCapacity/defineTerritory/ defineMember/defineRole/defineUser/defineRelationship/defineCustomIntegration/ defineScript/defineAlert/defineDomain/ defineMailbox、および一度だけ実行する defineBatch/defineRun）を使って Cargo ワークスペース全体を宣言し、cargo-ai project で実環境に反映します。すべてのリソースタイプに対応するため、命令型の機能を扱うすべてのスキルと重複します。上記の「宣言型と命令型」に従って使い分けてください。

ライフサイクル： project init（Cargo テンプレート getcargohq/cargo-manifest のひな形を作成。コンテキスト、実行頻度、評価を含みます。ルートに cargo.json と cargo.state.json、デプロイするリソースを infra/ に配置）→ project types（ワークスペースに対する型設定）→ define* ファイルを作成 → project plan（ワークスペースに保存された状態との差分を確認。作成は行いません）→ project deploy（作成・更新し、状態を保存）→ project destroy。さらに、refresh（フィールド名を示してドリフトを確認）、import（既存のリソースを取り込む）、pull（実環境のワークスペースから define* を生成して取り込む）、rollback、check（状態を使わずにオフラインで検証）、info（現在の内容を確認）、graph（実環境のワークスペース、またはオフラインの --project [--plan] に対する Mermaid 図）、state（状態の確認・参照先変更・削除。connect で GitHub からデプロイ）も使用できます。project plan はサインアウト状態でも、最後にキャッシュされた状態を使って実行できます。

重要なルール：

• cargo.state.json をコミットします — ただし、これは状態そのものではなく、ポインター（{"stateUuid": "…"}）です。デプロイ状態はワークスペースに保存され、デプロイ済みのプレイ／エージェント／アラートにアクセスする唯一の手段です（スラッグはありません）。ポインターを失った場合は project state bind で復元できますが、状態を失うとそれらは孤立します。project state list|create|bind|remove。
• プロジェクトとは、cargo.json を含むフォルダーです（{ "resources": "infra" }）。各コマンドはリポジトリのルートまでさかのぼって最も近いものを探し、それが見つからなければ停止して、echo '{ "resources": "infra" }' > cargo.json と表示します。cargo.state.json は cargo.json の隣に置き、infra/ には置きません。infra/cargo.state.json が残っていると、実行すべき mv コマンドを表示して停止します。複数のプロジェクトがあるリポジトリでは、それぞれに cargo.json が必要です。
• .uuid ではなくハンドルで接続します — define* ハンドルまたは xxRef("uuid") を渡します。
• 値を扱うヘルパーは1つではなく3つです。 secret("ENV_VAR") はデプロイ時にユーザーの環境変数を読み取り、状態とコンテンツハッシュには含まれません（そのため、ローテーションしたシークレットを実際に反映するには deploy --refresh が必要です）。env("ENV_VAR") は意図的にハッシュに含まれます。workspaceEnv("NAME") はポインターで、サーバーが使用のたびに再読み込みするため、ワークスペースで値をローテーションしても再デプロイは不要です。
• 非対話型の deploy／destroy（CI）には --yes が必要です。
• ワークスペースのインテグレーションを変更した後は cargo-ai project types を実行してください。設定の型チェックに必要です。型付けは便利ですが、なくてもデプロイできます。
• クレジットベースのコネクターアクションを含む definePlay／defineTool グラフの場合： project deploy の前に、プロバイダーのプレイブック（../cargo-gtm/provider-playbooks/、特に Recurring use のセクション）を確認してください — デプロイしたプレイは、スケジュール実行のたびにノードの料金が再度発生します。
• defineBatch／defineRun は次回のデプロイ時に1回だけ実行され、元に戻すことはできません。 outputs/ 内のファイルは、リソースの適用後に実際のバッチまたは実行を開始する実行処理を宣言します。ワークスペースに保持される状態内の台帳により、各 ID は1回だけ実行されます（再試行はありません — 新しい ID にすると再実行されます）。セグメントまたはフィルターに対する実行は完全なバッチです。デプロイ前に ../cargo-gtm/references/cost-discipline.md に従って試験運用し、承認してください。ガイド：../cargo-project/guides/executions.md。
• GitHub からデプロイするには、Actions にトークンを設定するのではなく、リポジトリを接続します。 cargo-ai project state connect は各 PR の内容をコメントに表示し、本番ブランチへのプッシュごとにデプロイします — 接続した時点のブランチヘッドも対象です。同じ種類の送信が100件、オーディエンスへの追加が5,000件、またはクレジットが2,500件を超えるマージは、PR に cargo:approve-impact ラベルが付くまで Needs approval: large impact で失敗します。このラベルを付けるのは、ユーザーが承認した場合だけです。Actions からもデプロイを実行すると失敗します（stateAutoDeployed）。手順：../cargo-project/recipes/deploy-from-ci.md。

同梱レシピ： recipes/scaffold-a-project.md、add-connector-and-model.md、build-an-agent.md、migrate-existing-workspace.md、deploy-from-ci.md。

クックブック： 約20種類の、事前に作成されたGTM成果物（TAMの構築、アカウントのスコアリング、通話内容の記録、インバウンドの適格性評価、CRMのエンリッチメントなど）は、単発のスキルとともにgetcargohq/gtm-skillsにあります。メニューはローカルにあります： ../cargo-project/references/cookbooks.md。 一般的なGTM成果物を一から作成する前に確認してください。

振り分けの判断基準は、単発か継続的かです。 ユーザーが今日リストを求めているなら「Build our TAM」は cargo-gtm、成果物を継続的に生成するパイプラインを求めているなら tam-building です。言葉は同じでも、成果物が継続して届くことを意図しているかどうかを見極めてください。各クックブックは、インストールするエージェントがプロジェクトにコピーして調整する、独立した実例です。記入するテンプレートではありません： npx skills add getcargohq/gtm-skills/<name>。注意事項と --force に関する警告については、../cargo-project/SKILL.md のセクションを参照してください。

cargo-mailbox-management

重要なルール：

• メールボックスはレコードごとではなく、毎月継続して発生するクレジット料金です。メールボックス1つあたり月100～125クレジット（共有およびプライベートは100、googleは125。最新の数値は mailboxManagement pricing get で確認）、存在する限り課金されます。課金を止める方法は mailbox remove のみで、一時停止はできません。初回の create を実行する前に、メールボックスの総数と月間のクレジット見積もりを提示し、明確な承認を得てください。
• このドメインからメールを送信することはありません。 配信にはネイティブアクション sendEmail（{"kind":"native","actionSlug":"sendEmail"}、入力は --data）を使用し、cargo-orchestration 経由で実行します。送信1件あたり0.1クレジットです。これを呼び出すプレイは実行のたびに再課金され、再度連絡します。
• 送信量は設定値ではなく、段階的に増加します。 実際の送信量は、warmupStartedAt から45日間で1日5件から40件まで直線的に増加します。start-warmup を一度も実行していないメールボックスは、永久に1日5件に固定されます。stop-warmup を実行すると起点が0日目にリセットされ、dailySendLimit でできるのは増加をさらに制限することだけで、緩和することはできません。
• すべての送信は ../cargo-gtm/references/acceptable-use.md §3（根拠、抑制、関連性）による制限を受けます。抑制設定はワークスペース全体に適用され、送信のたびに確認されます。削除コマンドはなく、List-Unsubscribe による登録解除は自動的に書き込まれます。送信量の上限を引き上げることも、同じ送信量を確保するために1つのキャンペーンを追加のメールボックスに分散することも、§2に基づき不正回避として拒否してください。
• ここでは非同期処理はありません。ポーリングする実行はありません。非同期に見える例外は mailbox create で、status: "pending" を返します。これは run get ではなく、mailbox refresh-status で解消します。
• --type outlook はフラグとして受け付けられますが、必ず失敗します（transportNotSupported — Graph による配信はまだ提供されていません）。--statuses／--kinds／--reasons は、スペースを入れずにカンマ区切りで指定します。mailbox list だけは count がなく、mailbox／suppression のリストにはデフォルトの上限がありません（最大1000件）。これに対し、メッセージ／スレッド／イベントのデフォルトは50件です。
• bounced を生成する処理はまだありません。配信状況通知を解析する機能がないため、バウンスのイベントは記録されず、自動的な抑制も行われません。バウンス件数が0でも、リストが問題ないとは報告しないでください。
• 送信ドメインを扱うCLI機能はありません。 mailbox create --domain-uuid は必須です。また、domainManagement には cargo-ai コマンドがありません。UUID はウェブアプリまたはプロジェクトの defineDomain から取得してください。権限は mailboxManagement:read／:write で、管理者限定ではありません。

cargo-workspace-management

重要なルール：

• ほとんどのコマンドには、管理者アクセス権を持つトークンが必要です。
• 自動化は必ずサービスユーザーとして実行し、個人として実行しないでください。 サービスユーザー（kind: "service"）はAPI、ウェブアプリ、または defineUser から作成します。CLI の user create で招待できるのは個人のみです。サービスユーザーをワーカーまたはコーディングエージェントの実行ユーザーとして割り当てるには、そのユーザー自身のすべての権限があなたの権限に含まれている必要があります（runAsUserNotPermitted）。
• workspaceManagement token create には --name が必須です（従来の --from-user フラグは削除されました）。後で token list を見たときに用途が明確にわかる名前を選んでください。
• トークン値は秘密情報です。token list は、自分のトークン（管理者の場合はサービスユーザーのトークンも）の値を返します。token create のときだけ返すわけではありません。シークレットマネージャー（GitHub Secrets、AWS Secrets Manager など）に保存し、token list の出力を決して貼り付けないでください。
• CLI がエラーになる、誤った使い方をしている、またはCLIタスクの進行にあなた（ユーザーまたはエージェント）が行き詰まっている場合は、必ず workspaceManagement report create を送信してください。このファイルの冒頭にあるセクションと ../cargo-workspace-management/references/examples/reports.md を参照してください。

cargo-mcp

重要なルール：

• 毎回のセッションで、最初に whoami を実行してください。 トークンはセッションを単一のワークスペースに紐付け、上書きはできません。誤ったワークスペースでセッションを開始すると、他のユーザーに属する実データが返され、成功したように見えてしまいます。
• リストに対して execute_action をループ実行しないでください。 execute_action_batch のほうが低コストで、処理を確認でき、1つのオブジェクトと出力 CSV を返します。
• search_actions は各アクションの credits[].cost を返すため、実行前に料金を提示し、全件に一括適用する前に10～20件をサンプルとして処理してください。
• query_models は、行数上限が小さい（デフォルト20、最大50）読み取り専用の SQL SELECT を1つ実行します（JOIN、集計、CTE は使用可能です）。行をページングして取得するのではなく、SQL 内で集計してください。全件エクスポートには cargo-storage を使用します。
• プラットフォームのエンドポイントは、すべてのワークスペースに同じ固定のツール一覧を提供します。defineMcpServer / ai mcp-server create で公開されたサーバーは別のエンドポイントです（cargo-ai mcp --server <uuid>）。

非同期ポーリング

すべての操作は非同期です。ブロックするには --wait-until-finished を渡すか、ポーリングしてください。

結果の種類	ポーリングコマンド	間隔	完了とみなす条件
実行	cargo-ai orchestration run get <uuid>	2秒	status が success、error、または cancelled
バッチ	cargo-ai orchestration batch get <uuid>	5秒	status が success、error、または cancelled
エージェントメッセージ	cargo-ai ai message get <uuid>	2秒	status が success または error

action execute は実行を返し、action execute-batch はバッチを返します。どちらも同じ方法でポーリングできます。

リトライ戦略、エラー処理、大規模バッチに関するガイダンスは、../cargo-orchestration/references/polling.md を参照してください。

---

スキル間の UUID の流れ

references/uuid-flow.md を参照してください。スキル間で受け渡されるすべての UUID とスラッグ（workflowUuid、modelUuid、connectorUuid、actionSlug など）のプロデューサー／コンシューマー表、ワークフローの前に実行する標準的な検出手順、および UI で UUID を解決するための app.getcargo.io URL パターンを記載しています。

---

エンドツーエンドのユースケース

references/use-cases.md を参照してください。どのスキルを読み込むか、各ケースでどのような順序でコマンドを実行するかを示す、8つの手順付きレシピ（単一レコードのエンリッチメント、バッチ処理と CRM 同期、AI リードスコアリング、ゼロからのカスタムワークフロー作成、エラー監視、新規ワークスペースのブートストラップ、フィルターとソートを使ったセグメントのエクスポート、GTM コンテキスト監査）を紹介しています。

---

よくある落とし穴

references/gotchas.md を参照してください。気づきにくい失敗の原因や、混同されやすいコマンドの組み合わせ（conjonction の綴り、run create と batch create、--model-uuid と --segment-uuid、ストレージクエリのテーブル名、トークン値はシークレットであること、請求額のセント単位、サードパーティーコネクターのレート制限、context runtime execute と write／edit の違いなど）を説明しています。