Cargo

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

Cargo CLI — Skills Overview

This repository contains 16 skills at the repo root: this router (cargo), one onboarding skill (cargo-quickstart), one outcome skill (cargo-gtm), and thirteen 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, connection, AI, content, context, analytics, billing, observability, hosting, cdk, workspace management), plus cargo-diagnostics (cross-domain forensics over runs, batches, and credit spend). 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 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

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 --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

--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 installer's hooks (curl -fsSL https://api.getcargo.io/install.sh | sh) 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.

1. At session start — refresh and register

Before any other Cargo command, refresh the CLI and skills, then register the session in workspace management:

# 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 /cli-version 2>/dev/null || echo latest)"

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

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.

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 "" \
  --description ""

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:

cargo-ai workspaceManagement session upsert \
  --session-id  \
  --title "" \
  --summary "" \
  --finished

--title and --summary are required (NOT NULL). --finished stamps finished_at = now; pass --finished-at 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):

cargo-ai workspaceManagement report create \
  --title "Session share: " \
  --description ""

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.

---

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 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-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 (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 on *.cargo.app) and edge workers (serverless HTTP handlers), and manage their deployments | | [cargo-cdk](../cargo-cdk/SKILL.md) ([recap](#cargo-cdk)) | Declarative — spans every resource type. Define a whole workspace in code (define* builders) and deploy it with cargo-ai cdk (init → types → plan → deploy). Use for workspace-as-code / reproducible / version-controlled setups; see "Declarative vs imperative" above. | | [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 |

> 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.)

CLI domains without a dedicated skill yet

The CLI exposes several domains that no capability skill wraps yet. Reach for them directly (cargo-ai --help) when a task needs them, and file a `worksp

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: getcargohq
• Source: getcargohq/cargo-skills
• License: MIT
• Homepage: https://getcargo.ai

Install and usage instructions live in the source repository linked above.