cargo-skills

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

Cargo CLI — スキルの概要

このリポジトリには、Cargo の AI ネイティブな収益インフラストラクチャ向けの 7 つのスキルが含まれています。各スキルは、それぞれ異なる領域を扱います。このファイルでは、タスクに応じて読み込むスキルと、スキルを組み合わせる方法を説明します。

インストール

npm install -g @cargo-ai/cli
cargo-ai login --token <your-api-token>
# Optional: target a specific workspace
cargo-ai login --token <your-api-token> --workspace-uuid <uuid>
# Verify
cargo-ai whoami

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

すべてのコマンドは標準出力に JSON を出力します。コマンドが失敗すると、ゼロ以外の終了コードを返し、{"errorMessage": "..."} を出力します。

CLI が失敗する場合や行き詰まった場合 — ワークスペース管理にレポートを送信する

スキルに記載された方法では CLI の問題が解決せず、--help でも解決できない場合、ユーザーまたはエージェントが進展のないまま同じコマンドを繰り返し実行している場合、フラグや JSON ペイロードの構文が不明な場合、または必要な機能が見当たらない場合は、ワークスペース管理にレポートを送信してエスカレーションしてください。

cargo-ai workspace 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 を参照してください。

---

スキル一覧

スキル	次のことを行う場合に読み込みます…
cargo-orchestration	アクションの実行、ワークフローの実行、バッチのトリガー、エージェントとのチャット、データウェアハウスへのクエリ
cargo-analytics	実行結果のダウンロード、セグメントデータのエクスポート、エラー率やメトリクスの監視
cargo-billing	クレジット使用量の確認、サブスクリプションの詳細の表示、ワークフローまたはコネクターごとのコストの追跡
cargo-storage	データモデル、列、データセット、リレーションシップの確認または変更
cargo-connection	コネクター認証の管理、利用可能な連携機能とそのアクションの確認
cargo-ai	エージェントの作成と設定、RAG 用のファイルのアップロード、MCP サーバーの管理
cargo-workspace-management	ユーザーの招待、API トークンの作成、フォルダーの整理、ロールの管理、CLI の問題の管理チームへの報告

---

スキルの関連性

┌──────────────────────────────────────────────────────────────┐
│                  cargo-workspace-management                  │
│             Authentication, users, tokens, folders           │
└──────────────────────────────────────────────────────────────┘

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

依存関係の実際の使い方：

• cargo-workspace-management はすべてのスキルに認証コンテキストを提供します。最初に設定してください。
• cargo-storage、cargo-connection、cargo-ai は、cargo-orchestration に UUID を提供する同等のスキルです。互いに依存しません。
• system-of-record 経由でクエリを実行する前に、cargo-storage を読み込んで DDL（正確なテーブル名）を確認してください。
• ワークフローのノードグラフを作成する前に、cargo-connection を読み込んで connectorUuid と actionSlug を確認してください。
• エージェントノードを使用するワークフローを実行する前に、cargo-ai を読み込んで agentUuid を確認してください。
• 実行が完了した後、結果のダウンロードやパフォーマンスの測定には cargo-analytics を読み込んでください。
• 上記のいずれかで消費されるクレジットを把握するには、cargo-billing を読み込んでください。

---

スキルの詳細

cargo-orchestration

実行ハブです。 アクションを実行し、ワークフローを実行し、AI エージェントとチャットし、データウェアハウスにクエリを実行して、セグメントのレコードを取得します。

主なコマンド：

# Single actions (no workflow needed)
cargo-ai orchestration action execute --action '{"kind":"tool","toolUuid":"<uuid>","config":{}}' --data '{...}'
cargo-ai orchestration action execute-batch --action '{"kind":"connector","integrationSlug":"...","actionSlug":"...","config":{}}' --records '[{...},{...}]'

# Workflows (chain multiple actions)
cargo-ai orchestration run create --workflow-uuid <uuid> --data '{...}'
cargo-ai orchestration run create --data '{...}' --nodes '[...]'
cargo-ai orchestration batch create --workflow-uuid <uuid> --data '{"kind":"segment","segmentUuid":"..."}'

# AI agents
cargo-ai ai message create --chat-uuid <uuid> --parts '[{"type":"text","text":"..."}]'

# Data
cargo-ai system-of-record client query "SELECT * FROM <table> LIMIT 10"
cargo-ai segmentation segment fetch --model-uuid <uuid> --filter '{"conjonction":"and","groups":[]}'

重要なルール：

• action execute、run create、batch createのどれを使用するかは、cargo-orchestration/SKILL.md冒頭の判断フローチャートを参照してください。
• JSON フィルターではconjunctionではなくconjonctionを使用してください。スペルを間違えてもエラーなしで失敗します。
• system-of-record にクエリを実行する前に、必ず DDL を取得してください：cargo-ai storage model get-ddl <model-uuid>。
• すべての操作は非同期です。ポーリングするか、--wait-until-finishedを指定してください。非同期ポーリングを参照してください。

参照： cargo-orchestration/SKILL.md

---

cargo-analytics

測定とエクスポートです。 実行結果のダウンロード、セグメントデータのエクスポート、エラー率や成功指標の監視に使用します。

主なコマンド：

cargo-ai orchestration run get-metrics --workflow-uuid <uuid>
cargo-ai orchestration run download --workflow-uuid <uuid> --is-finished
cargo-ai orchestration run count --workflow-uuid <uuid> --statuses error
cargo-ai segmentation segment download --model-uuid <uuid> --filter '{"conjonction":"and","groups":[]}'

重要なルール：

• segment downloadには--segment-uuidではなく--model-uuidが必要です。
• バッチ結果をダウンロードするには、release get <release-uuid>のnodes[].slugからoutput-node-slugを取得してください。
• 請求額やクレジット使用量を確認するには、代わりにcargo-billingを使用してください。

参照： cargo-analytics/SKILL.md

---

cargo-billing

コストとクレジットの管理です。 ワークフロー、コネクター、エージェントごとのクレジット消費量の追跡、サブスクリプションの状態確認、請求書の表示に使用します。

主なコマンド：

cargo-ai billing usage get-metrics --from <YYYY-MM-DD> --to <YYYY-MM-DD>
cargo-ai billing usage get-metrics --from <date> --to <date> --group-by workflow_uuid
cargo-ai billing subscription get
cargo-ai billing subscription get-invoices

重要なルール：

• 管理者アクセス権のあるトークンが必要です。
• 請求書の金額はセント単位です。ドルに換算するには100で割ってください。
• subscription getのsubscriptionAvailableCreditsCount - subscriptionCreditsUsedCountが残りのクレジット数です。

参照： cargo-billing/SKILL.md

---

cargo-storage

データスキーマの管理です。 モデルの調査、列の作成や更新、データセットの参照、ワークスペースのデータ構造の把握に使用します。

主なコマンド：

cargo-ai storage model list
cargo-ai storage model get-ddl <model-uuid>   # always run before SoR queries
cargo-ai storage column list --model-uuid <uuid>
cargo-ai storage relationship set --from-model-uuid <uuid> --to-model-uuid <uuid>

重要なルール：

• system-of-record 経由でクエリを実行する前に、必ずmodel get-ddlを実行してください。正確なテーブル名（例：datasets_default.models_companies）が含まれています。
• 高度なレコードクエリ（フィルタリング、並べ替え、ページネーション）には、cargo-orchestrationのsegmentation segment fetchを使用してください。

参照： cargo-storage/SKILL.md

---

cargo-connection

コネクターとインテグレーションの管理です。 外部サービスの認証、対応アクションの確認、ワークフローノードグラフに必要なconnectorUuidとactionSlugの値の取得に使用します。

主なコマンド：

cargo-ai connection connector list
cargo-ai connection integration list
cargo-ai connection integration get <slug>          # third-party actions (HubSpot, Salesforce, etc.)
cargo-ai connection native-integration get          # built-in Cargo actions only (NOT third-party)

主な概念：

• インテグレーション＝外部サービスの種類（HubSpot、Clearbit、Salesforce、…）
• コネクター＝認証済みのインテグレーションのインスタンス（ノード内でconnectorUuidによって参照されます）

参照： cargo-connection/SKILL.md

---

cargo-ai

エージェントリソースの管理です。 エージェントの作成と設定、検索拡張生成（RAG）用ドキュメントのアップロード、MCP サーバーへの接続に使用します。

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

主なコマンド：

cargo-ai ai agent list
cargo-ai ai agent create --name "Lead Researcher" --language-model-slug gpt-4o --temperature 0.3
cargo-ai ai file upload --file-path ./knowledge-base.pdf
cargo-ai ai mcp-server create --name "Internal Tools" --url "https://..."
cargo-ai ai memory list --agent-uuid <uuid>

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

参照： cargo-ai/SKILL.md

---

cargo-workspace-management

ワークスペース管理。 ユーザーの招待、API トークンの作成とローテーション、プレイ／ツール／エージェントのフォルダーへの整理、ロールの管理に使用します。また、CLI でエラーが発生した場合や誤用されている場合は、ワークスペース管理にレポートを送信します。

主なコマンド：

cargo-ai whoami
cargo-ai workspace user create --user-email [email protected] --role-slug <slug>
cargo-ai workspace token create --name "CI/CD pipeline"
cargo-ai workspace folder create --name "Q1 Campaigns" --emoji-slug "rocket" --kind "play"
cargo-ai workspace report create --title "<summary>" --description "<details>"

重要なルール：

• ほとんどのコマンドには、管理者アクセス権を持つトークンが必要です。
• workspace token create には --name が必須です（従来の --from-user フラグは削除されました）。後で token list を実行したときに用途が明確にわかる名前を付けてください。
• トークンの値が表示されるのは作成時の1回限りです。すぐにシークレットマネージャー（GitHub Secrets、AWS Secrets Manager など）に保存してください。
• CLI でエラーが発生した場合、誤用されている場合、または CLI タスクの進行に（ユーザーまたはエージェントが）苦労している場合は、必ず workspace report create を送信してください。このファイルの冒頭のセクションと cargo-workspace-management/references/examples/reports.md を参照してください。

参考資料： cargo-workspace-management/SKILL.md

---

非同期ポーリング

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

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

action execute は実行を返し、action execute-batch はバッチを返します。どちらにも同じポーリング方法が適用されます。

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

---

スキル間の UUID の受け渡し

ほとんどの cargo-orchestration 操作には、他のスキルで取得した UUID が必要です。この表では、各 UUID を取得するスキルと、それを使用するコマンドを示します。

UUID	取得元	使用するコマンド
workflowUuid	orchestration play list / tool list	run create、batch create、run get-metrics、run download
modelUuid	storage model list	segment fetch、segment download、system-of-record query（DDL 経由）
segmentUuid	segmentation segment list	batch create --data '{"kind":"segment",...}'
agentUuid	ai agent list	ai chat create、ノードグラフ（kind: "agent"）
connectorUuid	connection connector list	ノードグラフ（kind: "connector"）、billing usage --connector-uuid
actionSlug	connection integration get <slug>（サードパーティー製）または connection native-integration get（組み込み）	ノードグラフ（kind: "connector" または kind: "native"）
releaseUuid	orchestration batch get → .releaseUuid	orchestration release get、batch download
batchUuid	orchestration batch create	batch get、batch download、run get-metrics --batch-uuid
folderUuid	workspace folder list	play list --folder-uuid、tool list --folder-uuid
roleSlug	workspace role list	workspace user create --role-slug

ワークフローを実行する前の標準的な確認手順：

# 1. Confirm identity
cargo-ai whoami

# 2. Find the tool or play to run
cargo-ai orchestration tool list
cargo-ai orchestration play list

# 3. Find the model and get its DDL (if querying via SoR)
cargo-ai storage model list
cargo-ai storage model get-ddl <model-uuid>

# 4. Find connectors needed by the workflow nodes
cargo-ai connection connector list

# 5. Find agents used in workflow nodes
cargo-ai ai agent list

# 6. Find the segment to process (for plays / batch with segment data)
cargo-ai segmentation segment list

UI で取得する

各リソースには、Cargo アプリ内に専用ページがあります。次の URL パターンを使って、CLI から返された UUID を UI で参照したり、ユーザーが貼り付けた URL から UUID を抽出したりできます。

リソース	URL パターン
Play	app.getcargo.io/workspaces/<WORKSPACE_UUID>/plays/<PLAY_UUID>
ツール	app.getcargo.io/workspaces/<WORKSPACE_UUID>/tools/<TOOL_UUID>
エージェント	app.getcargo.io/workspaces/<WORKSPACE_UUID>/agents/<AGENT_UUID>
モデル	app.getcargo.io/workspaces/<WORKSPACE_UUID>/models/<MODEL_UUID>

ワークスペース UUID は、cargo-ai whoami の workspace.uuid に返されます。

---

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

1. 1 社の情報を拡充する（最も簡単な方法）

必要なスキル： cargo-orchestration

1. orchestration action execute            → run a connector action on one record
   --action '{"kind":"connector","integrationSlug":"clearbit","actionSlug":"company_enrich","config":{}}'
   --data '{"domain":"acme.com"}' --wait-until-finished

2. 企業のリストを拡充して CRM にプッシュする

必要なスキル： cargo-storage、cargo-connection、cargo-orchestration、cargo-analytics

1. storage model get-ddl                   → get exact table name
2. connection connector list               → get enrichment + CRM connector UUIDs
3. connection integration get <slug>       → discover third-party action slugs (e.g. HubSpot, Clearbit)
4. orchestration tool list                 → find the enrichment tool
5. orchestration batch create      → run on a segment of companies
6. orchestration batch get         → poll until status is terminal
7. analytics run download          → export results

3. AI でリードをスコアリングし、モデルを更新する

必要なスキル： cargo-ai、cargo-orchestration、cargo-billing

1. ai agent list                   → find or create the scoring agent
2. ai agent create                 → configure instructions, model, temperature 0.0
3. orchestration play list         → find the scoring play
4. orchestration batch create      → trigger on a segment of new leads
5. orchestration batch get         → poll until status is terminal
6. billing usage get-metrics       → check credit consumption

4. カスタムの情報拡充ワークフローを一から構築する

必要なスキル： cargo-connection、cargo-orchestration

1. connection connector list               → get connector UUID
2. connection integration get <slug>       → get actionSlug for the third-party service
3. orchestration node validate --nodes     → validate graph before running
4. orchestration run create --nodes        → run with custom node graph
5. orchestration run get                   → poll to terminal state

5. ワークフローの健全性を監視し、エラー発生時にアラートを送る

必要なスキル： cargo-orchestration、cargo-analytics

1. orchestration tool list / play list    → discover workflowUuid
2. analytics run count --statuses error   → count errors in period
3. analytics run get-metrics              → get success/error rate breakdown
4. analytics run download --statuses error → download failed runs for inspection

6. 新しいワークスペースをセットアップする

必要なスキル： cargo-workspace-management、cargo-storage、cargo-connection、cargo-ai

1. workspace token create --name <label>   → create a dedicated, named API token
2. workspace role list             → discover available roles
3. workspace user create           → invite team members
4. storage model create            → create Companies and Contacts models
5. storage column create           → add columns (name, domain, employee_count, etc.)
6. storage relationship set        → link Contacts → Companies
7. connection connector create     → connect enrichment and CRM integrations
8. ai agent create                 → configure an AI agent for research or scoring
9. workspace folder create         → organize plays and tools into folders

7. セグメントデータをエクスポートして分析する

必要なスキル： cargo-storage、cargo-analytics

1. storage model list              → get modelUuid
2. analytics segment download      → export with filter and sort
   --filter '{"conjonction":"and","groups":[
     {"conjonction":"and","conditions":[
       {"kind":"string","columnSlug":"country","operator":"is","values":["US"]}
     ]}
   ]}'
   --sort '[{"columnSlug":"created_at","kind":"desc"}]'

---

よくある落とし穴

落とし穴	詳細
conjonction のスペル	フィルター JSON では conjonction（conjunction ではありません）を使います。これは意図的なものです。ここを間違えてもエラーは表示されず、レコードが返されません。
run create と batch create	run create が機能するのは tool ワークフローのみです。play の workflowUuid を使うと playNotCompatible が返されます。
--model-uuid と --segment-uuid	segment fetch と segment download には --model-uuid が必要です。segment list → .modelUuid から取得してください。
SQL より先に DDL	テーブル名を推測してはいけません。必ず最初に model get-ddl <uuid> を実行してください。テーブル名は datasets_default.models_companies のような形式です。
トークンは一度しか表示されない	API トークンの値が返されるのは作成時のみです。すぐに保存してください。workspace token create には --name が必要です（--from-user は使えなくなりました）。
請求額の単位はセント	subscription get-invoices が返す amount の単位はセントです。100 で割ってください。
Play と tool の違い	Play = データの変更に反応します（セグメント駆動）。Tool = オンデマンドで実行されます（手動、API、cron）。
バッチデータの種類	Play ワークフローが受け付けるのは segment、change、filter、recordIds です。Tool ワークフローが受け付けるのは file、records です。
サードパーティーコネクターのレート制限	レート制限があるのは kind: "connector" ノード（Clearbit、HubSpot など）のみで、ネイティブノードにはありません。バッチの実行中にエラーが気付かれないまま増えていきます。まず 1 レコード、次に 50 レコード、さらに 500 レコードで試してから本番規模で実行してください。コネクターノードにはバックオフ付きの retry を追加してください。