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 batches, end-to-end use

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 leads for the user's persona, with a cost receipt) in under two minutes, ending by saving the demo 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, cdk, 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 cdk — the declarative one. Where the other capability skills wrap imperative one off cargo ai <domain calls, cargo cdk defines the whole workspace as code ( define builders + cargo ai cdk 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 A new account starts with 100 free credits 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: ~5,000 leads sourced ( salesNavigator.searchLeads , 0.02/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 about 0.5 . Say the free balance out loud before the first paid call on a new account. 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. oauth runs the same OAuth 2.0 Device Authorization Flow it always did, and still needs a human at the verification URL. Use token for CI, with a workspace scoped token from Settings API ; token values are shown only once, so store one immediately in a secrets manager. 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, and Cursor (one repo, three targets) — plugin users get the same skills plus the approval hook and session lifecycle hooks bundled, with no separate installer. 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 return {"errorMessage": "..."} . 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. Jobs 1 and 3 (refresh + session register/finalize) run on their own when either the Cargo plugin is installed (its bundled SessionStart / Stop / SessionEnd hooks handle them) or the hooks from the Cargo bootstrap installer — documented under Staying current → Claude Code in the repo [ README.md ](../README.md) — are present. The Stop hook also checkpoints the session row each turn, so a session that never reaches SessionEnd still shows recent context instead of a bare placeholder. Do these by hand only when neither is installed (or on agents without lifecycle hooks). Job 2 (reporting) is always your responsibility — it can't be automated, and neither can the two asks at the end of Job 3 (share the session, star the repo): a hook can print, but it can't take a Y/N. Never run that installer on the user's behalf without asking. Its documented form pipes a network fetched script into a shell, so it is the user's call, made by the user, in their own terminal — point them at the README rather than reaching for the command yourself. If they want to inspect it first, the README also gives the download once then run form; tell them to prefer it, because fetching twice (read, then pipe) proves nothing about what the second request serves. 1. At session start — refresh and register Before any other Cargo command, refresh the CLI and skills, then register the session in workspace management: 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). Skip the session upsert only if the user opted out or no session id is available. 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: 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. It carries wins as well as failures : a session share (below) files through the same command. 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 — finalize the session row, then ask to share Produce a short title (5–8 words) and a 1–2 sentence summary of what the session actually worked on, then overwrite the placeholder row and stamp finished at : title and summary are required (NOT NULL). finished stamps finished at = now ; pass finished at <iso for an explicit timestamp. Then ask once, at the natural end of the session: "Send this session's activity to the Cargo team so they can improve the experience? (Y/N)" On yes, file a session share report (consented session traces are the fastest product learning loop the team has): On no, don't ask again this session. Skip the ask entirely for trivial sessions (a single lookup, no paid actions). See ../cargo workspace management/references/examples/reports.md for the session share template. Then, if the session went well — 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 (same bar as the session share ask — skip trivial sessions). 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. "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): Touch the marker on either answer, so a no is never re asked and a yes is never double 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 (CDK) 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 cdk ](../cargo cdk/SKILL.md). The user is managing resources as an artifact : "set up / bootstrap a whole workspace as code", "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 cdk 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 → CDK. 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 persona question → 25 leads in under two minutes → cost receipt → save as a recurring play. Routes to carg