cargo-diagnostics
Explain what a Cargo run or batch actually did, after the fact — trace one run node by node, draw the graph it executed with the failing step marked, sweep a batch or play for errors grouped by root cause, and attribute credit spend down to the node and the provider. Triggers: "why did this fail", "it succeeded but the output is wrong", "half my rows are empty", "why is this column blank", "what broke in this batch", "why did that cost so much", "which node is burning credits", "it worked yesterday", "these results look wrong", "it went down the wrong path", "this step never ran", "show me what the run did". Skip when: setting up an alert for next time — use cargo-observability; just downloading the data — use cargo-analytics.
- Installs
- 8.8K
- Last 24h
- +122
- Trending rank
- #1730
- Security
- Pass
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/getcargohq/cargo-skills --skill cargo-diagnostics- 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-diagnostics 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 — Diagnostics
Forensic runbooks for workflow behavior: trace one run, sweep a batch for errors, profile a play's credit spend. This skill is the interpretation layer — the raw surfaces (run get, orchestration SQL, billing metrics) are documented in cargo-orchestration and cargo-billing; each runbook here tells you which of them to pull, in what order, and what each output shape means.
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 with {"errorMessage": "..."}. Anything that creates a run or a batch is async — pass --wait-until-finished or poll the matching get. Credit attribution steps (billing usage get-metrics, billing subscription get) need a token with admin access; everything else works with a standard token. When the full skill bundle is installed, ../cargo/references/prerequisites.md adds the CLI version pin, token scopes, and the admin-only surface.
Which runbook?
What are you diagnosing?
│
├── One run / one record ("why did this record fail?",
│ "run succeeded but the output is wrong/empty")
│ └── references/run-trace.md
│
├── Many runs ("the batch has errors", "error rate spiked",
│ "which node keeps failing?")
│ └── references/batch-error-sweep.md
│
└── Cost ("this play is expensive", "where do the credits go?",
"make this cheaper")
└── references/play-optimize-credits.md
Rule of thumb: start with the sweep when you don't yet know which run to look at — it ends by handing you exemplar run UUIDs to feed into the trace.
No run UUID at all ("look at the last run", "the run for acme.com", "what did my play do in the editor")? That's references/run-trace.md § 0, which resolves a symptom to a UUID. Note that orchestration run list without --workflow-uuid needs --created-after and a window of at most 30 days, so it cannot answer "the last run" on its own; orchestration SQL over runs takes no filter and can. Never conclude that run inputs and outputs are inaccessible because run list refused.
Boundary with cargo-analytics: analytics measures and exports ("what's the error rate?", "download the batch results", "export this segment"); this skill explains ("why is the error rate up?", "why is this record's output empty?"). A diagnosis often starts from an analytics signal (error count spiked, batch reports failedRunsCount > 0) and ends back in analytics — once the cause is fixed and runs re-executed, bulk retrieval goes through run download-outputs / batch download / segment download, all documented in ../cargo-analytics/SKILL.md. This skill's evidence surfaces (run get, orchestration SQL, billing metrics) are for diagnosis, not bulk export.
References
| Doc | What it covers |
|---|---|
references/run-trace.md | Find a run from a symptom when you have no UUID (§ 0), then walk it end-to-end: per-node executions, runContext outputs, branch routing, per-node credits and timing. |
references/batch-error-sweep.md | Find errored runs across a batch/play/workspace, group failures by root cause, pick exemplars, decide fix vs report. |
references/play-optimize-credits.md | Attribute credit spend to workflows and nodes, then apply the cost levers in priority order. Attributes the execution charge separately (§ 2b) — 0.01 credits per node execution, which creditsUsedCount does not carry and per-node attribution therefore misses. |
The surfaces every runbook draws on
| Surface | Command | Gives you |
|---|---|---|
| Run detail | cargo-ai orchestration run get <run-uuid> | run.executions[] (node-by-node trace), runContext (per-node output keyed by nodeSlug), runComputedConfigs (what each node was actually called with) |
| Traces | cargo-ai orchestration trace list --started-after <iso> [--statuses error,degraded] [--workflow-uuid <uuid>] · trace count (same filters) · trace get <trace-uuid> | One row per trace — everything one trigger set off across the run lineage (tool and agent child runs, hosted-worker invocations, a chat's assistant turns): status (pending/error/degraded/success), rootRunUuid, rootRecordTitle, spansCount, failedSpansCount, creditsUsedCount, workerUuid, chatUuid. --started-after is required. trace get returns the aggregate only — no spans |
| Spans | cargo-ai orchestration span list --execution-started-after <iso> [filters] · span count (same filters, minus --search/--limit) | Node executions without SQL. Filters: --batch-uuid, --run-uuid, --parent-run-uuid, --workflow-uuid, --execution-statuses pending,success,error, --node-action-slug, --node-integration-slug, --node-slug, --node-kind native|connector|tool|agent|worker, --execution-title-or-error-message <ilike>, --record-title-or-id, --search (list only: record title/id, execution title or error). --execution-started-after is required |
| Orchestration SQL | cargo-ai orchestration query execute "<sql>" | Aggregates over runs, batches, spans, records (ClickHouse; no schema prefix; workspace-scoped). The one way to list a trace's spans by id: WHERE trace_uuid = '<uuid>' |
| Billing metrics | cargo-ai billing usage get-metrics --from <date> --to <date> | Credit totals, filterable and groupable by workflow_uuid, connector_uuid, agent_uuid, integration_slug, model_uuid |
| Graph picture | cargo-ai orchestration node diagram --run-uuid <uuid> --highlight <slug> --format ascii --raw | The graph the run executed, with the failing node marked. Free, runs nothing |
Draw the graph before explaining a routing bug. For "it took the wrong branch"
or "this step never ran", the picture is the evidence, and it shows one thing
run get does not make obvious: the on failure edges. A step that looks skipped
is often one the run reached via a fallbackChildUuid edge, which means the
provider errored rather than returning nothing — a different diagnosis with a
different fix. Flags and the ASCII legend: ../cargo-orchestration/references/node-diagram.md.
degraded is not success. A trace is degraded when a root-run node errored and a fallbackOnFailure / fallback edge carried the run to completion — the run reports success, the failed span stays error. error means an errored root-run node with no next node stopped it. Child-run failures don't settle a trace's status; pending means any span at any depth is still running. Sweep --statuses error,degraded together: a degraded trace is a provider failure the graph absorbed, usually the same root cause as the errors.
Full query syntax, table columns, and caps: ../cargo-orchestration/references/examples/queries.md. Debugging field semantics: ../cargo-orchestration/references/troubleshooting.md.
Presenting findings
Follow ../cargo/references/interaction.md: lead with the conclusion ("18 of 20 failures are one cause: the connector's token expired"), summarize evidence in a short table, never dump raw run get JSON or full query results into the conversation. Any fix that re-runs paid nodes goes through the pilot gate: re-run 10–20 records first, report the observed cost and hit-rate, then ask the user to approve the rest quoting the record count and credit estimate — a diagnosis is not approval to re-bill the batch that produced it. Full spend rules in ../cargo-gtm/references/cost-discipline.md.
When diagnosis dead-ends
If the evidence contradicts documented behavior (a field missing from run get, a query cap that doesn't match the docs, an error that makes no sense), file a report — that's the official channel and the team reads every one:
cargo-ai workspaceManagement report create \
--title "<one-line summary>" \
--description "<commands run, errorMessage verbatim, expected vs actual, UUIDs>"
FAQ
What does the cargo-diagnostics skill do?
Explain what a Cargo run or batch actually did, after the fact — trace one run node by node, draw the graph it executed with the failing step marked, sweep a batch or play for errors grouped by root cause, and attribute credit spend down to the node and the provider. Triggers: "why did this fail", "it succeeded but the output is wrong", "half my rows are empty", "why is this column blank", "what broke in this batch", "why did that cost so much", "which node is burning credits", "it worked yesterday", "these results look wrong", "it went down the wrong path", "this step never ran", "show me what the run did". Skip when: setting up an alert for next time — use cargo-observability; just downloading the data — use cargo-analytics.
How do I install cargo-diagnostics?
Run npx skills add https://github.com/getcargohq/cargo-skills --skill cargo-diagnostics 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-diagnostics/ (personal) or .claude/skills/cargo-diagnostics/ (project).
Which AI agents can use cargo-diagnostics?
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-diagnostics 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-diagnostics?
It is published by getcargohq in getcargohq/cargo-skills. It has 8,781 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.