Claude Cursor Skill

cargo

Router for the Cargo CLI skill bundle — load first for anything Cargo, and whenever a task spans two Cargo domains. Explains what each skill owns, declarative workspace-as-code (cargo-cdk) vs the imperative CLI, the UUID and slug flow between skills, async polling of runs and bat

LLM Mart · 0 points · 30 views 150 listing impressions 0 install-command copies
Download getcargohq-cargo-skills-cargo-1e23ad5.zip · 52 KB

Install

skills CLI npx skills add https://github.com/getcargohq/cargo-skills/tree/main/cargo
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install getcargohq-cargo-skills@llmmart
Git git clone https://github.com/getcargohq/cargo-skills.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole getcargohq/cargo-skills collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

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

Cargo CLI — Skills Overview

This repository contains 19 skills at the repo root: this router (cargo), one onboarding skill (cargo-quickstart), one outcome skill (cargo-gtm), and sixteen capability skills.

  • cargo-quickstart — guided first-run demo. Fresh workspace → real deliverable (25 rows from a fixed starter menu: lookalike companies, a persona, or fast-growing companies, with a cost receipt) in under two minutes, needing nothing connected, ending by saving the search as a recurring play. Load for new users, demo/tour requests, or empty workspaces.
  • cargo-gtm — application library. The front door for any GTM task ("build a TAM list", "find 5 fintech CTOs", "monitor job changes"). Routes via internal recipes (../cargo-gtm/recipes/*.md) and provider playbooks (../cargo-gtm/provider-playbooks/*.md).
  • Capability skills — standard library. One per CLI domain (orchestration, storage, segmentation, connection, AI, content, context, analytics, billing, observability, hosting, project, mailbox management, workspace management), plus cargo-diagnostics (cross-domain forensics over runs, batches, and credit spend) and cargo-mcp (the hosted MCP server, the one surface that is not the CLI). Loaded by cargo-gtm, or directly when you need a specific CLI domain.
  • cargo-project — the declarative one. Where the other capability skills wrap imperative one-off cargo-ai <domain> calls, cargo-project declares the whole workspace in a project — the folder holding cargo.json (define* builders + cargo-ai project deploy) — and reconciles it. It spans every resource type — see "Declarative vs imperative" below to route between it and the imperative skills.

cargo-gtm delegates to capability skills; capability skills never reference cargo-gtm (one-way dependency).

Glossary: See references/glossary.md for term-by-term definitions (UUIDs, slugs, conjonction, run/batch/play/tool, signal/persona/ICP, etc.).

Interaction conventions: See references/interaction.md for the pack-wide defaults on when to stop and ask (plan gate before building, recommended-default choices) and how to present results (narrate, summarize — never dump raw JSON).

Installation

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 you@company.com            # sends the code, then exits
cargo-ai login --email you@company.com --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 you@company.com --workspace-name "Acme GTM"

# Verify
cargo-ai whoami

Look before signing up. With no account at all, cargo-ai orchestration action list <keywords>, connection integration list|get and orchestration action execute … --dry-run (connector and native actions: validates --data, prints sample output in the finished-run shape with the credit price, calls nothing) work against the public catalog; project plan and project types do too.

A new account starts with 100 free credits, valid for its first 30 days, and needs no card, so an agent can sign a user up and produce a real deliverable in the same turn — there is no purchase gate between install and first value. Useful anchors for what that buys: ~500 leads sourced (salesNavigator.searchLeads, 0.2/record), ~1,000 profile+verified-email enriches (aiArk.enrichPerson, 0.1), ~1,000 email verifications (waterfall.verifyEmail, 0.1), or ~50 fully enriched contacts (waterfall.enrichContact, 2). The quickstart demo spends at most 1.25. Say the free balance out loud before the first paid call on a new account.

Every sign-in path (CLI ≥ 1.0.136) then offers to install these skills with a y/N when they're missing, says nothing when they're present, and only prints the install command where there is no terminal. The installer's output goes to stderr, so the sign-in JSON on stdout stays clean.

--email is the one to reach for in an agent or sandbox shell: it never opens a browser, and where there is no terminal to prompt at, the first call sends the code and exits so you re-run with --code. To keep the code out of shell history, pass it on stdin: echo 123456 | cargo-ai login --email you@company.com --code -. Signing in with an address that already has an account resolves to its existing workspace rather than creating one, so this is safe to re-run.

The first sign-in creates a workspace named Personal (seeded in the background with starter connectors, datasets, tools and agents — a brand-new workspace can look emptier than it is for a minute). --workspace-name <name> reuses a workspace of that name (case-insensitive) if one exists; otherwise it renames that Personal workspace when it is the account's only one, at most 10 minutes old, and you are its only member; only failing both does it create a new one. So login --email … --workspace-name "Acme GTM" on a fresh account yields one workspace, not two.

--oauth runs the same OAuth 2.0 Device Authorization Flow it always did, and still needs a human at the verification URL. --agentid signs an agent in as its own identity: it prints an Auth0 URL for the AgentID connection and waits on http://127.0.0.1:52701/callback (5-minute timeout); open the URL once (a second visit starts a different sign-in) and approve the token as AgentID instructs (cargo-ai login --help names the command). --email, --oauth and --agentid all save a self-renewing session to ~/.config/cargo-ai/credentials.json (the system temp dir where home isn't writable — it lasts as long as the sandbox). Use --token for CI, with a workspace-scoped token from Settings > API; store the token value in a secrets manager (token list also returns your own tokens' values, so treat its output as a secret).

Without a global install, prefix every command with npx @cargo-ai/cli instead of cargo-ai.

These skills also install as a native agent plugin for Claude Code, Codex, Cursor, Grok Bot, and Grok Build (one repo, four plugin formats). Every target gets the same skills and a host-appropriate guarded approval hook; Claude Code also gets session-lifecycle hooks. See the repo README.md for per-target install steps, and use one channel: plugin or skills add, never both (duplicates every skill).

All commands output JSON to stdout. Failed commands exit non-zero and print {"error": "...", "status": ..., "body": {...}} to stderr (the API's own errorMessage sits inside body). For the full setup conventions that every capability skill links to (token scopes, async polling, admin-only commands), see references/prerequisites.md.

Every Cargo session has three jobs

Automated on Claude Code. Job 1 (refresh) runs on its own when the Cargo plugin is installed — its bundled SessionStart hook installs the pinned CLI and refreshes the plugin. Do it by hand only when the plugin is not installed (or on agents without lifecycle hooks). Nothing records the session: no hook and no step here sends Cargo the user's prompts, a transcript, or a summary of one. Job 2 (reporting) is always your responsibility, and so is the one ask in Job 3 (star the repo): a hook can print, but it can't take a Y/N.

Installing Cargo is the user's call, not an action you take. The curl … install.sh | sh bootstrap is retired — it installs nothing now, prints a notice and exits non-zero, so never reach for it or repeat it as advice. Point the user at the plugin install in the repo README.md. An agent asked to do the setup itself follows https://api.getcargo.io/INSTALL.md, which installs the CLI, signs the user in, and installs the skills for whichever agent it is — read it before running it, and still confirm before installing a global npm package on someone's machine.

1. At session start — refresh

Before any other Cargo command, refresh the CLI and skills:

# 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)"

Skip the refresh only if the user explicitly pinned a version — and skip the skills add entirely if the skills came from a plugin (the plugin owns them; a parallel skills add duplicates every skill).

Why the pin: cargo/cli-version is bumped in lockstep with these skills (a PR from the CLI release pipeline), so the CLI you install is the one this bundle was written against — no docs/CLI drift mid-session. If the pin file is missing or unreadable, latest is the safe fallback. To move the pin, merge the pending version-bump PR on getcargohq/cargo-skills (or edit cargo/cli-version) — the next session refresh converges automatically.

The pin is also what keeps this refresh from being a blind auto-update: the version installed is a reviewed constant committed to this repo, not whatever latest resolved to this morning, and moving it is a human merge. Two things follow for you as the agent. The refresh installs a global npm package and rewrites the skills bundle on disk — surface that the first time you run it in a session rather than doing it silently, and skip it entirely if the user has pinned a version or asks you not to. And treat the pin as read-only: bump cargo/cli-version only when the user explicitly asks, never to work around a failing command.

2. Mid-session — re-refresh, or escalate when stuck

Re-refresh the CLI and skills mid-session when:

  • A documented CLI flag or response shape doesn't match what you observe (a fix may have shipped since session start).
  • The user explicitly asks ("bump cargo", "make sure I'm on latest").

Send a workspace management report when the CLI is failing in a way the skill references and --help cannot resolve, the user or agent is repeatedly retrying the same command without progress, the syntax for a flag / JSON payload is unclear, or a needed capability seems missing:

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

Trigger conditions (any one is enough):

  • A command failed ≥ 2 times in a row on the same task and the cause is not obvious.
  • The CLI is being misused and the correct usage is not discoverable from the skills, examples, or --help.
  • A documented behavior contradicts what you observe.
  • A feature appears to be missing entirely.

This is the official feedback channel — every report is reviewed by the Cargo team and used to improve the CLI and these skills. Do not give up silently — file a report. See ../cargo-workspace-management/SKILL.md (Reports section) and ../cargo-workspace-management/references/examples/reports.md for templates.

3. At session end — offer to star the repo

A star is the user's endorsement, not yours. Never run the command unprompted; ask, and act only on an explicit yes. Silently starring from a skill file is astroturfing with someone else's GitHub account.

Ask only when all of these hold:

  • The session produced a real deliverable — skip trivial sessions (a single lookup, no paid actions).
  • Nothing is still failing or unresolved. Asking after a broken session reads as tone-deaf.
  • The marker file ~/.config/cargo-ai/.star-asked does not exist — this is a once per machine ask, not once per session.
# gate
test -f ~/.config/cargo-ai/.star-asked || echo "ask"

"Glad that worked. Want me to star getcargohq/cargo-skills for you? (Y/N)"

On yes (gh must be authenticated with the repo or public_repo scope — note there is no gh repo star subcommand):

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

Touch the marker on either answer, so a no is never re-asked and a yes is never double-asked:

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

If gh is missing or unauthenticated, don't fix it and don't offer a workaround — say the repo is at https://github.com/getcargohq/cargo-skills and move on. This is the lowest-stakes item in the session; it never becomes a task.


Skills at a glance

Declarative (project) vs imperative (CLI) — pick the mode first

Two ways to create/manage the same Cargo resources. Decide which the task wants before picking a domain:

  • Declarative → cargo-project. The user is managing resources as an artifact: "set up / bootstrap a whole workspace in a project", "make this reproducible / version-controlled / in git", "deploy these connectors + models + agents together", or anything that should be re-runnable and diffable across environments. Define it in define* files and cargo-ai project deploy.
  • Imperative → the matching capability skill below. The user is doing a one-off operation or exploring: "create one connector", "add a column", "list connectors", "run this workflow", "query storage", "read a memory". A read, ad-hoc query, or single mutation that needn't live in code.

When unsure: should the result be committed and re-deployable? Yes → a project. A quick action or a read → the capability skill.

Onboarding skill

Load for a brand-new user or an empty workspace.

Skill Load when you need to…
cargo-quickstart Run the guided first-run demo: one menu question → 25 real rows in under two minutes → cost receipt → save as a recurring play. Routes to cargo-gtm afterwards.

Outcome skill

Load when the user states a real-world goal.

Skill Load when you need to…
cargo-gtm (recap) Any GTM task — sourcing, enrichment, verification, scoring, sequencing, CRM sync, signal monitoring (job changes, funding, tech-stack/hiring intent). Routes via recipes (recipes/), guides (guides/), and provider playbooks (provider-playbooks/).

Capability skills

Load for a specific CLI domain. The first link in each row jumps to the actual SKILL.md; the parenthetical jumps to the recap on this page.

Skill Load when you need to…
cargo-orchestration (recap) Execute actions, run workflows, trigger batches, chat with agents, query orchestration with SQL (ClickHouse)
cargo-analytics (recap) Download run results, export segment data, monitor error rates and metrics
cargo-billing (recap) Check credit usage, view subscription details, track costs per workflow or connector
cargo-diagnostics (recap) Diagnose after the fact: trace why one run misbehaved, sweep a batch/play for errors grouped by root cause, profile where a play's credits go
cargo-observability (recap) Create and manage alerts — scheduled threshold checks on spans/runs/records, a model's health, or a SQL query — that fire actions (connector/tool/agent runs) on breach. Proactive counterpart to diagnostics
cargo-storage (recap) Inspect or modify data models, columns, datasets, and relationships; query workspace storage with SQL
cargo-segmentation (recap) Build and manage segments — the saved filters that name the audience for a batch, a play trigger, or an export — and read their change (delta) feed
cargo-connection (recap) Manage connector authentication, discover available integrations and their actions
cargo-ai (recap) Create and configure agents, configure releases, attach knowledge for RAG, manage MCP servers and memories
cargo-content (recap) Upload and organize knowledge files, build native/connector-backed knowledge libraries for RAG, and store/serve any file by path with a signed or public link (the content domain)
cargo-context (recap) Browse/read/write/edit the workspace's git-backed GTM context repo, run commands in its runtime sandbox, inspect the knowledge graph
cargo-hosting (recap) Scaffold, deploy, and promote hosted apps (Vite SPAs) and edge workers (serverless HTTP handlers), manage their deployments, and give workers env vars and secrets
cargo-project (recap) Declarative — spans every resource type. Declare a whole workspace in a project (define* builders) and deploy it with cargo-ai project (init → types → plan → deploy). Use for GTM as Code / reproducible / version-controlled setups; see "Declarative vs imperative" above.
cargo-mailbox-management (recap) Provision sending mailboxes Cargo owns, run warm-up and the 5→40/day send ramp, send with the sendEmail action, and read threads, replies, delivery events, and suppressions
cargo-workspace-management (recap) Invite users, create API tokens, organize folders, manage roles, report CLI issues to management
cargo-mcp (recap) Drive Cargo from the hosted MCP server at https://mcp.getcargo.io/mcp with no CLI install — connect a client, discover and price an action, execute one record or a batch, poll it, read models; and route between the MCP tools and the CLI

Agent knowledge for RAG: files + libraries live in the content domain → cargo-content; how they attach to an agent → cargo-ai. (Files/libraries moved out of the old ai file … path in CLI ≥ 1.0.19.)

These skills vs an MCP server

Three distinct things wear the name MCP here. They share no answers, so establish which one is meant before replying:

What it is Skill
Hosted server Cargo's own endpoint at https://mcp.getcargo.io/mcp. Seventeen fixed platform tools (discover, price, execute, poll, read models, read context, usage). A workspace's curated servers are served separately, at /v1/ai/mcpServers/<uuid>/mcp. The way to drive Cargo with no CLI installed. cargo-mcp
Workspace server A curated set this workspace publishes (ai mcp-server create --actions … --resources …), served to any stdio client by cargo-ai mcp. cargo-ai
Agent MCP client Somebody else's MCP server attached to a Cargo agent (release update-draft --mcp-clients). cargo-ai

The first is new and is what "does Cargo have an MCP server?" now means. It authenticates by OAuth discovered from its own 401 challenge, or by a workspace-scoped bearer token:

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

The second is the curation path, and remains the right answer when a workspace wants to expose one approved tool rather than the whole platform:

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

With no --server, the bridge uses CARGO_MCP_SERVER_UUID when set, otherwise the platform /mcp. (Older CLIs instead fell back to "the workspace's only MCP server" and failed outright when there wasn't exactly one.)

Route between the CLI and either MCP surface by shape of the request:

These skills (CLI) An MCP server
What it is The whole CLI surface, every domain The platform runtime tools, plus whatever the workspace chose to expose
Best for Anything that builds something reusable: workflows, plays, schema changes, project deploys, diagnostics, exports, warehouse SQL In-conversation execution: look this record up, enrich this list, run this one approved tool
Cost control Full pilot → approval → receipt discipline (../cargo-gtm/references/cost-discipline.md) Per-call; search_actions returns each action's credit cost before you run it
Reproducible Yes — commands, plays, and project files are artifacts No — a tool call leaves no artifact behind

Rule of thumb: anything the user will want to re-run or version belongs in the CLI. Never fan an MCP tool out record-by-record over a list — that is what execute_action_batch (and orchestration action execute-batch on the CLI) exists for, and it is cheaper and observable. Conversely, when the workspace has already curated a tool for a job, calling it beats hand-assembling the same thing from raw actions.

CLI domains without a dedicated skill yet

The CLI exposes several domains that no capability skill wraps yet. Reach for them directly (cargo-ai <domain> --help) when a task needs them, and file a workspaceManagement report if the surface is unclear:

CLI domain Covers
expression The template / JS expressions node configs are written in. eval evaluate --expression '<json>' --variables '<json>' resolves one against sample variables (the quickest check on a {{…}} before a run), and eval generate --prompt "…" --variables '<json>' drafts one from plain English. Recipes are saved, reusable expressions: 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 pins one for the workspace.
system-of-record The warehouse the workspace's storage lives in (bigQuery or snowflake). sor list\|get\|create --kind … --config '<json>'\|update\|remove; sor migrate <uuid> applies Cargo's pending schema migrations to that warehouse, in order, stopping at the first that fails; sor cutover <uuid> moves the workspace onto that system of record, copying its tables across in the background (one cutover per workspace at a time). Both are admin operations on live storage — confirm before running either. client query "<sql>", client fetch, client download and client get-documentation <slug> talk to the warehouse directly; log list / log get-metrics read its sync logs. For everyday SQL over models, storage query execute (cargo-storage) is the right door.
revenue-organization Territory and capacity planning for a sales team: member list\|get\|update\|archive\|unarchive and member sync --connector-uuid <crm-connector> (pull reps from the CRM), territory list\|get\|create\|update\|remove, capacity list\|get\|create\|update\|remove, and allocation list\|get\|remove — the assignments the native allocate action ({"kind":"native","actionSlug":"allocate"}, "choose members of your team") writes when a workflow routes a record to a rep.
user-management Current-user operations with no workspace context.

Top-level commands outside every domain

Five commands sit at the root of the CLI rather than under a domain, and no skill wraps them. They are listed here so you recognize them when a user names one — not as a routing target:

Command What it is
cargo-ai doctor Diagnoses the setup in one JSON object: installed version vs latest, the skills-bundle pin, credentials, and API reachability. Exits with the most severe failure. It also lists skills-missing when no agent skills are found (fix: npx skills add getcargohq/cargo-skills) without changing the exit code; the plugin install, under the cargo-skills marketplace, counts as installed from cdk 1.0.134. The fastest answer to "why is this command not working" before you start reading skills.
cargo-ai start (alias onboard) Signs the user in if needed, then continues into one of: a coding agent (--continue claude\|cursor\|codex\|gemini), code to scaffold a project, cli for the palette, or demo for the guided tour. Takes --email/--code/--oauth, --workspace-name, --directory, --icp.
cargo-ai ask Chat in the terminal. Defaults to Claude Code on this machine against the working directory (--dir); --agent-uuid attaches a workspace agent to that same local session. --print gives one turn as JSON on stdout, --continue reopens the last chat. Also reachable as cargo-ai --chat.
cargo-ai book-demo Opens the calendar to book a demo with Cargo sales. --no-open prints the URL instead.
cargo-ai (bare) The interactive palette, when the terminal can render it. Bare cargo-ai project prints the group help; it does not run info or init.

Two of these overlap work the skills describe by hand: doctor is a better first step than hand-checking the pin, and start --continue demo is the CLI's own version of the cargo-quickstart tour. Prefer the skill when you want control over what gets spent; prefer the command when the user just wants it done.


How the skills relate

            ┌─────────────────────────────────────┐
            │              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)

Dependency rules in practice:

  • cargo-gtm delegates to capability skills via relative paths (../cargo-orchestration/...). Capability skills never reference cargo-gtm.
  • cargo-workspace-management provides auth context for every skill — set it up first.
  • cargo-storage, cargo-connection, and cargo-ai are peer skills that supply UUIDs to cargo-orchestration. They don't depend on each other.
  • cargo-content owns workspace files and libraries (the content domain). It produces file/library UUIDs that cargo-ai consumes as agent release resources (RAG), and it is also the file store: write and read by path, list a folder, hand out a signed or public link — from the CLI, a worker (createCargoObjects), a play (writeFile/readFile/getFileUrl nodes) or an agent (a writable folder). Files with mirrorToContext: true (the default for uploads and defineFile, not for path writes) are also committed to the context repo under .files/, read-only from the cargo-context runtime.
  • cargo-mailbox-management owns sending inboxes (the mailboxManagement domain) — provisioning, warm-up, the send ramp, threads, events, and the workspace suppression list. It deliberately does not send: delivery is the sendEmail native action under cargo-orchestration, which is why a send inherits orchestration's pacing, retry and credit accounting. The mailbox itself is also declarable in a project via defineMailbox (with defineDomain for the sending domain).
  • cargo-project is cross-cutting: it's a declarative authoring mode that produces the very connectors/models/plays/agents/etc. the imperative capability skills manage one at a time. Route to it when the task is "manage the workspace from a project" (GTM as Code: reproducible, in git, multi-resource); route to the imperative domain skills for one-off ops, reads, and ad-hoc queries. See "Declarative vs imperative" under Skills at a glance.
  • cargo-context is orthogonal to the workflow-execution flow. It touches the git-backed GTM knowledge base (markdown/MDX), not storage or workflow runs. Use it for capturing/editing the workspace's prose context — personas, plays, proof, objections, signals — and for inspecting the typed knowledge graph.
  • For SQL queries against storage, use cargo-ai storage query execute "<sql>" (tables as <datasetSlug>.<modelSlug>). Load cargo-storage to discover dataset and model slugs, and to fetch the DDL when you need column types or the SQL dialect.
  • For SQL queries against orchestration runtime tables (runs, batches, spans, records) — error rates, per-node failures, time-series — use cargo-ai orchestration query execute "<sql>". Workspace scoping is automatic; tables are referenced without a schema prefix.
  • Before building a workflow node graph, load cargo-connection to get connectorUuid and actionSlug. If any node calls a credits-based provider action, also load cargo-gtm and read that provider's playbook (../cargo-gtm/provider-playbooks/<slug>.md) — including its Recurring use section whenever the workflow is a scheduled tool or play, since a bad config or wrong cadence re-bills on every run. This applies even when the task arrived through cargo-orchestration or cargo-project directly, without a GTM framing.
  • Before executing a workflow that uses an agent node, load cargo-ai to get agentUuid.
  • After runs complete, load cargo-analytics to download results or measure performance. For action output retrieval, prefer cargo-ai orchestration run download-outputs over run download — the former returns a signed-URL CSV/JSON of just the output node's data.
  • Load cargo-billing to understand credit consumption for any of the above.
  • When a run failed, a run "succeeded but looks wrong", a batch has errors, or a play costs too much, load cargo-diagnostics — it sequences the run get / orchestration-SQL / billing surfaces into forensic runbooks (trace one run, sweep a batch, profile credit spend).
  • To be told about a problem before you go looking — an error-rate spike, a cost ceiling, a slow node, a stalled sync, a workflow that stopped running — load cargo-observability. It creates alerts: scheduled threshold checks over the same telemetry (spans/runs/records), a model's health, or a SQL query, that fire actions on breach. Diagnostics is reactive (explain what happened); observability is proactive (watch for it). Alerts can also be declared in a project via defineAlert.

Per-skill critical rules

The non-obvious rules for each skill — the things that fail silently or cost money if you guess. Each skill's own SKILL.md carries the full surface; these are the ones worth knowing before you pick.

cargo-gtm

Recipes shipped:

Recipe Use when…
recipes/source-planning.md Decide the source before spending: probe candidates, cost per hit.
recipes/prospecting.md End-to-end find → enrich → verify → sync (P1/P2/P3 variants).
recipes/build-tam.md Build a Total Addressable Market list at scale (100–10,000 companies).
recipes/sales-navigator-extraction.md Extract a Sales Navigator search past the 1,000-account / 2,500-people cap.
recipes/find-stakeholders.md Find the buying committee at a named account by title, seniority and department.
recipes/score-leads.md Score and tier a company list against the ICP, with the reason on every row.
recipes/research-account.md Brief one account before a meeting, every line traced to a source.
recipes/monitor-buying-signals.md Watch target accounts for dated, linked buying signals, free rung first.
recipes/linkedin-url-lookup.md Resolve LinkedIn URL from name + company with strict validation.
recipes/portfolio-prospecting.md Investor / accelerator → portfolio companies → contacts.
recipes/job-change-monitoring.md waterfall.detectJobChange (cargo-unique) on a contact segment.
recipes/funding-watch.md Track companies that recently raised funding.
recipes/tech-intent.md Find companies by tech-stack or hiring-intent signals.
recipes/icp-discovery.md Diff Closed-Won vs Closed-Lost segments, surface ICP signals.
recipes/custom-datapoints.md Design which custom attributes + live signals to collect, gated on a real source and cost.
recipes/outreach-activation.md Turn a signal segment into send-ready outreach (enrich → verify → personalize → sequencer handoff).
recipes/ads-audience-activation.md Push a segment to Google Ads Customer Match / LinkedIn Matched Audiences.
recipes/review-and-iterate.md Human review loop for judgment output; corrections become permanent rules.
recipes/re-engagement.md Wake up stale contacts only when a fresh signal fires (job change, funding, tech intent).
recipes/lost-deal-revival.md Revive Closed-Lost CRM deals by branching on lost_reason (champion left, budget, timing).
recipes/account-expansion.md Multi-thread customer accounts — net-new buyers, deduped against the Contacts model.

Priority provider stack (recipes lead with these): salesNavigator (sourcing), aiArk (LinkedIn-anchored enrich + the catalog's cheapest company enrich and search), waterfall (multi-source enrichment + email verify + job-change), FullEnrich (premium contact lookup), apolloio (1-credit niche-coverage enrich), theirStack (tech-stack + hiring intent), peopleDataLabs (heavyweight backfill). Already have LinkedIn URLs (or an event URL)? Don't source — go straight to aiArk.enrichPerson (0.1, profile + verified email, bills 0 on no-email), or linkedin (enrichProfile/enrichCompany 0.25, extractEventAttendees) when you don't need the email; these are the cheapest URL-anchored enriches and easy to miss because the stack above is sourcing-first.

Critical rules:

  • Acceptable use gates every step that touches a person (../cargo-gtm/references/acceptable-use.md): B2B professional identities from licensed providers only, three free blocking checks before any outreach step (basis, suppression, relevance), and a refusal list — undifferentiated fan-out, consumer targeting, lists with no stated origin, contacting a suppressed record, filter or identity evasion, auto-dialing, batch-blasting LinkedIn engagement actions, batch or automated posting / replying / liking / DMing from the user's X account (xAccount). The pack never sends: outreach stops at send-ready variables for the user's own sequencer.
  • All recipes use credits-based actions — 190 of the 594 the catalog exposes, priced in ../cargo-gtm/references/credits-cost-table.md and regenerated from cargo-ai orchestration action list --kind connector / --kind native (free, reads the catalog), which return a credits array on every billed action. The other 404 actions carry no provider price — but nothing that runs in a workflow is free: every node execution bills 0.01 credits (1 per 100), structural natives (branch, filter, switch, variables) included. The cost table prices actions, not steps; see ../cargo-billing/SKILL.md → "The execution charge".
  • Action shape: {"kind":"connector","integrationSlug":"<slug>","actionSlug":"<slug>"} — no config on a top-level action, and connectorUuid is never nested inside one; it sits at the top level of a node.
  • Output retrieval: cargo-ai orchestration run download-outputs --output-node-slug <slug> (NOT run download).
  • peopleDataLabs filter shape: searchX uses cargo's {conjonction, groups, conditions} shape; queryX takes a PDL SQL string — never Elasticsearch.

cargo-orchestration

Critical rules:

  • See the decision flowchart at the top of ../cargo-orchestration/SKILL.md for when to use action execute vs run create vs batch create.
  • Never enroll a full batch on the first attempt. batch create / action execute-batch fan out across every record in the source. Sample 10–20 records, report observed cost + hit-rate, then ask the user to approve the full enrollment — quoting the record count and the credit estimate. Mechanics: ../cargo-orchestration/SKILL.md → "Create a batch"; spend rules: ../cargo-gtm/references/cost-discipline.md §1.
  • Search for the action; never browse the catalog for it. cargo-ai orchestration action list <keywords> [--kind connector|native|tool|agent] [--integration-slug <slug>] [--limit 20] covers the integration catalog, Cargo native actions, workspace tools, and agents in one free call, and returns a ready-to-paste action object (connectorUuid resolved) plus the action's credit costs. Its sibling cargo-ai connection action search <keywords> is connector-only but adds --credits-only, the one filter action list lacks. Both beat paging connection integration list; reach for integration get <slug> only once you have picked the action and need its full input schema.
  • Omit config on action execute / action execute-batch — inputs go in --data / --records. That is the shape action list returns, so its result pastes straight in. action get-output-schema takes the same shape (inputs, when its schema depends on them, in --data). Workflow nodes, alert --actions, play healthAlertActions, and agent / MCP-server --actions still carry config. Inputs misplaced in config are stripped without an error that names config, so they never arrive: an action with a required input is refused before it runs on that missing field, one without runs on nothing. A misspelled or undeclared input key is refused before the run is created (invalidData, Unknown field: <key>, nested keys included; in a batch one bad record refuses the whole batch) — except on tool actions, extra top-level batch columns, and inside workflow nodes, where an unknown key is still dropped silently.
  • action execute is the default for running an operation; node execute is debug-only. Use node execute only to test a single node of a workflow you're authoring — it requires --workflow-uuid, --release-uuid, --node, --computed-config and --context (all five). Anything else — enrich a record, call a connector action, invoke a tool or agent — goes through action execute / action execute-batch.
  • Build node graphs from dedicated actions + expressions, in this order: (1) a dedicated action, found first with orchestration action list <keywords> (connector actions, and native ones like agent, modelUpsert, branch, group); (2) an expression for the glue, since it's inline JavaScript in the field that needs the value; (3) HTTP, only if no action exists for that API; (4) a script/python node, only if the logic can't fit in an expression. See ../cargo-orchestration/references/node-selection.md.
  • Show a node graph, don't describe it. Before deploying a draft, and whenever the user asks what a workflow or play does: cargo-ai orchestration node diagram --workflow-uuid <uuid> --raw (free, runs nothing, CLI ≥ 1.0.54; references/node-diagram.md). Routing, fallback edges, and which nodes bill are what's being approved. Let the command draw it rather than transcribing — node slugs repeat within a release, so a hand-drawn diagram keyed on slug merges nodes that aren't the same.
  • Filter JSON uses conjonction (not conjunction). It is a required key, so a misspelling is rejected with a 400.
  • Query orchestration runtime tables (ClickHouse) with cargo-ai orchestration query execute "<sql>" against runs, batches, spans, records (no schema prefix; workspace scoping is automatic).
  • For SQL against workspace storage (Companies, Contacts, …), use cargo-ai storage query execute "<sql>" — documented in cargo-storage.
  • All operations are async — poll or pass --wait-until-finished. See Async polling.

cargo-analytics

Critical rules:

  • segment download requires --model-uuid, not --segment-uuid.
  • For batch result download, get the output-node-slug from release get <release-uuid> → nodes[].slug.
  • For billing and credit usage, use cargo-billing instead.
  • Analytics answers "what happened" (metrics, counts, exports). When the question is why — a failing run, a batch full of errors, surprising cost — hand off to cargo-diagnostics; its sweep runbook picks up exactly where analytics' error counts leave off.

cargo-billing

Critical rules:

  • Requires a token with admin access.
  • Invoice amounts are in cents — divide by 100 for dollars.
  • subscriptionAvailableCreditsCount + additionalAvailableCreditsCount - subscriptionCreditsUsedCount from subscription get (under .subscription) = remaining credits.
  • Every node execution bills 0.01 credits (1 per 100) — structural natives included, errored executions included. It is attributed to no node (executions[].creditsUsedCount is provider cost only), so any estimate or per-node profile built without it under-counts. Only usage get-metrics --unit orchestration.executions shows it; --unit takes exactly billing.credits / orchestration.executions / storage.records / hosting.events, and with no --unit those four interleave in one items[] array with different meanings for count.

cargo-diagnostics

Critical rules:

  • Start with the sweep when you don't know which run to look at; it ends with exemplar UUIDs for the trace. With no UUID at all, orchestration trace list --started-after <iso> --statuses error,degraded lists what failed, one row per trigger across child runs; span list / span count filter node executions by batch, provider, action or error text without SQL. Both need a start date (--started-after / --execution-started-after).
  • degraded means a fallback absorbed a failure — the run succeeded, a node errored. Sweep it together with error.
  • runContext is the source of truth for what a node produced; an execution's title is a truncated summary — never evidence.
  • Credit attribution (billing …) needs an admin token; the SQL and run get steps don't.
  • Any fix that re-runs paid nodes goes through the pilot gate in ../cargo-gtm/references/cost-discipline.md.
  • Diagnostics explains; it doesn't export. For bulk retrieval after the diagnosis (run download-outputs, batch download, segment download) go back to cargo-analytics.
  • Present conclusions first, evidence as compact tables — per references/interaction.md (in the cargo router skill).

cargo-observability

Critical rules:

  • preview before create. alert preview --scope … --threshold … [--window-minutes 60] evaluates now without firing — the only way to size a threshold against reality and to catch an invalid scope/threshold pairing (outcome: "notComputed") before it becomes a schedule that errors every tick.
  • Scope and threshold are a matched pair. Telemetry metrics (errorRate, duration+aggregation, credits+aggregation, count) need spans/runs/records; query needs a query scope; recordsCount/recordsShare/freshness/syncDuration need model. Full matrix + units in references/scopes-and-thresholds.md.
  • Empty window vs real zero. Most metrics report an idle window as empty (healthy, no fire). Only count and recordsCount return a real 0 — pair with lte 0 for a dead-man's switch (alert when a workflow stops, a model empties).
  • Firing is at-most-once and costs credits. Actions fire as runs (runUuids on the event); a sustained breach re-fires once per tick it's still true, never on the same rows twice. If an action calls a paid provider, apply ../cargo-gtm/references/cost-discipline.md — a scheduled alert re-bills on every breach.
  • --enabled is strict (true/false only); model-scope filter uses the segmentation shape spelled conjonction.
  • Permissions are observability:read / observability:write (not admin-only). The declarative equivalent is a project's defineAlert — see cargo-project.

cargo-storage

Critical rules:

  • Query via cargo-ai storage query execute "<sql>" (or storage query download --query "<sql>" for full exports) using <datasetSlug>.<modelSlug> table names (e.g. default.companies). model get-ddl is optional — useful for column types and SQL dialect.
  • For SQL against orchestration runtime tables (runs/batches/spans/records), use cargo-ai orchestration query execute "<sql>" — documented in cargo-orchestration.
  • For advanced record queries (filtering, sorting, pagination), use segmentation segment fetch — documented in cargo-segmentation.
  • storage relationship set replaces the dataset's whole relationship set — anything absent from the payload is deleted. list first, send the full array back.

cargo-segmentation

Critical rules:

  • Filter JSON uses conjonction (not conjunction). It is required at the filter and the group level, so a misspelling is rejected with a 400, and a group with conditions: [] is rejected too.
  • Size before you spend. segment fetch --fetching-limit 1 counts an inline filter for free (read count; --limit caps the membership itself, so --limit 1 reports 1); a saved segment's recordsCount is the authoritative size. Quote it before proposing any paid run over the audience.
  • segment download takes --model-uuid plus the filter, never --segment-uuid.
  • change list needs --segment-uuid; change fetch needs the change UUID plus --kinds (added/updated/removed/unchanged).
  • updatedRecordsCount stays 0 unless the segment was created with --tracking-column-slugs — those columns define what "updated" means.
  • Segments named GENERATED_PLAY_SEGMENT (fromPlay: true) are owned by a play. Never edit or remove them by hand.

cargo-connection

Key concepts:

  • Integration = external service type (HubSpot, Clearbit, Salesforce, …)
  • Connector = authenticated instance of an integration (referenced by connectorUuid in nodes)

cargo-ai

Critical rules:

  • Knowledge for RAG attaches to an agent via the release's resources: files + libraries come from cargo-content. Wire them in with release update-draft --resources … then release deploy-draft.
  • cargo-ai mcp with no --server now bridges the first-party platform MCP (mcp.getcargo.io/mcp), not "the workspace's only MCP server". ai mcp-server still builds a curated server; pass its uuid with --server. See "These skills vs Cargo's MCP surfaces" above.
  • A coding agent (--harness-slug + --repository on a release or a new chat) pushes as the Cargo GitHub app, which must be installed on the repo; its token is scoped to that repo, it works on cargo/<name> branches and never pushes the default branch, and a mention on its PR continues the chat. Harness and repository are fixed when a chat is created — passing them with --chat-uuid is refused.
  • CLI ≥ 1.0.19: files and libraries moved out of the ai domain into the top-level content domain (now the cargo-content skill). The old cargo-ai ai file … commands no longer exist.

For using agents (sending messages, multi-turn chat, polling), use cargo-orchestration.

See ../cargo-ai/SKILL.md for model and temperature guidance by use case.

cargo-content

Critical rules:

  • New top-level content domain in CLI ≥ 1.0.19 — cargo-ai content file … / cargo-ai content library …. The old cargo-ai ai file … path is gone (unknown command → you're on the old path; bump the CLI).
  • A file or library is inert until attached to an agent's deployed release resources — that wiring lives in cargo-ai.
  • upload and put default differently. upload (and defineFile) indexes the file for agent search and mirrors it into the context repo under .files/ (committed and pushed); content file put and every other path write store it only — not searchable by an agent until written with --index vectorStore, and not in git.
  • Links are unauthenticated. content file url returns a signed link anyone can open until it expires (default 1 h, max 3 h); a public file has a stable no-auth link until made private. Share either only when the user asked to share that file.
  • For batch-run input files (CSVs that drive a batch), use cargo-ai workspaceManagement file upload (a different surface) — see cargo-workspace-management.

cargo-context

Key concepts:

  • Context repository = the GitHub repo backing the workspace's context. Canonical example: getcargohq/cargo-workspaces. Files use kebab-case.md names, YAML frontmatter with required title + description, and domain/slug cross-refs (no .md).
  • Runtime sandbox = a checked-out, executable copy of the context repo. runtime write and runtime edit push to the default branch; runtime execute does not push.
  • Knowledge graph = the typed graph over every md/mdx file, with frontmatter and outbound cross-refs per node. Built via cargo-ai context graph get.

Critical rules:

  • runtime write / runtime edit commit and push. runtime execute is ephemeral — use it for grep/ls/inspection, never for persistent changes.
  • runtime edit --old-string must match the file content exactly once (unless --replace-all). Read first, copy whitespace verbatim.
  • Set title + description frontmatter on every .md/`.m
Files (cargo-skills)
  • references
    • glossary.md 27.2 KB
      Loading…
    • gotchas.md 13.9 KB
      Loading…
    • interaction.md 6.8 KB
      Loading…
    • prerequisites.md 6.1 KB
      Loading…
    • use-cases.md 5.2 KB
      Loading…
    • uuid-flow.md 3.4 KB
      Loading…
  • cli-version 8 B · in bundle
  • skill-metadata.json 1.2 KB
    Loading…
  • SKILL.md 74 KB
    ---
    name: cargo
    description: "Entry point for Cargo (getcargo.ai), go-to-market infrastructure for AI agents. With Cargo an agent builds B2B lead lists, finds and verifies work emails, enriches companies and contacts, qualifies leads, syncs the CRM and watches buying signals, then runs any of it on a schedule. New accounts get 100 free credits, no card. Routes each job to the right Cargo skill and holds the rules that apply across all of them (project vs one-off CLI, run vs batch, async polling, silent-failure gotchas). Triggers: \"set up Cargo\", \"what can Cargo do\", \"what is Cargo\", \"which Cargo skill\", \"bootstrap my workspace\", \"I have a Cargo account\", \"cargo-ai …\", any `cargo-ai` command whose domain is unclear, or a task spanning two Cargo domains. Skip when: the task obviously belongs to one skill; load that skill directly."
    version: "1.36.6"
    compatibility: Requires @cargo-ai/cli (npm). Sign in or create an account with `cargo-ai login --email` (emailed code, no browser), `--oauth`, or an API token
    homepage: https://github.com/getcargohq/cargo-skills
    metadata:
      author: getcargo
      openclaw:
        requires:
          bins:
            - cargo-ai
        install:
          - kind: node
            package: "@cargo-ai/cli@latest"
            bins:
              - cargo-ai
        homepage: https://github.com/getcargohq/cargo-skills
    ---
    ```
    ██████    ████    █████    ██████   ██████
    ██    ░  ██  ██░  ██  ██   ██    ░  ██  ██░
    ██       ██████░  █████ ░  ██ ███   ██  ██░
    ██       ██  ██░  ██ ██    ██  ██░  ██  ██░
    ██████   ██  ██░  ██  ██   ██████░  ██████░
     ░░░░░░   ░░  ░░   ░░  ░░   ░░░░░░   ░░░░░░
    ```
    
    # Cargo CLI — Skills Overview
    
    This repository contains 19 skills at the repo root: this **router** (`cargo`), one **onboarding skill** (`cargo-quickstart`), one **outcome skill** (`cargo-gtm`), and sixteen **capability skills**.
    
    - **`cargo-quickstart`** — guided first-run demo. Fresh workspace → real deliverable (25 rows from a fixed starter menu: lookalike companies, a persona, or fast-growing companies, with a cost receipt) in under two minutes, needing nothing connected, ending by saving the search as a recurring play. Load for new users, demo/tour requests, or empty workspaces.
    - **`cargo-gtm`** — application library. The front door for any GTM task ("build a TAM list", "find 5 fintech CTOs", "monitor job changes"). Routes via internal recipes (`../cargo-gtm/recipes/*.md`) and provider playbooks (`../cargo-gtm/provider-playbooks/*.md`).
    - **Capability skills** — standard library. One per CLI domain (orchestration, storage, segmentation, connection, AI, content, context, analytics, billing, observability, hosting, project, mailbox management, workspace management), plus `cargo-diagnostics` (cross-domain forensics over runs, batches, and credit spend) and `cargo-mcp` (the hosted MCP server, the one surface that is not the CLI). Loaded by `cargo-gtm`, or directly when you need a specific CLI domain.
    - **`cargo-project`** — the declarative one. Where the other capability skills wrap **imperative** one-off `cargo-ai <domain>` calls, `cargo-project` declares the whole workspace in a project — the folder holding `cargo.json` (`define*` builders + `cargo-ai project deploy`) — and reconciles it. It spans every resource type — see "Declarative vs imperative" below to route between it and the imperative skills.
    
    `cargo-gtm` delegates to capability skills; capability skills never reference `cargo-gtm` (one-way dependency).
    
    **Glossary:** See [`references/glossary.md`](references/glossary.md) for term-by-term definitions (UUIDs, slugs, `conjonction`, run/batch/play/tool, signal/persona/ICP, etc.).
    
    **Interaction conventions:** See [`references/interaction.md`](references/interaction.md) for the pack-wide defaults on when to stop and ask (plan gate before building, recommended-default choices) and how to present results (narrate, summarize — never dump raw JSON).
    
    ## Installation
    
    ```bash
    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 you@company.com            # sends the code, then exits
    cargo-ai login --email you@company.com --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 you@company.com --workspace-name "Acme GTM"
    
    # Verify
    cargo-ai whoami
    ```
    
    **Look before signing up.** With no account at all, `cargo-ai orchestration action list <keywords>`, `connection integration list|get` and `orchestration action execute … --dry-run` (connector and native actions: validates `--data`, prints sample output in the finished-run shape with the credit price, calls nothing) work against the public catalog; `project plan` and `project types` do too.
    
    **A new account starts with 100 free credits, valid for its first 30 days, and needs no card**, so an agent can sign a user up and produce a real deliverable in the same turn — there is no purchase gate between install and first value. Useful anchors for what that buys: ~500 leads sourced (`salesNavigator.searchLeads`, 0.2/record), ~1,000 profile+verified-email enriches (`aiArk.enrichPerson`, 0.1), ~1,000 email verifications (`waterfall.verifyEmail`, 0.1), or ~50 fully enriched contacts (`waterfall.enrichContact`, 2). The [quickstart demo](../cargo-quickstart/SKILL.md) spends at most **1.25**. Say the free balance out loud before the first paid call on a new account.
    
    Every sign-in path (CLI ≥ 1.0.136) then offers to install these skills with a y/N when they're missing, says nothing when they're present, and only prints the install command where there is no terminal. The installer's output goes to stderr, so the sign-in JSON on stdout stays clean.
    
    `--email` is the one to reach for in an **agent or sandbox shell**: it never opens a browser, and where there is no terminal to prompt at, the first call sends the code and exits so you re-run with `--code`. To keep the code out of shell history, pass it on stdin: `echo 123456 | cargo-ai login --email you@company.com --code -`. Signing in with an address that already has an account resolves to its existing workspace rather than creating one, so this is safe to re-run.
    
    **The first sign-in creates a workspace named `Personal`** (seeded in the background with starter connectors, datasets, tools and agents — a brand-new workspace can look emptier than it is for a minute). `--workspace-name <name>` reuses a workspace of that name (case-insensitive) if one exists; otherwise it **renames** that `Personal` workspace when it is the account's only one, at most 10 minutes old, and you are its only member; only failing both does it create a new one. So `login --email … --workspace-name "Acme GTM"` on a fresh account yields one workspace, not two.
    
    `--oauth` runs the same OAuth 2.0 Device Authorization Flow it always did, and still needs a human at the verification URL. `--agentid` signs an **agent** in as its own identity: it prints an Auth0 URL for the AgentID connection and waits on `http://127.0.0.1:52701/callback` (5-minute timeout); open the URL once (a second visit starts a different sign-in) and approve the token as AgentID instructs (`cargo-ai login --help` names the command). `--email`, `--oauth` and `--agentid` all save a self-renewing session to `~/.config/cargo-ai/credentials.json` (the system temp dir where home isn't writable — it lasts as long as the sandbox). Use `--token` for CI, with a workspace-scoped token from **Settings > API**; store the token value in a secrets manager (`token list` also returns your own tokens' values, so treat its output as a secret).
    
    Without a global install, prefix every command with `npx @cargo-ai/cli` instead of `cargo-ai`.
    
    These skills also install as a native **agent plugin** for Claude Code, Codex, Cursor, Grok Bot, and Grok Build (one repo, four plugin formats). Every target gets the same skills and a host-appropriate guarded approval hook; Claude Code also gets session-lifecycle hooks. See the repo `README.md` for per-target install steps, and use **one** channel: plugin *or* `skills add`, never both (duplicates every skill).
    
    All commands output JSON to stdout. Failed commands exit non-zero and print `{"error": "...", "status": ..., "body": {...}}` to stderr (the API's own `errorMessage` sits inside `body`). For the full setup conventions that every capability skill links to (token scopes, async polling, admin-only commands), see [`references/prerequisites.md`](references/prerequisites.md).
    
    ## Every Cargo session has three jobs
    
    > **Automated on Claude Code.** Job 1 (refresh) runs on its own when the **Cargo plugin** is installed — its bundled `SessionStart` hook installs the pinned CLI and refreshes the plugin. Do it by hand only when the plugin is not installed (or on agents without lifecycle hooks). Nothing records the session: no hook and no step here sends Cargo the user's prompts, a transcript, or a summary of one. Job 2 (reporting) is always your responsibility, and so is the one **ask** in Job 3 (star the repo): a hook can print, but it can't take a Y/N.
    >
    > **Installing Cargo is the user's call, not an action you take.** The `curl … install.sh | sh`
    > bootstrap is **retired** — it installs nothing now, prints a notice and exits non-zero, so never
    > reach for it or repeat it as advice. Point the user at the plugin install in the repo
    > [`README.md`](../README.md). An agent asked to do the setup itself follows
    > `https://api.getcargo.io/INSTALL.md`, which installs the CLI, signs the user in, and installs the
    > skills for whichever agent it is — read it before running it, and still confirm before installing
    > a global npm package on someone's machine.
    
    ### 1. At session start — refresh
    
    Before any other Cargo command, refresh the CLI and skills:
    
    ```bash
    # 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)"
    ```
    
    Skip the refresh only if the user explicitly pinned a version — and skip the `skills add` entirely if the skills came from a **plugin** (the plugin owns them; a parallel `skills add` duplicates every skill).
    
    **Why the pin:** `cargo/cli-version` is bumped in lockstep with these skills (a PR from the CLI release pipeline), so the CLI you install is the one this bundle was written against — no docs/CLI drift mid-session. If the pin file is missing or unreadable, `latest` is the safe fallback. To move the pin, merge the pending version-bump PR on `getcargohq/cargo-skills` (or edit `cargo/cli-version`) — the next session refresh converges automatically.
    
    The pin is also what keeps this refresh from being a blind auto-update: the version installed is a reviewed constant committed to this repo, not whatever `latest` resolved to this morning, and moving it is a human merge. Two things follow for you as the agent. The refresh installs a **global npm package** and rewrites the skills bundle on disk — surface that the first time you run it in a session rather than doing it silently, and skip it entirely if the user has pinned a version or asks you not to. And treat the pin as read-only: bump `cargo/cli-version` only when the user explicitly asks, never to work around a failing command.
    
    ### 2. Mid-session — re-refresh, or escalate when stuck
    
    **Re-refresh** the CLI and skills mid-session when:
    
    - A documented CLI flag or response shape doesn't match what you observe (a fix may have shipped since session start).
    - The user explicitly asks ("bump cargo", "make sure I'm on latest").
    
    **Send a workspace management report** when the CLI is failing in a way the skill references and `--help` cannot resolve, the user or agent is repeatedly retrying the same command without progress, the syntax for a flag / JSON payload is unclear, or a needed capability seems missing:
    
    ```bash
    cargo-ai workspaceManagement report create \
      --title "<one-line summary of the problem>" \
      --description "<exact command(s) tried, errorMessage, expected vs actual, UUIDs involved>"
    ```
    
    Trigger conditions (any one is enough):
    
    - A command failed ≥ 2 times in a row on the same task and the cause is not obvious.
    - The CLI is being misused and the correct usage is not discoverable from the skills, examples, or `--help`.
    - A documented behavior contradicts what you observe.
    - A feature appears to be missing entirely.
    
    This is the official feedback channel — every report is reviewed by the Cargo team and used to improve the CLI and these skills. **Do not give up silently — file a report.** See `../cargo-workspace-management/SKILL.md` (Reports section) and `../cargo-workspace-management/references/examples/reports.md` for templates.
    
    ### 3. At session end — offer to star the repo
    
    A star is the **user's** endorsement, not yours. Never run the command unprompted; ask, and act only on an explicit yes. Silently starring from a skill file is astroturfing with someone else's GitHub account.
    
    Ask only when all of these hold:
    
    - The session produced a real deliverable — skip trivial sessions (a single lookup, no paid actions).
    - Nothing is still failing or unresolved. Asking after a broken session reads as tone-deaf.
    - The marker file `~/.config/cargo-ai/.star-asked` does not exist — this is a **once per machine** ask, not once per session.
    
    ```bash
    # gate
    test -f ~/.config/cargo-ai/.star-asked || echo "ask"
    ```
    
    > "Glad that worked. Want me to star `getcargohq/cargo-skills` for you? (Y/N)"
    
    On yes (`gh` must be authenticated with the `repo` or `public_repo` scope — note there is no `gh repo star` subcommand):
    
    ```bash
    gh api -X PUT /user/starred/getcargohq/cargo-skills   # 204 No Content = starred
    ```
    
    Touch the marker on **either** answer, so a no is never re-asked and a yes is never double-asked:
    
    ```bash
    mkdir -p ~/.config/cargo-ai && touch ~/.config/cargo-ai/.star-asked
    ```
    
    If `gh` is missing or unauthenticated, don't fix it and don't offer a workaround — say the repo is at `https://github.com/getcargohq/cargo-skills` and move on. This is the lowest-stakes item in the session; it never becomes a task.
    
    ---
    
    ## Skills at a glance
    
    ### Declarative (project) vs imperative (CLI) — pick the mode first
    
    Two ways to create/manage the same Cargo resources. Decide which the task wants
    before picking a domain:
    
    - **Declarative → [`cargo-project`](../cargo-project/SKILL.md).** The user is managing
      resources **as an artifact**: "set up / bootstrap a whole workspace in a project",
      "make this reproducible / version-controlled / in git", "deploy these
      connectors + models + agents together", or anything that should be re-runnable
      and diffable across environments. Define it in `define*` files and
      `cargo-ai project deploy`.
    - **Imperative → the matching capability skill below.** The user is doing a
      **one-off operation** or **exploring**: "create one connector", "add a column",
      "list connectors", "run this workflow", "query storage", "read a memory". A read,
      ad-hoc query, or single mutation that needn't live in code.
    
    When unsure: should the result be committed and re-deployable? Yes → a project. A quick
    action or a read → the capability skill.
    
    ### Onboarding skill
    
    Load for a brand-new user or an empty workspace.
    
    | Skill                                                                    | Load when you need to…                                                                             |
    | ------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------- |
    | [`cargo-quickstart`](../cargo-quickstart/SKILL.md)                       | Run the guided first-run demo: one menu question → 25 real rows in under two minutes → cost receipt → save as a recurring play. Routes to `cargo-gtm` afterwards. |
    
    ### Outcome skill
    
    Load when the user states a real-world goal.
    
    | Skill                                                       | Load when you need to…                                                                             |
    | ----------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
    | [`cargo-gtm`](../cargo-gtm/SKILL.md) ([recap](#cargo-gtm))  | Any GTM task — sourcing, enrichment, verification, scoring, sequencing, CRM sync, signal monitoring (job changes, funding, tech-stack/hiring intent). Routes via recipes (`recipes/`), guides (`guides/`), and provider playbooks (`provider-playbooks/`). |
    
    ### Capability skills
    
    Load for a specific CLI domain. The first link in each row jumps to the actual SKILL.md; the parenthetical jumps to the recap on this page.
    
    | Skill                                                                                                       | Load when you need to…                                                                             |
    | ----------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
    | [`cargo-orchestration`](../cargo-orchestration/SKILL.md) ([recap](#cargo-orchestration))                    | Execute actions, run workflows, trigger batches, chat with agents, query orchestration with SQL (ClickHouse) |
    | [`cargo-analytics`](../cargo-analytics/SKILL.md) ([recap](#cargo-analytics))                                | Download run results, export segment data, monitor error rates and metrics                         |
    | [`cargo-billing`](../cargo-billing/SKILL.md) ([recap](#cargo-billing))                                      | Check credit usage, view subscription details, track costs per workflow or connector               |
    | [`cargo-diagnostics`](../cargo-diagnostics/SKILL.md) ([recap](#cargo-diagnostics))                          | Diagnose after the fact: trace why one run misbehaved, sweep a batch/play for errors grouped by root cause, profile where a play's credits go |
    | [`cargo-observability`](../cargo-observability/SKILL.md) ([recap](#cargo-observability))                    | Create and manage **alerts** — scheduled threshold checks on spans/runs/records, a model's health, or a SQL query — that fire actions (connector/tool/agent runs) on breach. Proactive counterpart to diagnostics |
    | [`cargo-storage`](../cargo-storage/SKILL.md) ([recap](#cargo-storage))                                      | Inspect or modify data models, columns, datasets, and relationships; query workspace storage with SQL |
    | [`cargo-segmentation`](../cargo-segmentation/SKILL.md) ([recap](#cargo-segmentation))                       | Build and manage segments — the saved filters that name the audience for a batch, a play trigger, or an export — and read their change (delta) feed |
    | [`cargo-connection`](../cargo-connection/SKILL.md) ([recap](#cargo-connection))                             | Manage connector authentication, discover available integrations and their actions                 |
    | [`cargo-ai`](../cargo-ai/SKILL.md) ([recap](#cargo-ai))                                                     | Create and configure agents, configure releases, attach knowledge for RAG, manage MCP servers and memories |
    | [`cargo-content`](../cargo-content/SKILL.md) ([recap](#cargo-content))                                      | Upload and organize knowledge files, build native/connector-backed knowledge libraries for RAG, and store/serve any file by path with a signed or public link (the `content` domain) |
    | [`cargo-context`](../cargo-context/SKILL.md) ([recap](#cargo-context))                                      | Browse/read/write/edit the workspace's git-backed GTM context repo, run commands in its runtime sandbox, inspect the knowledge graph |
    | [`cargo-hosting`](../cargo-hosting/SKILL.md) ([recap](#cargo-hosting))                                      | Scaffold, deploy, and promote hosted apps (Vite SPAs) and edge workers (serverless HTTP handlers), manage their deployments, and give workers env vars and secrets |
    | [`cargo-project`](../cargo-project/SKILL.md) ([recap](#cargo-project))                                                   | **Declarative — spans every resource type.** Declare a whole workspace in a project (`define*` builders) and deploy it with `cargo-ai project` (init → types → plan → deploy). Use for GTM as Code / reproducible / version-controlled setups; see "Declarative vs imperative" above. |
    | [`cargo-mailbox-management`](../cargo-mailbox-management/SKILL.md) ([recap](#cargo-mailbox-management))        | Provision sending mailboxes Cargo owns, run warm-up and the 5→40/day send ramp, send with the `sendEmail` action, and read threads, replies, delivery events, and suppressions |
    | [`cargo-workspace-management`](../cargo-workspace-management/SKILL.md) ([recap](#cargo-workspace-management)) | Invite users, create API tokens, organize folders, manage roles, report CLI issues to management   |
    | [`cargo-mcp`](../cargo-mcp/SKILL.md) ([recap](#cargo-mcp))                                                   | Drive Cargo from the hosted MCP server at `https://mcp.getcargo.io/mcp` with no CLI install — connect a client, discover and price an action, execute one record or a batch, poll it, read models; and route between the MCP tools and the CLI |
    
    > **Agent knowledge for RAG:** **files** + **libraries** live in the `content` domain → [`cargo-content`](../cargo-content/SKILL.md); how they attach to an agent → [`cargo-ai`](../cargo-ai/SKILL.md). (Files/libraries moved out of the old `ai file …` path in CLI ≥ 1.0.19.)
    
    ### These skills vs an MCP server
    
    **Three distinct things wear the name MCP here.** They share no answers, so
    establish which one is meant before replying:
    
    | | What it is | Skill |
    |---|---|---|
    | **Hosted server** | Cargo's own endpoint at `https://mcp.getcargo.io/mcp`. Seventeen fixed platform tools (discover, price, execute, poll, read models, read context, usage). A workspace's curated servers are served separately, at `/v1/ai/mcpServers/<uuid>/mcp`. The way to drive Cargo with no CLI installed. | [`cargo-mcp`](../cargo-mcp/SKILL.md) |
    | **Workspace server** | A curated set *this workspace* publishes (`ai mcp-server create --actions … --resources …`), served to any stdio client by `cargo-ai mcp`. | [`cargo-ai`](../cargo-ai/SKILL.md) |
    | **Agent MCP client** | Somebody else's MCP server attached *to* a Cargo agent (`release update-draft --mcp-clients`). | [`cargo-ai`](../cargo-ai/SKILL.md) |
    
    The first is new and is what "does Cargo have an MCP server?" now means. It
    authenticates by OAuth discovered from its own `401` challenge, or by a
    workspace-scoped bearer token:
    
    ```bash
    claude mcp add --transport http cargo https://mcp.getcargo.io/mcp
    ```
    
    The second is the curation path, and remains the right answer when a workspace
    wants to expose one approved tool rather than the whole platform:
    
    ```bash
    claude mcp add cargo -- cargo-ai mcp                    # the platform MCP
    claude mcp add cargo -- cargo-ai mcp --server <uuid>    # a curated server instead
    ```
    
    With no `--server`, the bridge uses `CARGO_MCP_SERVER_UUID` when set, otherwise the platform `/mcp`. (Older CLIs instead fell back to "the workspace's only MCP server" and failed outright when there wasn't exactly one.)
    
    Route between the CLI and either MCP surface by shape of the request:
    
    | | **These skills (CLI)** | **An MCP server** |
    |---|---|---|
    | What it is | The whole CLI surface, every domain | The platform runtime tools, plus whatever the workspace chose to expose |
    | Best for | Anything that builds something reusable: workflows, plays, schema changes, project deploys, diagnostics, exports, warehouse SQL | In-conversation execution: look this record up, enrich this list, run this one approved tool |
    | Cost control | Full pilot → approval → receipt discipline ([`../cargo-gtm/references/cost-discipline.md`](../cargo-gtm/references/cost-discipline.md)) | Per-call; `search_actions` returns each action's credit cost before you run it |
    | Reproducible | Yes — commands, plays, and project files are artifacts | No — a tool call leaves no artifact behind |
    
    Rule of thumb: **anything the user will want to re-run or version belongs in the CLI.** Never fan an MCP tool out record-by-record over a list — that is what `execute_action_batch` (and `orchestration action execute-batch` on the CLI) exists for, and it is cheaper and observable. Conversely, when the workspace has already curated a tool for a job, calling it beats hand-assembling the same thing from raw actions.
    
    ### CLI domains without a dedicated skill yet
    
    The CLI exposes several domains that no capability skill wraps yet. Reach for them directly (`cargo-ai <domain> --help`) when a task needs them, and file a `workspaceManagement report` if the surface is unclear:
    
    | CLI domain | Covers |
    | --- | --- |
    | `expression` | The template / JS expressions node configs are written in. `eval evaluate --expression '<json>' --variables '<json>'` resolves one against sample variables (the quickest check on a `{{…}}` before a run), and `eval generate --prompt "…" --variables '<json>'` drafts one from plain English. **Recipes** are saved, reusable expressions: `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` pins one for the workspace. |
    | `system-of-record` | The warehouse the workspace's storage lives in (`bigQuery` or `snowflake`). `sor list\|get\|create --kind … --config '<json>'\|update\|remove`; **`sor migrate <uuid>`** applies Cargo's pending schema migrations to that warehouse, in order, stopping at the first that fails; **`sor cutover <uuid>`** moves the workspace onto that system of record, copying its tables across in the background (one cutover per workspace at a time). Both are admin operations on live storage — confirm before running either. `client query "<sql>"`, `client fetch`, `client download` and `client get-documentation <slug>` talk to the warehouse directly; `log list` / `log get-metrics` read its sync logs. For everyday SQL over models, `storage query execute` (cargo-storage) is the right door. |
    | `revenue-organization` | Territory and capacity planning for a sales team: `member list\|get\|update\|archive\|unarchive` and `member sync --connector-uuid <crm-connector>` (pull reps from the CRM), `territory list\|get\|create\|update\|remove`, `capacity list\|get\|create\|update\|remove`, and `allocation list\|get\|remove` — the assignments the native **`allocate`** action (`{"kind":"native","actionSlug":"allocate"}`, "choose members of your team") writes when a workflow routes a record to a rep. |
    | `user-management` | Current-user operations with no workspace context. |
    
    ### Top-level commands outside every domain
    
    Five commands sit at the root of the CLI rather than under a domain, and no skill wraps them.
    They are listed here so you recognize them when a user names one — not as a routing target:
    
    | Command | What it is |
    | --- | --- |
    | `cargo-ai doctor` | Diagnoses the setup in one JSON object: installed version vs latest, the **skills-bundle pin**, credentials, and API reachability. Exits with the most severe failure. It also lists `skills-missing` when no agent skills are found (fix: `npx skills add getcargohq/cargo-skills`) without changing the exit code; the plugin install, under the `cargo-skills` marketplace, counts as installed from cdk 1.0.134. The fastest answer to "why is this command not working" before you start reading skills. |
    | `cargo-ai start` (alias `onboard`) | Signs the user in if needed, then continues into one of: a coding agent (`--continue claude\|cursor\|codex\|gemini`), `code` to scaffold a project, `cli` for the palette, or `demo` for the guided tour. Takes `--email`/`--code`/`--oauth`, `--workspace-name`, `--directory`, `--icp`. |
    | `cargo-ai ask` | Chat in the terminal. Defaults to **Claude Code on this machine** against the working directory (`--dir`); `--agent-uuid` attaches a workspace agent to that same local session. `--print` gives one turn as JSON on stdout, `--continue` reopens the last chat. Also reachable as `cargo-ai --chat`. |
    | `cargo-ai book-demo` | Opens the calendar to book a demo with Cargo sales. `--no-open` prints the URL instead. |
    | `cargo-ai` (bare) | The interactive palette, when the terminal can render it. Bare `cargo-ai project` prints the group help; it does not run `info` or `init`. |
    
    Two of these overlap work the skills describe by hand: `doctor` is a better first step than
    hand-checking the pin, and `start --continue demo` is the CLI's own version of the
    [`cargo-quickstart`](../cargo-quickstart/SKILL.md) tour. Prefer the skill when you want control
    over what gets spent; prefer the command when the user just wants it done.
    
    ---
    
    ## How the skills relate
    
    ```
                ┌─────────────────────────────────────┐
                │              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)
    ```
    
    **Dependency rules in practice:**
    
    - `cargo-gtm` delegates to capability skills via relative paths (`../cargo-orchestration/...`). Capability skills never reference `cargo-gtm`.
    - `cargo-workspace-management` provides auth context for every skill — set it up first.
    - `cargo-storage`, `cargo-connection`, and `cargo-ai` are peer skills that supply UUIDs to `cargo-orchestration`. They don't depend on each other.
    - `cargo-content` owns workspace **files** and **libraries** (the `content` domain). It produces file/library UUIDs that `cargo-ai` consumes as agent release `resources` (RAG), and it is also the **file store**: write and read by path, list a folder, hand out a signed or public link — from the CLI, a worker (`createCargoObjects`), a play (`writeFile`/`readFile`/`getFileUrl` nodes) or an agent (a writable folder). Files with `mirrorToContext: true` (the default for uploads and `defineFile`, not for path writes) are also committed to the context repo under `.files/`, read-only from the `cargo-context` runtime.
    - `cargo-mailbox-management` owns **sending inboxes** (the `mailboxManagement` domain) — provisioning, warm-up, the send ramp, threads, events, and the workspace suppression list. It deliberately does **not** send: delivery is the `sendEmail` native action under `cargo-orchestration`, which is why a send inherits orchestration's pacing, retry and credit accounting. The mailbox itself is also declarable in a project via `defineMailbox` (with `defineDomain` for the sending domain).
    - `cargo-project` is **cross-cutting**: it's a declarative *authoring mode* that produces the very connectors/models/plays/agents/etc. the imperative capability skills manage one at a time. Route to it when the task is "manage the workspace from a project" (GTM as Code: reproducible, in git, multi-resource); route to the imperative domain skills for one-off ops, reads, and ad-hoc queries. See "Declarative vs imperative" under Skills at a glance.
    - `cargo-context` is **orthogonal** to the workflow-execution flow. It touches the git-backed GTM knowledge base (markdown/MDX), not storage or workflow runs. Use it for capturing/editing the workspace's prose context — personas, plays, proof, objections, signals — and for inspecting the typed knowledge graph.
    - For SQL queries against storage, use `cargo-ai storage query execute "<sql>"` (tables as `<datasetSlug>.<modelSlug>`). Load `cargo-storage` to discover dataset and model slugs, and to fetch the DDL when you need column types or the SQL dialect.
    - For SQL queries against orchestration runtime tables (`runs`, `batches`, `spans`, `records`) — error rates, per-node failures, time-series — use `cargo-ai orchestration query execute "<sql>"`. Workspace scoping is automatic; tables are referenced without a schema prefix.
    - Before building a workflow node graph, load `cargo-connection` to get `connectorUuid` and `actionSlug`. If any node calls a **credits-based provider action**, also load `cargo-gtm` and read that provider's playbook (`../cargo-gtm/provider-playbooks/<slug>.md`) — including its **Recurring use** section whenever the workflow is a scheduled tool or play, since a bad config or wrong cadence re-bills on every run. This applies even when the task arrived through `cargo-orchestration` or `cargo-project` directly, without a GTM framing.
    - Before executing a workflow that uses an agent node, load `cargo-ai` to get `agentUuid`.
    - After runs complete, load `cargo-analytics` to download results or measure performance. **For action output retrieval, prefer `cargo-ai orchestration run download-outputs` over `run download` — the former returns a signed-URL CSV/JSON of just the output node's data.**
    - Load `cargo-billing` to understand credit consumption for any of the above.
    - When a run failed, a run "succeeded but looks wrong", a batch has errors, or a play costs too much, load `cargo-diagnostics` — it sequences the `run get` / orchestration-SQL / billing surfaces into forensic runbooks (trace one run, sweep a batch, profile credit spend).
    - To be told about a problem *before* you go looking — an error-rate spike, a cost ceiling, a slow node, a stalled sync, a workflow that stopped running — load `cargo-observability`. It creates **alerts**: scheduled threshold checks over the same telemetry (`spans`/`runs`/`records`), a model's health, or a SQL query, that fire actions on breach. Diagnostics is reactive (explain what happened); observability is proactive (watch for it). Alerts can also be declared in a project via `defineAlert`.
    
    ---
    
    ## Per-skill critical rules
    
    The non-obvious rules for each skill — the things that fail silently or cost money if you guess. Each skill's own SKILL.md carries the full surface; these are the ones worth knowing *before* you pick.
    
    ### cargo-gtm
    
    **Recipes shipped:**
    
    | Recipe | Use when… |
    |---|---|
    | `recipes/source-planning.md` | Decide the source before spending: probe candidates, cost per hit. |
    | `recipes/prospecting.md` | End-to-end find → enrich → verify → sync (P1/P2/P3 variants). |
    | `recipes/build-tam.md` | Build a Total Addressable Market list at scale (100–10,000 companies). |
    | `recipes/sales-navigator-extraction.md` | Extract a Sales Navigator search past the 1,000-account / 2,500-people cap. |
    | `recipes/find-stakeholders.md` | Find the buying committee at a named account by title, seniority and department. |
    | `recipes/score-leads.md` | Score and tier a company list against the ICP, with the reason on every row. |
    | `recipes/research-account.md` | Brief one account before a meeting, every line traced to a source. |
    | `recipes/monitor-buying-signals.md` | Watch target accounts for dated, linked buying signals, free rung first. |
    | `recipes/linkedin-url-lookup.md` | Resolve LinkedIn URL from name + company with strict validation. |
    | `recipes/portfolio-prospecting.md` | Investor / accelerator → portfolio companies → contacts. |
    | `recipes/job-change-monitoring.md` | `waterfall.detectJobChange` (cargo-unique) on a contact segment. |
    | `recipes/funding-watch.md` | Track companies that recently raised funding. |
    | `recipes/tech-intent.md` | Find companies by tech-stack or hiring-intent signals. |
    | `recipes/icp-discovery.md` | Diff Closed-Won vs Closed-Lost segments, surface ICP signals. |
    | `recipes/custom-datapoints.md` | Design which custom attributes + live signals to collect, gated on a real source and cost. |
    | `recipes/outreach-activation.md` | Turn a signal segment into send-ready outreach (enrich → verify → personalize → sequencer handoff). |
    | `recipes/ads-audience-activation.md` | Push a segment to Google Ads Customer Match / LinkedIn Matched Audiences. |
    | `recipes/review-and-iterate.md` | Human review loop for judgment output; corrections become permanent rules. |
    | `recipes/re-engagement.md` | Wake up stale contacts only when a fresh signal fires (job change, funding, tech intent). |
    | `recipes/lost-deal-revival.md` | Revive Closed-Lost CRM deals by branching on `lost_reason` (champion left, budget, timing). |
    | `recipes/account-expansion.md` | Multi-thread customer accounts — net-new buyers, deduped against the Contacts model. |
    
    **Priority provider stack** (recipes lead with these): salesNavigator (sourcing), aiArk (LinkedIn-anchored enrich + the catalog's cheapest company enrich and search), waterfall (multi-source enrichment + email verify + job-change), FullEnrich (premium contact lookup), apolloio (1-credit niche-coverage enrich), theirStack (tech-stack + hiring intent), peopleDataLabs (heavyweight backfill). **Already have LinkedIn URLs (or an event URL)?** Don't source — go straight to `aiArk.enrichPerson` (0.1, profile **+ verified email**, bills 0 on no-email), or `linkedin` (`enrichProfile`/`enrichCompany` 0.25, `extractEventAttendees`) when you don't need the email; these are the cheapest URL-anchored enriches and easy to miss because the stack above is sourcing-first.
    
    **Critical rules:**
    - **Acceptable use gates every step that touches a person** (`../cargo-gtm/references/acceptable-use.md`): B2B professional identities from licensed providers only, three free blocking checks before any outreach step (*basis*, *suppression*, *relevance*), and a refusal list — undifferentiated fan-out, consumer targeting, lists with no stated origin, contacting a suppressed record, filter or identity evasion, auto-dialing, batch-blasting LinkedIn engagement actions, batch or automated posting / replying / liking / DMing from the user's X account (`xAccount`). The pack never sends: outreach stops at send-ready variables for the user's own sequencer.
    - All recipes use credits-based actions — **190** of the 594 the catalog exposes, priced in [`../cargo-gtm/references/credits-cost-table.md`](../cargo-gtm/references/credits-cost-table.md) and regenerated from `cargo-ai orchestration action list --kind connector` / `--kind native` (free, reads the catalog), which return a `credits` array on every billed action. The other 404 actions carry no *provider* price — but nothing that runs in a workflow is free: **every node execution bills 0.01 credits (1 per 100)**, structural natives (`branch`, `filter`, `switch`, `variables`) included. The cost table prices actions, not steps; see [`../cargo-billing/SKILL.md`](../cargo-billing/SKILL.md) → "The execution charge".
    - Action shape: `{"kind":"connector","integrationSlug":"<slug>","actionSlug":"<slug>"}` — no `config` on a top-level action, and **`connectorUuid` is never nested inside one**; it sits at the top level of a node.
    - Output retrieval: `cargo-ai orchestration run download-outputs --output-node-slug <slug>` (NOT `run download`).
    - peopleDataLabs filter shape: `searchX` uses cargo's `{conjonction, groups, conditions}` shape; `queryX` takes a PDL **SQL string** — never Elasticsearch.
    
    ### cargo-orchestration
    
    **Critical rules:**
    
    - See the decision flowchart at the top of `../cargo-orchestration/SKILL.md` for when to use `action execute` vs `run create` vs `batch create`.
    - **Never enroll a full batch on the first attempt.** `batch create` / `action execute-batch` fan out across every record in the source. Sample **10–20 records**, report observed cost + hit-rate, then ask the user to approve the full enrollment — quoting the **record count** and the **credit estimate**. Mechanics: `../cargo-orchestration/SKILL.md` → "Create a batch"; spend rules: `../cargo-gtm/references/cost-discipline.md` §1.
    - **Search for the action; never browse the catalog for it.** `cargo-ai orchestration action list <keywords> [--kind connector|native|tool|agent] [--integration-slug <slug>] [--limit 20]` covers the integration catalog, Cargo native actions, workspace tools, and agents in one free call, and returns a ready-to-paste `action` object (`connectorUuid` resolved) plus the action's **credit costs**. Its sibling `cargo-ai connection action search <keywords>` is connector-only but adds `--credits-only`, the one filter `action list` lacks. Both beat paging `connection integration list`; reach for `integration get <slug>` only once you have picked the action and need its full input schema.
    - **Omit `config` on `action execute` / `action execute-batch`** — inputs go in `--data` / `--records`. That is the shape `action list` returns, so its result pastes straight in. `action get-output-schema` takes the same shape (inputs, when its schema depends on them, in `--data`). Workflow **nodes**, alert `--actions`, play `healthAlertActions`, and agent / MCP-server `--actions` still carry `config`. Inputs misplaced in `config` are stripped without an error that names `config`, so they never arrive: an action with a required input is refused before it runs on that missing field, one without runs on nothing. A misspelled or undeclared input key is refused before the run is created (`invalidData`, `Unknown field: <key>`, nested keys included; in a batch one bad record refuses the whole batch) — except on tool actions, extra top-level batch columns, and inside workflow nodes, where an unknown key is still dropped silently.
    - **`action execute` is the default for running an operation; `node execute` is debug-only.** Use `node execute` only to test a single node of a workflow you're authoring — it requires `--workflow-uuid`, `--release-uuid`, `--node`, `--computed-config` and `--context` (all five). Anything else — enrich a record, call a connector action, invoke a tool or agent — goes through `action execute` / `action execute-batch`.
    - **Build node graphs from dedicated actions + expressions, in this order:** (1) a dedicated action, found first with `orchestration action list <keywords>` (connector actions, and native ones like `agent`, `modelUpsert`, `branch`, `group`); (2) an expression for the glue, since it's inline JavaScript in the field that needs the value; (3) HTTP, only if no action exists for that API; (4) a `script`/`python` node, only if the logic can't fit in an expression. See `../cargo-orchestration/references/node-selection.md`.
    - **Show a node graph, don't describe it.** Before deploying a draft, and whenever the user asks what a workflow or play does: `cargo-ai orchestration node diagram --workflow-uuid <uuid> --raw` (free, runs nothing, CLI ≥ 1.0.54; `references/node-diagram.md`). Routing, fallback edges, and which nodes bill are what's being approved. Let the command draw it rather than transcribing — node **slugs repeat within a release**, so a hand-drawn diagram keyed on slug merges nodes that aren't the same.
    - Filter JSON uses `conjonction` (not `conjunction`). It is a required key, so a misspelling is rejected with a 400.
    - Query orchestration runtime tables (ClickHouse) with `cargo-ai orchestration query execute "<sql>"` against `runs`, `batches`, `spans`, `records` (no schema prefix; workspace scoping is automatic).
    - For SQL against workspace storage (Companies, Contacts, …), use `cargo-ai storage query execute "<sql>"` — documented in `cargo-storage`.
    - All operations are async — poll or pass `--wait-until-finished`. See [Async polling](#async-polling).
    
    ### cargo-analytics
    
    **Critical rules:**
    
    - `segment download` requires `--model-uuid`, not `--segment-uuid`.
    - For batch result download, get the `output-node-slug` from `release get <release-uuid>` → `nodes[].slug`.
    - For billing and credit usage, use `cargo-billing` instead.
    - Analytics answers "what happened" (metrics, counts, exports). When the question is **why** — a failing run, a batch full of errors, surprising cost — hand off to `cargo-diagnostics`; its sweep runbook picks up exactly where analytics' error counts leave off.
    
    ### cargo-billing
    
    **Critical rules:**
    
    - Requires a token with **admin access**.
    - Invoice amounts are in cents — divide by 100 for dollars.
    - `subscriptionAvailableCreditsCount + additionalAvailableCreditsCount - subscriptionCreditsUsedCount` from `subscription get` (under `.subscription`) = remaining credits.
    - **Every node execution bills 0.01 credits (1 per 100)** — structural natives included, errored executions included. It is attributed to *no* node (`executions[].creditsUsedCount` is provider cost only), so any estimate or per-node profile built without it under-counts. Only `usage get-metrics --unit orchestration.executions` shows it; `--unit` takes exactly `billing.credits` / `orchestration.executions` / `storage.records` / `hosting.events`, and with no `--unit` those four interleave in one `items[]` array with different meanings for `count`.
    
    ### cargo-diagnostics
    
    **Critical rules:**
    
    - Start with the **sweep** when you don't know which run to look at; it ends with exemplar UUIDs for the **trace**. With no UUID at all, `orchestration trace list --started-after <iso> --statuses error,degraded` lists what failed, one row per trigger across child runs; `span list` / `span count` filter node executions by batch, provider, action or error text without SQL. Both need a start date (`--started-after` / `--execution-started-after`).
    - **`degraded` means a fallback absorbed a failure** — the run succeeded, a node errored. Sweep it together with `error`.
    - `runContext` is the source of truth for what a node produced; an execution's `title` is a truncated summary — never evidence.
    - Credit attribution (`billing …`) needs an **admin** token; the SQL and `run get` steps don't.
    - Any fix that re-runs paid nodes goes through the pilot gate in `../cargo-gtm/references/cost-discipline.md`.
    - Diagnostics explains; it doesn't export. For bulk retrieval after the diagnosis (`run download-outputs`, `batch download`, `segment download`) go back to `cargo-analytics`.
    - Present conclusions first, evidence as compact tables — per `references/interaction.md` (in the `cargo` router skill).
    
    ### cargo-observability
    
    **Critical rules:**
    
    - **`preview` before `create`.** `alert preview --scope … --threshold … [--window-minutes 60]` evaluates now without firing — the only way to size a threshold against reality and to catch an invalid scope/threshold pairing (`outcome: "notComputed"`) before it becomes a schedule that errors every tick.
    - **Scope and threshold are a matched pair.** Telemetry metrics (`errorRate`, `duration`+aggregation, `credits`+aggregation, `count`) need `spans`/`runs`/`records`; `query` needs a query scope; `recordsCount`/`recordsShare`/`freshness`/`syncDuration` need `model`. Full matrix + units in `references/scopes-and-thresholds.md`.
    - **Empty window vs real zero.** Most metrics report an idle window as `empty` (healthy, no fire). Only `count` and `recordsCount` return a real `0` — pair with `lte 0` for a **dead-man's switch** (alert when a workflow *stops*, a model *empties*).
    - **Firing is at-most-once and costs credits.** Actions fire as runs (`runUuids` on the event); a sustained breach re-fires once per tick it's still true, never on the same rows twice. If an action calls a paid provider, apply `../cargo-gtm/references/cost-discipline.md` — a scheduled alert re-bills on every breach.
    - **`--enabled` is strict** (`true`/`false` only); model-scope `filter` uses the segmentation shape spelled **`conjonction`**.
    - Permissions are `observability:read` / `observability:write` (not admin-only). The declarative equivalent is a project's `defineAlert` — see `cargo-project`.
    
    ### cargo-storage
    
    **Critical rules:**
    
    - Query via `cargo-ai storage query execute "<sql>"` (or `storage query download --query "<sql>"` for full exports) using `<datasetSlug>.<modelSlug>` table names (e.g. `default.companies`). `model get-ddl` is optional — useful for column types and SQL dialect.
    - For SQL against orchestration runtime tables (`runs`/`batches`/`spans`/`records`), use `cargo-ai orchestration query execute "<sql>"` — documented in `cargo-orchestration`.
    - For advanced record queries (filtering, sorting, pagination), use `segmentation segment fetch` — documented in `cargo-segmentation`.
    - `storage relationship set` **replaces** the dataset's whole relationship set — anything absent from the payload is deleted. `list` first, send the full array back.
    
    ### cargo-segmentation
    
    **Critical rules:**
    
    - Filter JSON uses `conjonction` (not `conjunction`). It is required at the filter and the group level, so a misspelling is rejected with a 400, and a group with `conditions: []` is rejected too.
    - **Size before you spend.** `segment fetch --fetching-limit 1` counts an inline filter for free (read `count`; `--limit` caps the membership itself, so `--limit 1` reports 1); a saved segment's `recordsCount` is the authoritative size. Quote it before proposing any paid run over the audience.
    - `segment download` takes `--model-uuid` **plus the filter**, never `--segment-uuid`.
    - `change list` needs `--segment-uuid`; `change fetch` needs the **change** UUID plus `--kinds` (`added`/`updated`/`removed`/`unchanged`).
    - `updatedRecordsCount` stays `0` unless the segment was created with `--tracking-column-slugs` — those columns define what "updated" means.
    - Segments named `GENERATED_PLAY_SEGMENT` (`fromPlay: true`) are owned by a play. Never edit or remove them by hand.
    
    ### cargo-connection
    
    **Key concepts:**
    
    - **Integration** = external service type (HubSpot, Clearbit, Salesforce, …)
    - **Connector** = authenticated instance of an integration (referenced by `connectorUuid` in nodes)
    
    ### cargo-ai
    
    **Critical rules:**
    
    - Knowledge for RAG attaches to an agent via the release's `resources`: **files** + **libraries** come from [`cargo-content`](#cargo-content). Wire them in with `release update-draft --resources …` then `release deploy-draft`.
    - **`cargo-ai mcp` with no `--server` now bridges the first-party platform MCP** (`mcp.getcargo.io/mcp`), not "the workspace's only MCP server". `ai mcp-server` still builds a curated server; pass its uuid with `--server`. See "These skills vs Cargo's MCP surfaces" above.
    - **A coding agent (`--harness-slug` + `--repository` on a release or a new chat) pushes as the Cargo GitHub app**, which must be installed on the repo; its token is scoped to that repo, it works on `cargo/<name>` branches and never pushes the default branch, and a mention on its PR continues the chat. Harness and repository are fixed when a chat is created — passing them with `--chat-uuid` is refused.
    - **CLI ≥ 1.0.19:** files and libraries moved out of the `ai` domain into the top-level **`content`** domain (now the `cargo-content` skill). The old `cargo-ai ai file …` commands no longer exist.
    
    > For _using_ agents (sending messages, multi-turn chat, polling), use `cargo-orchestration`.
    
    See `../cargo-ai/SKILL.md` for model and temperature guidance by use case.
    
    ### cargo-content
    
    **Critical rules:**
    
    - New top-level **`content`** domain in CLI ≥ 1.0.19 — `cargo-ai content file …` / `cargo-ai content library …`. The old `cargo-ai ai file …` path is gone (`unknown command` → you're on the old path; bump the CLI).
    - A file or library is inert until attached to an agent's deployed release `resources` — that wiring lives in [`cargo-ai`](#cargo-ai).
    - **`upload` and `put` default differently.** `upload` (and `defineFile`) indexes the file for agent search and mirrors it into the context repo under `.files/` (committed and pushed); `content file put` and every other path write store it only — not searchable by an agent until written with `--index vectorStore`, and not in git.
    - **Links are unauthenticated.** `content file url` returns a signed link anyone can open until it expires (default 1 h, max 3 h); a `public` file has a stable no-auth link until made private. Share either only when the user asked to share that file.
    - For batch-run **input** files (CSVs that drive a batch), use `cargo-ai workspaceManagement file upload` (a different surface) — see `cargo-workspace-management`.
    
    ### cargo-context
    
    **Key concepts:**
    
    - **Context repository** = the GitHub repo backing the workspace's context. Canonical example: [`getcargohq/cargo-workspaces`](https://github.com/getcargohq/cargo-workspaces). Files use `kebab-case.md` names, YAML frontmatter with required `title` + `description`, and `domain/slug` cross-refs (no `.md`).
    - **Runtime sandbox** = a checked-out, executable copy of the context repo. `runtime write` and `runtime edit` push to the default branch; `runtime execute` does **not** push.
    - **Knowledge graph** = the typed graph over every md/mdx file, with frontmatter and outbound cross-refs per node. Built via `cargo-ai context graph get`.
    
    **Critical rules:**
    
    - `runtime write` / `runtime edit` commit and push. `runtime execute` is ephemeral — use it for `grep`/`ls`/inspection, never for persistent changes.
    - `runtime edit --old-string` must match the file content **exactly once** (unless `--replace-all`). Read first, copy whitespace verbatim.
    - Set `title` + `description` frontmatter on every `.md`/`.m

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.