cargo-diagnostics Skill for Claude Code: Trace Runs, Sweep Errors and Cut Credit Spend

Makes Claude explain what a Cargo run or batch did after the fact: trace one run, group batch errors by cause and find where credits went.

Installs: 9.3K; on skills.sh
Stars: 21; on GitHub
Files: 4; besides SKILL.md
Updated: Oct 2026; last repo commit

Claude picks one of three runbooks. The run trace walks one run node by node, the batch error sweep groups errors by root cause and hands back example runs, and the credit profile attributes spend to the node and provider and ranks ways to cut it. It can also draw the graph a run executed with the failing step marked.

It reads runs, SQL over the runtime tables, traces, spans and billing metrics, and credit attribution needs an admin token. It needs the Cargo CLI and a Cargo sign-in. Setting an alert for next time is cargo-observability.

Good for

GTM engineers whose run succeeded but gave the wrong output
Operators with a batch full of errors
Teams asking why a play is expensive

Install cargo-diagnostics

Claude Code

Copy this prompt.

Install the cargo-diagnostics skill in Claude Code. Run this command:

/plugin marketplace add getcargohq/cargo-skills
/plugin install cargo@cargo-skills

Then check that it loaded and tell me how to use it.

2
Paste it into Claude Code. It shows the change and asks before running it.

Every Cargo skill drives the cargo-ai CLI, so install it and sign in first. A new account starts with 100 free credits and no card (README). Pick one channel, not two: the plugin and skills add both register the skills, so using both duplicates them. The whole bundle is the route the README documents; this skill's own files point to files in sibling skills such as ../cargo/references/prerequisites.md. The plugin needs Claude Code 2.1.154 or newer and adds hooks and two subagents; see the safety section.

From the project README. Source.

What's in the skill

When it loads

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.

Sections in SKILL.md

Bootstrap
Which runbook?
References
The surfaces every runbook draws on
Presenting findings
When diagnosis dead-ends

Key facts

Author: Cargo (frontmatter author: getcargo), in the vendor's own repo
License: MIT (LICENSE, README badge and plugin.json agree)
Version: 1.6.0
Installs on skills.sh: 9,320 (Nov 2, 2026)
GitHub stars: 21 (Nov 2, 2026)
Last commit: Oct 31, 2026
What installs: 5 files including SKILL.md: 3 reference and example files and skill-metadata.json
Needs: The cargo-ai CLI (npm) and a Cargo sign-in; a new account starts with 100 free credits
Cargo CLI license: UNLICENSED on npm; the skills bundle itself is MIT
Bundle size: README and plugin manifests say 19 skills, the skills.sh badge says 18, and the repo has 20 skill folders including a redirect stub
Works in: Claude Code, Codex, Cursor, Windsurf, GitHub Copilot, Hermes Agent and other skills.sh agents

What it includes

Finds a run from a symptom, then walks it node by node, including branch routing.
Runs code · Run trace
Groups errors in a batch or play by root cause and returns example run UUIDs.
Runs code · Batch error sweep
Attributes credits to workflows and nodes, then applies cost levers in priority order.
Runs code · Credit profile
Draws the graph a run executed with the failing step marked.
Runs code · Run graph
Uses run get, orchestration SQL, trace and span lists, and billing metrics.
Runs code · Evidence surfaces
Any fix that re-runs paid nodes starts with a 10 to 20 record re-run.
Runs code · Pilot gate on fixes
Files a workspace report when evidence contradicts the docs.
Runs code · Report on dead ends

From the official docs

Permissions

Low risk

It reads run and billing data, and its fixes can re-run paid nodes. Approve each re-run and keep run output out of shared chats.

What it can do

Read your data
Create and change things
Delete things
Read-only mode

Watch out for

Fixes can re-run paid nodes
A re-run spends credits. SKILL.md routes these through a 10 to 20 record pilot with cost and hit-rate reported before the rest. github.com
Claude runs the cargo-ai CLI as you
The skill drives the cargo-ai CLI. Sign-in is saved to ~/.config/cargo-ai/credentials.json, and the docs say to confirm the workspace with cargo-ai whoami before any write. github.com
The plugin route adds hooks that run shell commands
The plugin wires a PreToolUse hook on Bash that auto-approves safe cargo-ai calls, and a SessionStart hook that runs npm install -g @cargo-ai/cli at the pinned version. Login, token creation, report creation, project deploy and any remove or delete still prompt. github.com
The plugin sends a session summary to your Cargo workspace
The SessionEnd hook passes the last 60,000 bytes of the transcript to claude -p to write a title and summary, then stores them in your Cargo workspace session record. Use the skills CLI route if you do not want that. github.com
Credit steps need an admin token
billing usage get-metrics and subscription get need admin access. Use an admin token only when you ask about cost. github.com
Run output can hold contact data
Traces show node inputs and outputs. Keep them out of shared channels. github.com
The plugin also adds two subagents
cargo-execution-planner and cargo-list-builder run on the haiku model with Read, Grep, Glob and Bash tools. The planner is described as read-only and the list builder as executing only pre-approved slices. github.com

Security advisories

No published security advisories as of Nov 2, 2026.

Technical details

Talks to	api.getcargo.io (Cargo API). registry.npmjs.org (CLI install). app.getcargo.io (token creation)
Sign-in and keys	Sign-in by emailed code, browser (OAuth) or an API token. Browser and email sign-in save a session to ~/.config/cargo-ai/credentials.json; API tokens are workspace-scoped and the README says to store them in a secrets manager.
Scopes	Reads runs, batches, traces, spans and billing metrics Cargo workspace sign-in (saved in ~/.config/cargo-ai/credentials.json)

Questions

What does cargo-diagnostics do?

It helps Claude work out why a Cargo run, batch or play behaved the way it did. It traces one run, finds the common cause behind many errors, and shows where credits were spent.

Which runbook does it use?

SKILL.md has three: run trace for one record, batch error sweep for many runs, and credit profile for cost. It says to start with the sweep when you do not yet know which run to look at.

Diagnostics, analytics or observability?

Analytics measures and exports, diagnostics explains why, and observability sets alerts for next time. Each is a separate skill in the bundle.

Does it need admin access?

Only for credit attribution. SKILL.md says the billing steps need a token with admin access and everything else works with a standard token.

Will fixing a run cost credits?

It can. SKILL.md says a fix that re-runs paid nodes goes through the pilot gate: re-run 10 to 20 records first and report the cost and hit-rate.

How do I install it?

Use the install box above. Install the whole Cargo bundle, then the Cargo CLI and sign in. The README says to pick one channel, plugin or skills add, not both.

Is it official?

Yes. It sits in Cargo's own repo (getcargohq/cargo-skills), the LICENSE names Cargo as the copyright holder and the plugin manifest lists Cargo as the author.

Does it work in the Claude app, Codex or Cursor?

The README names Claude Code, Codex, Cursor, Windsurf, GitHub Copilot and Hermes Agent. For Claude Desktop it documents a Claude Cowork plugin route with network egress turned on. The skill drives a local CLI, so there is no plain Claude app skill upload here.

Is it safe to use?

It reads run, batch and billing data and can propose fixes that re-run paid nodes. SKILL.md sends those re-runs through a 10 to 20 record pilot, and tells Claude to lead with conclusions instead of dumping raw run JSON. Our advice: approve re-runs yourself and keep run output with contact data out of shared chats.

Information

updated Nov 2, 2026

Repository: getcargohq/cargo-skills
Folder: cargo-diagnostics

getcargohq/cargo-skills skills.sh

Sources

Docs, issue trackers and discussions this page is built from.

Show all 7

cargo-skills README · github.com
cargo prerequisites.md · github.com
cargo-diagnostics SKILL.md · github.com
cargo-skills LICENSE · github.com
cargo-skills plugin.json · github.com
session-end.sh · github.com
session-start.sh · github.com