cargo-segmentation
Define and use segments — named, saved filters over a Cargo model that become the audience for a batch run, a play trigger, or an export. Triggers: "build a segment of", "filter my contacts where", "who matches this criteria", "save this as a list", "how many companies match", "the Closed-Won segment", "everyone who has not been emailed", "target only accounts that", "what is in this segment", "narrow this down to". Filter JSON uses conjonction (not conjunction); misspelling it gets the call rejected with a 400. Skip when: running something over the segment — use cargo-orchestration; exporting its rows — use cargo-analytics; ad-hoc SQL over the model — use cargo-storage.
- Installs
- 6.1K
- Last 24h
- +121
- Trending rank
- #1768
- Security
- Pass
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/getcargohq/cargo-skills --skill cargo-segmentation- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads cargo-segmentation automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
Security audits
Independent scans of the skill's instructions and bundled files.
SKILL.md
The instructions your agent reads when the skill is triggered.
Cargo CLI — Segmentation
Segments are the audience layer of a Cargo workspace: a named, saved filter over one model that answers "which records do I mean?" Everything downstream — a batch run, a play trigger, a CSV export, a change feed — takes a segment (or a segment-shaped filter) as its input.
See
references/response-shapes.mdfor full JSON response structures. Seereferences/troubleshooting.mdfor common errors and how to fix them. Filter condition kinds and operators live in../cargo-orchestration/references/filter-syntax.md— the single source of truth for filter JSON.
Bootstrap
Already signed in (cargo-ai whoami returns a workspace)? Skip to the next section.
npm install -g @cargo-ai/cli # no global install? prefix every command with `npx @cargo-ai/cli`
cargo-ai login --email you@company.com # emailed code, no browser; creates the account on first use
# alternatives: --oauth (browser) · --token <api-token> (CI)
cargo-ai whoami # confirm the active workspace before any write
Every command prints JSON to stdout; failures exit non-zero and print {"error": "...", "status": ..., "body": ...} to stderr. Anything that creates a run or a batch is async — pass --wait-until-finished or poll the matching get. When the full skill bundle is installed, ../cargo/references/prerequisites.md adds the CLI version pin, token scopes, and the admin-only surface.
Key concepts
| Term | What it is |
|---|---|
| Filter | A JSON object ({conjonction, groups[].conditions[]}) evaluated against one model's columns. Ephemeral on its own. |
| Segment | A filter saved with a name, a modelUuid, and a slug. Has a uuid, a live recordsCount, and a history. This is what plays, batches, and exports reference. |
| Change | One computed delta of a segment between two syncs — how many records were added, updated, removed, unchanged. The basis of every "notify me when someone enters this audience" motion. |
| Tracking columns | The subset of columns (--tracking-column-slugs) whose value changes count as an updated record. Without them a record only ever registers as added or removed. |
Filter vs segment — pick deliberately. A one-off question ("how many companies have >100 employees?") wants segment fetch with an inline filter and no saved object. An audience you will run something against, schedule against, or track over time wants a real segment create — because only a saved segment produces changes.
Discover resources first
Always list before creating. A workspace usually already holds the segment you are about to duplicate.
cargo-ai segmentation segment list # all segments (uuid, name, slug, modelUuid, recordsCount)
cargo-ai storage model list # find the modelUuid a segment must target
cargo-ai storage column list --model-uuid <uuid> # the column slugs your filter conditions reference
Segments created automatically by a play are named GENERATED_PLAY_SEGMENT and carry fromPlay: true — never edit or remove those by hand; they belong to the play that owns them.
Retrieve in the UI: segments live under the model at app.getcargo.io/workspaces/<WORKSPACE_UUID>/models/<MODEL_UUID>. Get <WORKSPACE_UUID> from cargo-ai whoami.
Quick reference
cargo-ai segmentation segment list
cargo-ai segmentation segment get <segment-uuid>
cargo-ai segmentation segment create --name "<name>" --model-uuid <uuid> --filter '<json>'
cargo-ai segmentation segment update --uuid <segment-uuid> --filter '<json>'
cargo-ai segmentation segment remove <segment-uuid>
cargo-ai segmentation segment fetch --model-uuid <uuid> --filter '<json>' --limit 50
cargo-ai segmentation segment download --model-uuid <uuid> --filter '<json>'
cargo-ai segmentation change list --segment-uuid <segment-uuid>
cargo-ai segmentation change fetch --uuid <change-uuid> --kinds added --limit 50
cargo-ai segmentation record fetch --model-uuid <uuid> --ids <id[,id…]>
Building a filter
The full condition catalogue — every kind (string, number, date, boolean, array, object, objectProperty, any, vector, sql, segment, occurrence, enrollment) and every operator — is in ../cargo-orchestration/references/filter-syntax.md. The shape:
{
"conjonction": "and",
"groups": [
{
"conjonction": "and",
"conditions": [
{ "kind": "number", "columnSlug": "employee_count", "operator": "greaterThan", "value": 100 },
{ "kind": "string", "columnSlug": "email", "operator": "isNotEmpty" }
]
}
]
}
conjonction, notconjunction. The French spelling is intentional and required at both levels (the filter and every group): a misspelled key fails validation and the API returns a 400 namingconjonction. Grep your JSON forconjunctionbefore every call.Every group needs at least one condition. A group with
"conditions": []is rejected (Filter groups must contain at least one condition); match everything with"groups": []instead.
Match-everything filter: {"conjonction":"and","groups":[]}.
Size the audience before you build it
Counting is free; running anything over an audience is not. Establish the size first, then decide.
# 1. How many records match? — inline filter, no saved object, 1 row back; read `count`
cargo-ai segmentation segment fetch \
--model-uuid <uuid> \
--filter '{"conjonction":"and","groups":[{"conjonction":"and","conditions":[
{"kind":"number","columnSlug":"employee_count","operator":"greaterThan","value":100}]}]}' \
--fetching-limit 1 --sync false --enrich false
# 2. Happy with the shape? Save it as the real audience.
cargo-ai segmentation segment create \
--name "Mid-market accounts" \
--model-uuid <uuid> \
--filter '<same json>' \
--column-slugs "name,domain,employee_count" \
--tracking-column-slugs "employee_count,funding_stage"
segment fetch returns the match total as count (use --fetching-limit, not --limit: --limit caps membership, so --limit 1 reports a count of 1). segment get <uuid> then reports recordsCount — the authoritative size. Cite that number, not your own estimate, before proposing a paid run over the segment.
Fetch vs download vs record fetch
| Command | Returns | Use for |
|---|---|---|
segment fetch --model-uuid --filter | Records inline as JSON, paginated (--fetching-limit, --fetching-offset) | Inspecting a handful of rows, counting, previewing a filter before saving it |
segment download --model-uuid --filter | Signed URLs (urls[]) to the full dataset | Handing the whole audience to the user or another tool — see ../cargo-analytics/SKILL.md |
record fetch --model-uuid --ids <ids> | Specific records by id | Re-reading rows a change feed just told you about |
segment fetch refreshes the model before evaluating (--sync) and adds a _segments membership column (--enrich). Both default to on when omitted and cost time, so pass --sync false --enrich false for a size check.
Never page a large segment into the conversation. Use --limit 3 to see the shape, then download for the rest.
Changes — the delta feed
Every time a segment syncs, Cargo computes a change: how the membership moved. This is what turns a static list into a signal.
# What deltas exist for this segment?
cargo-ai segmentation change list --segment-uuid <segment-uuid>
# → { "changes": [ { "uuid", "totalRecordsCount", "addedRecordsCount",
# "updatedRecordsCount", "removedRecordsCount",
# "unchangedRecordsCount", "createdAt" } ] }
# Only the deltas where something entered (or moved, or left)
cargo-ai segmentation change list --segment-uuid <segment-uuid> --has-records added --limit 20
# One delta's counts, by its uuid → { "change": {...} }
cargo-ai segmentation change get <change-uuid>
# Which records actually entered the audience in that delta?
cargo-ai segmentation change fetch --uuid <change-uuid> --kinds added --limit 50
# The whole delta as files, when it is too big to page → { "urls": [...] }
cargo-ai segmentation change download --uuid <change-uuid> --kinds added,removed
--kinds is required on change fetch and takes added, updated, removed, or unchanged (comma-separated). Returned rows carry the _kind, _id, _title, and _time meta-columns alongside the model's own columns. change download returns signed URLs rather than rows, and takes the same four kinds (unchanged from CLI 1.0.128, cargo#6369; before it the API refused that one).
change list --not-empty keeps only the deltas where a record was added, updated or removed, and --has-records takes any of the four kinds. Both need CLI 1.0.128 (cargo#6369): before it the API answered --not-empty with a 400 (Unrecognized key: "notEmpty") and refused --has-records unchanged, so on an older CLI use --has-records <kind> to skip empty deltas.
updatedRecordsCount is always 0 unless the segment was created with --tracking-column-slugs — the tracked columns define what "updated" means. Set them at creation time when the segment is meant to feed a monitoring motion.
A segment's most recent delta is also inlined on segment list / segment get as lastChange, so a "what moved?" question rarely needs a second call.
What consumes a segment
Segments are an input, not an outcome. Once one exists:
- Run something over it — batch a connector action or workflow across every member:
../cargo-orchestration/SKILL.md. Batches enroll from a segment; sample 10–20 records and get explicit approval before enrolling the full audience. - Trigger a play on entry — a play fires as records enter its audience. A play is created from a
--model-uuid, a--filter, and--change-kinds, and generates its ownGENERATED_PLAY_SEGMENT; see../cargo-orchestration/references/examples/plays.md. - Export it —
../cargo-analytics/SKILL.md(segment downloadneeds--model-uuid, not--segment-uuid— a frequent 400). - Watch it — alert when the audience empties, stalls, or spikes:
../cargo-observability/SKILL.md. - Act on it as GTM — signal segments (job change, funding, tech intent) drive the recipes in
../cargo-gtm/SKILL.md. - Declare it as code —
defineSegmentin../cargo-project/SKILL.mdwhen the audience should live in git.
Gotchas
conjonction, neverconjunction— the call is rejected with a 400.segment downloadtakes--model-uuid, not--segment-uuid. The filter travels with the request; the segment UUID is not a valid input there.change fetchneeds--uuid(the change UUID) plus--kinds. Passing the segment UUID returns a 400.change listneeds--segment-uuid. Calling it bare returns a 400 complaining thatsegmentUuidis undefined.--helponchangeandrecordsubcommands prints the parent help rather than the subcommand's flags (CLI ≥ 1.0.48). Use the Quick reference above; file a report if it still bites.- A segment belongs to exactly one model. Cross-model audiences are a relationship + filter on the joined column, not two segments.
fromPlay: truesegments are owned by a play. Editing one changes what that play targets; removing one breaks it.--limiton a segment caps membership, it is not a display page size —--fetching-limitis the page size.
When the CLI fails
Two failed attempts on the same command, or behavior that contradicts this skill, goes to the team:
cargo-ai workspaceManagement report create \
--title "<one-line summary>" \
--description "<commands run, errorMessage verbatim, expected vs actual, UUIDs>"
FAQ
What does the cargo-segmentation skill do?
Define and use segments — named, saved filters over a Cargo model that become the audience for a batch run, a play trigger, or an export. Triggers: "build a segment of", "filter my contacts where", "who matches this criteria", "save this as a list", "how many companies match", "the Closed-Won segment", "everyone who has not been emailed", "target only accounts that", "what is in this segment", "narrow this down to". Filter JSON uses conjonction (not conjunction); misspelling it gets the call rejected with a 400. Skip when: running something over the segment — use cargo-orchestration; exporting its rows — use cargo-analytics; ad-hoc SQL over the model — use cargo-storage.
How do I install cargo-segmentation?
Run npx skills add https://github.com/getcargohq/cargo-skills --skill cargo-segmentation in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/cargo-segmentation/ (personal) or .claude/skills/cargo-segmentation/ (project).
Which AI agents can use cargo-segmentation?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is cargo-segmentation safe to install?
Security partners have reviewed it: Gen Agent Trust Hub passed; Socket passed; Snyk passed. As with any skill, read the SKILL.md and bundled scripts before installing.
Who maintains cargo-segmentation?
It is published by getcargohq in getcargohq/cargo-skills. It has 6,102 recorded installs.
More from getcargohq/cargo-skills
cargo-connection
getcargohq/cargo-skills
Connect Cargo to an external system and find out what it can do — authenticate connectors, browse the integration catalog, and resolve the connectorUuid and actionSlug a workflow node needs. Triggers: "connect my HubSpot", "is Salesforce connected", "what integrations do you support", "can Cargo talk to ", "what actions does have", "I need the connector UUID", "set up the API key for", "it is asking for credentials again", "why is this connector failing auth", "list my connectors". Integrations: amplemarket, amplitude, attio, bigQuery, calendly, cargoSignals, closecom, contrast, csv, customerio, dbt, emailBison, expandi, googleAds, googleCalendar, googleSheets, heyReach, http, hubspot, hubspotMcp, instantly, instantlyV2, intercom, jira, kitt, lemlist, lgm, linkedinAds, linkedinMatchedAudience, livestorm, manus, marketo, metaAds, metabase, microsoftTeams, mixpanel, monaco, netsuite, netsuiteSoap, nooks, notionMcp, octave, onesignal, outreach, pipedrive, postgresql,
cargo-gtm
getcargohq/cargo-skills
Do business-to-business go-to-market work on Cargo — research accounts and buying committees, enrich and verify B2B contact records from licensed data providers, score and qualify leads, draft permission-based outreach for the user's own sequencer, sync to CRM, and monitor buying signals. Consent basis, suppression lists, and volume limits gate every step that touches a person (references/acceptable-use.md); bulk unsolicited messaging, purchased or scraped lists, and consumer targeting are refused. Triggers: "build me a list of", "find 50 at ", "who works at", "find work emails for these accounts", "enrich this CSV", "verify these emails", "build a TAM", "who fits our ICP", "who actually buys from us", "what data points should we collect on accounts", "our outbound is reaching the wrong people", "score these leads", "write a first-touch email", "push these to my CRM", "who changed jobs", "who just raised funding", "companies using ", "who is hiring ", "fi
cargo-ai
getcargohq/cargo-skills
Build and configure AI agents inside Cargo — create an agent, choose its model and temperature, write its prompt, attach knowledge for retrieval (RAG), connect MCP tool servers, manage memories, and deploy releases. Triggers: "create an agent", "make an agent that", "give the agent our docs", "attach this knowledge base", "attach this library to the agent", "add resources to the agent release", "connect an MCP server", "expose our tools as an MCP server", "use Cargo from Claude Desktop or ChatGPT", "change the agent model", "what does the agent remember", "deploy the agent", "the agent is answering wrong". Skip when: uploading the knowledge files themselves — use cargo-content; sending the agent a message or running it over records — use cargo-orchestration.
cargo-workspace-management
getcargohq/cargo-skills
Administer a Cargo workspace and talk back to the Cargo team — invite and manage members, mint and rotate API tokens, organize plays, tools, and agents into folders, inspect roles, upload batch input files, and file reports. Triggers: "invite my teammate", "create an API token for CI", "who has access", "organize these into folders", "rotate that token", "upload this CSV for a batch" — and for feedback: "report this bug to Cargo", "send feedback to the Cargo team", "this CLI command is broken", "share this session with Cargo", "request a feature". Most commands need a token with admin access. Skip when: the question is about credits, plans, or invoices — use cargo-billing.
cargo-orchestration
getcargohq/cargo-skills
Make Cargo actually run something, or show what it would run — execute one connector action, run a multi-step workflow, trigger a batch across a whole segment or model, message an AI agent, build or edit a node graph, draw a workflow, tool or play as a diagram, and query the runtime tables (runs, batches, spans, records) with SQL. Triggers: "run this on all my contacts", "execute the action", "kick off a batch", "build a workflow", "schedule a play", "make it run every morning", "ask the agent", "show me the workflow", "what does this tool do", "visualize this play", "draw the graph", "explain this workflow", "how many runs failed today", "what is the output schema for this action", "add a step that". Skip when: explaining why a run misbehaved — use cargo-diagnostics; downloading result files — use cargo-analytics; committing the workflow as code — use cargo-project.
cargo-billing
getcargohq/cargo-skills
Understand what Cargo is costing — remaining credits, usage broken down by workflow, connector, or agent, subscription state, and invoice history. Triggers: "how many credits do I have left", "what did that cost", "why is my bill so high", "am I about to run out", "will this fit in our budget", "show me my invoices", "how much have I spent this month", "what plan am I on", "what do I get for free", "how many free credits", "can I afford this run", "add a card", "update my payment method", "why was my card declined". Needs a token with admin access. Skip when: attributing spend to specific nodes or cutting a play cost — use cargo-diagnostics.
Popular data & databases skills
supabase-postgres-best-practices
supabase/agent-skills
Postgres best practices maintained by Supabase, for Postgres running anywhere. Load this skill BEFORE writing or changing anything that lives in a Postgres database: creating or altering tables and columns (including choosing column types), schema design, migrations and declarative schema files, RLS policies and the tests that verify them, indexes, triggers, database functions, queues and scheduled jobs (pgcron, pgmq), vector/semantic search (pgvector), and restoring dumps (pgrestore) or importing data. Also load it when diagnosing slow queries, high CPU, timeouts, EXPLAIN plans, connection exhaustion, locking, bloat, or rows visible to the wrong user or tenant. This is not just a performance guide — schema, migration, security, and SQL authoring tasks need these rules too, even for a one-column change or a single query.
prisma-client-api
prisma/skills
Prisma Client API reference covering model queries, filters, operators, and client methods. Use when writing database queries, using CRUD operations, filtering data, or configuring Prisma Client. Triggers on "prisma query", "findMany", "create", "update", "delete", "$transaction".
prisma-database-setup
prisma/skills
Deprecated compatibility name for prisma-orm-setup. Use only when a user or existing integration explicitly invokes prisma-database-setup; otherwise select prisma-orm-setup.
prisma-cli
prisma/skills
Prisma ORM 7 CLI reference for existing Prisma 7 applications or explicitly selected Prisma 7 workflows. Covers prisma init, generate, migrate, db, dev, studio, and mcp. For setup, connection repair, or Prisma 8, use prisma-orm-setup; not the Prisma Platform CLI.
prisma-postgres
prisma/skills
Deprecated compatibility name for prisma-postgres-setup. Use only when a user or existing integration explicitly invokes prisma-postgres; otherwise select prisma-postgres-setup.
prisma-driver-adapter-implementation
prisma/skills
Required reference for Prisma ORM 7 SQL driver adapter work. Use when implementing or modifying adapters, adding database drivers, or touching SqlDriverAdapter, Transaction, savepoint, result mapping, or DriverAdapterError behavior. Covers current transaction lifecycle, optional savepoint hooks, original database-error preservation, and verification.