doca-spcx-cc — Claude Code skill: what it does, how to install
This skill drives the host-side doca_spcx_cc CLI to load, configure, run and stop an SPC-X congestion-control algorithm on a BlueField DPA, including the SPCX-vs-doca-pcc call.
Apache-2.0 ★ 4,106 updated 2026-10-23
npx skills add NVIDIA/skills --skill doca-spcx-cc -a claude-codeWhat doca-spcx-cc does
The skill applies when someone works with doca_spcx_cc, the CLI under /opt/mellanox/doca/tools/, to operate an SPC-X congestion-control algorithm against a live RDMA or RoCE fabric driven by a BlueField DPA processor. It walks a fixed order: pick a surface first — SPCX, doca-pcc, or factory firmware — then settle the RP/NP role, split DPA-side algorithm authoring from plain consumption, and confirm the link actually carries contention before anything else.
Two companion files back this up: a tasks file for configuring and running, and a capabilities file covering the SPCX-vs-PCC tradeoff, runtime metrics, and a safety layer for production rollout — blast radius, observability, out-of-band access, rollback to factory PCC. One scenario gets called out directly: doca_pcc --status reporting Active with an unchanged traffic curve proves nothing either way, because a CC algorithm has no observable behavior without real contention on the fabric.
Running this requires a DOCA SDK install under /opt/mellanox/doca on Ubuntu 22.04/24.04 or RHEL/SLES with the SPCX optional component, a BlueField exposing its DPA processor with the firmware custom-PCC slot enabled, a version-matched DPACC compiler, and a non-production RDMA/RoCE fabric where contention can be induced. Without DOCA installed, the skill points to doca-setup/SKILL.md instead.
What it helps with
- decide between SPCX,
doca-pcc, and factory firmware for a custom CC algorithm - confirm an SPCX session actually took over congestion control
- diagnose a
DOCA_PCC_PS_ERRORon startup - evaluate an SPCX algorithm on a non-production fabric before rollout
- check version alignment between the tool, the
doca-pcclibrary, DPACC, and firmware
Example prompts for the agent
- Help me pick between SPCX and doca-pcc for a new RTT-based algorithm on RoCE
- My SPCX session loaded but throughput didn't change, what's going on
- Check whether my SPCX algorithm is ready to move to a production fabric
How to install doca-spcx-cc
1Skills CLI (Vercel)
npx skills add NVIDIA/skills --skill doca-spcx-cc -a claude-code2Manually: put the files in place
~/.claude/skills/doca-spcx-cc/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/doca-spcx-cc/
1Skills CLI (Vercel)
npx skills add NVIDIA/skills --skill doca-spcx-cc -a codex2Manually: put the files in place
.agents/skills/doca-spcx-cc/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add NVIDIA/skills --skill doca-spcx-cc -a cursor2Manually: put the files in place
.cursor/skills/doca-spcx-cc/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install NVIDIA/skills skills/doca-spcx-cc2Manually: put the files in place
.github/skills/doca-spcx-cc/SKILL.md1Skills CLI (Vercel)
npx skills add NVIDIA/skills --skill doca-spcx-cc -a gemini-cli2Platform CLI
gemini skills install https://github.com/NVIDIA/skills --path skills/doca-spcx-ccManually: put the files in place
.devin/skills/doca-spcx-cc/SKILL.mdThe legacy .windsurf/skills/ path still works
Claude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about doca-spcx-cc
How do I install doca-spcx-cc in Claude Code?
Run npx skills add NVIDIA/skills --skill doca-spcx-cc -a claude-code; the skill lands at ~/.claude/skills/doca-spcx-cc/SKILL.md.
What does doca-spcx-cc do?
It guides loading, configuring, running, and stopping an SPC-X congestion-control algorithm through the doca_spcx_cc CLI on a BlueField DPA processor, and helps choose between SPCX and doca-pcc.
What's required to run doca-spcx-cc?
A DOCA SDK install with the SPCX optional component, a BlueField exposing its DPA with the firmware custom-PCC slot enabled, a version-matched DPACC compiler, and a non-production RDMA/RoCE fabric for testing.
Source text
SKILL.md · Apache-2.0
--- license: Apache-2.0 name: doca-spcx-cc description: > Use this skill when the user is invoking `doca_spcx_cc` (the host-side CLI under /opt/mellanox/doca/tools/) to load, parameterize, start, observe, or stop an SPC-X congestion-control algorithm on a BlueField with a DPA processor against a live RDMA / RoCE fabric, or picking SPCX vs the established `doca-pcc` surface. Trigger even when the user does not say "DOCA SPCX" or "doca_spcx_cc" — typical implicit phrasings include "I want to write a custom RTT-based CC algorithm for my RoCE fabric", "my SPCX session loaded but throughput / latency didn't change", "doca_pcc status shows Active but factory CC seems to still be in charge", "DOCA_PCC_PS_ERROR on start", "is the programmable-CC surface available on my install", or "DPA-side algorithm image won't load". Refuse and route elsewhere for DPA-side algorithm authoring detail, factory PCC firmware configuration, read-only PCC counter inspection, raw DPA cycle profiling, RDMA library programming, or general DOCA install — those belong to other skills. metadata: author: NVIDIA <[email protected]> kind: tool doca_version: "3.5" tags: - doca - pcc - spcx compatibility: > Requires DOCA SDK installed at /opt/mellanox/doca on Linux (Ubuntu 22.04/24.04 or RHEL/SLES) with the SPCX optional component, a BlueField exposing its DPA processor with the firmware custom-PCC slot enabled, the DPACC compiler installed and version-matched, and a non-prod RDMA / RoCE fabric with controllable contention reachable for evaluation. Probes via `pkg-config doca-pcc` and `doca_spcx_cc --help`. The validation steps require a live DOCA install. --- # DOCA SPCX Congestion-Control Tool ## Examples - **"Should I use SPCX or `doca-pcc` for a custom CC algorithm?"** — this is in scope. Walk the decision tree before loading anything on a live fabric. - **"SPCX loaded but throughput did not change."** — confirm the algorithm is in charge before retuning parameters. ## Instructions Follow Loading order below. Open the tasks companion for configure / run. Open the capabilities companion for the SPCX-vs-PCC tradeoff and safety. Do not open every companion file. **Where to start:** This is a tool skill for invoking `doca_spcx_cc` — the host-side CLI that exercises an SPC-X congestion-control algorithm on a live RDMA / RoCE fabric driven by a BlueField with a DPA processor. Open the tasks companion and start at `## configure` for the SPCX-vs-PCC-vs-factory-firmware decision tree (load-bearing gate before any code), the role decision (RP / NP), the DPA-side algorithm authoring vs consumption split, and the live-link / contention precondition. Open the capabilities companion when the question is *what does SPCX let me express that `doca-pcc` does not*, *what is the SPCX-vs-PCC tradeoff*, *what runtime metrics does the tool surface*, or *what is the safety posture for loading a custom CC algorithm on a production fabric*. If DOCA is not installed yet, route to `doca-setup/SKILL.md` first. This skill covers the **SPC-X CC tool**. `doca-pcc/SKILL.md` is the established PCC story; SPCX is the documented extension that authors SPCX-class algorithms on the same DPA hardware substrate. The zero-touch RTT-based CC algorithm (ZTR-RTT) is one NVIDIA reference algorithm that can be loaded through either the PCC or SPCX path depending on the install and the user's algorithm choice; the agent surfaces this decision tree explicitly per the capabilities companion. ## Example questions this skill answers well The CLASSES of `doca_spcx_cc` questions this skill is built to answer, each with one worked example. The class is the load-bearing piece; the worked example is one instance. - **"Should I use SPCX or `doca-pcc` for my custom CC algorithm?"** — worked example: *"I want to write a new RTT-based congestion-control algorithm for my RoCE fabric — which surface do I target?"*. Answered by the SPCX-vs-PCC-vs-factory-firmware decision tree in the capabilities companion + the *"is SPCX the right surface on this install?"* gate in the tasks companion step 1. - **"How do I evaluate my authored SPCX algorithm on a real RDMA link before letting it touch production?"** — worked example: *"I have a DPACC-compiled SPCX algorithm and a non-prod BlueField pair; how do I run a contention-positive evaluation?"*. Answered by the authoring vs consumption split + the live-link precondition in the capabilities companion + the replica-first evaluation flow in the tasks companion. - **"My SPCX algorithm appears to load cleanly but the link's throughput / latency curve is unchanged — what's going on?"** — worked example: *"the host-side `doca_pcc --status` reports `Active` and a stable session, but my RoCE flows look unchanged"*. Answered by the live-link / contention rule in the capabilities companion + the *"algorithm has no signal under no contention"* guidance in the tasks companion + the tasks companion (route through the layered error taxonomy before blaming the algorithm). > **No contention → no signal → no conclusion.** `Active` plus an > unchanged traffic curve is not evidence that the algorithm failed > to take over from factory CC. A CC algorithm has no observable > behaviour without actual contention on the fabric, so an idle-link > or contention-absent run is uninformative by construction — it > supports no verdict in either direction. Establish that the run > actually generated contention before concluding anything, and never > declare an algorithm either broken or safe on such a run. Rule in > the capabilities companion. - **"My SPCX algorithm passed replica testing — what's the gate before I roll it forward to production?"** — worked example: *"my CC algorithm works on the two BlueField pairs in the lab; can I push it to the fleet?"*. Answered by the safety overlay in the capabilities companion (heavily cross-linked to `doca-hardware-safety/SKILL.md`): blast-radius bounded, observability gate proven, OOB reachable, factory-PCC rollback rehearsed, escalation path documented before any production cutover. - **"Is `doca_spcx_cc` on my install, and is it paired with the matching `doca-pcc` library and DPACC compiler version?"** — worked example: *"is the SPCX surface available on my DOCA install?"*. Answered by the version-overlay in the capabilities companion, which redirects to the canonical `doca-version/SKILL.md` chain and adds the *tool ↔ `doca-pcc` library ↔ DPACC compiler ↔ firmware custom-PCC slot* match rule. - **"My SPCX session errored — is it the tool, the algorithm, the device, or the firmware?"** — worked example: *"`doca_spcx_cc` exits with `DOCA_PCC_PS_ERROR` on start"*. Answered by the layered error taxonomy in the capabilities companion + the layered walk in the tasks companion. ## Audience This skill serves **external developers, platform operators, and AI agents authoring, loading, and evaluating an SPC-X congestion-control algorithm on a BlueField with a DPA processor, against a live RDMA / RoCE fabric**. Concretely: - A CC researcher / developer who has authored an SPCX-class DPA-side algorithm (or who is consuming a documented shipped reference such as the zero-touch RTT-based algorithm via the ZTR-RTT CC documentation via `doca-public-knowledge-map` on the SPCX path when the install + algorithm support it) and needs the operator-side harness to load, parameterize, start, observe, and stop the algorithm. - A platform operator running a programmable-CC pilot on a non-prod RDMA fabric to characterise the algorithm's behaviour under controlled contention. - An AI agent producing a *"is this SPCX algorithm safe to roll forward"* answer honestly — with evidence from a contention-positive evaluation, a documented rollback to the factory PCC, and an explicit blast- radius bound — instead of a guess from datasheet prose. It is **not** for users debugging the `doca_spcx_cc` binary itself, **not** a substitute for the live public DOCA SPCX / DOCA PCC programming guides, **not** the right place for the DPA-side algorithm authoring detail (that path goes through the public DOCA PCC programming guide and the `doca-pcc/SKILL.md` + `doca-dpa/SKILL.md` skills), and **not** the right place for default factory PCC configuration (no host-side library or SPCX tool needed; route via `doca-public-knowledge-map/SKILL.md`). The tool is shipped as a **CLI binary** under `/opt/mellanox/doca/tools/`, not a library you link against; it uses the same `kind: tool` three-file shape as the rest of the bundle. ## Language scope `doca_spcx_cc` is a C host-side CLI that links the host-side `doca-pcc/SKILL.md` library and loads a DPA-side SPCX algorithm image built by the DPACC compiler. The algorithm body is a separate DPA-side translation unit written in the language DPACC accepts. The skill keeps workflow guidance language-neutral and routes per-language questions to the public DOCA PCC / DPACC guides via `doca-public-knowledge-map/SKILL.md`. ## When to load this skill Load this skill when the user is — or the agent needs to — invoke `doca_spcx_cc` on a real host with DOCA installed, paired with a BlueField that has its DPA processor exposed AND the firmware custom-PCC slot enabled, against a port carrying RDMA / RoCE traffic with **actual contention**. Concretely: - Loading an authored SPCX algorithm (or a documented shipped reference) onto the BlueField via the SPCX surface, parameterizing it, starting it, and observing its effect on the live link. - Evaluating an SPCX algorithm on a non-prod replica before any production rollout — capturing the contention-positive run as evidence. - Comparing SPCX vs `doca-pcc` paths for the same algorithm class on the same install (where both paths are available) and deciding which to commit to. - Producing a *"safe to roll forward"* recommendation with the documented evidence + rollback plan, or refusing the recommendation when the evidence / rollback is missing per the capabilities companion. - Diagnosing a `DOCA_PCC_PS_ERROR` or a silent-no-effect symptom against the layered error taxonomy. Do **not** load this skill for general DOCA orientation, DPA-side algorithm authoring detail, raw cycle profiling of the DPA, the factory PCC algorithm shipped in the firmware, or DOCA install. For those, route to `doca-public-knowledge-map/SKILL.md`, `doca-pcc/SKILL.md`, `doca-dpa/SKILL.md`, or `doca-setup/SKILL.md`. ## What this skill provides This is a **thin loader**. Substantive material lives in two companion files: - the capabilities companion — what SPCX expresses that PCC does not (and where the surfaces overlap), the SPCX-vs-PCC-vs-factory-firmware decision tree, the authoring vs consumption split, the role decision (RP / NP), the documented probe-packet format axis, the live-link / contention precondition rule (the load-bearing safety invariant — *"a CC algorithm has no signal under no contention"*), the runtime observability surface (per-port / per-flow trace formats + the host-side status surface), the triple-axis precondition rule (`doca-pcc/SKILL.md`: DPA-capable BlueField + firmware custom-PCC slot enabled + `doca_pcc_cap_*` agreement) extended with SPCX-specific availability, the version overlay (tool ↔ library ↔ DPACC ↔ firmware), the layered error taxonomy (install / device-binding / fw-slot / DPA-image / algorithm-precondition / live-link-precondition / runtime / version / cross-cutting), the observability surface, and the heavily-overlaid safety posture (a wrong CC algorithm on production can melt the fabric). - the tasks companion — step-by-step workflows for the in-scope task verbs: `install` (host-side DOCA install + DPA prerequisites + firmware custom-PCC slot), `configure` (SPCX-vs-PCC decision + role + algorithm + parameters + probe-packet format), `build` (route to install — the host-side tool is shipped; the DPA-side algorithm is user-built by DPACC), `modify` (refuse — do not patch the binary; modify the invocation, algorithm, and parameters), `run` (the prepare → smoke → contention-positive evaluation flow), `test` (iterative loop on the replica before production), `debug` (walk the error taxonomy), `use` (the *"safe to roll forward"* decision with evidence + rollback + escalation), plus a `Deferred task verbs` block. The skill assumes a host where DOCA is already installed, a BlueField with a DPA processor and the firmware-level custom-PCC slot enabled is present and visible, the DPACC compiler is installed at a version matched to the host-side DOCA, the user already knows how (at sketch level) to write the DPA-side SPCX algorithm (or has a shipped reference algorithm to consume), and a non-prod RDMA / RoCE fabric with controllable contention is available for evaluation. ## What this skill deliberately does not ship This skill is **agent guidance**, not a samples or scripts bundle. To keep the boundary clean, it deliberately does not contain — and pull requests should not add: - **A specific congestion-control algorithm.** SPCX *loads* an algorithm the user supplies; the skill refuses to invent algorithm bodies and routes any *"what algorithm should I write"* question to the public DOCA PCC programming guide and to the user's own domain expertise. - **Pre-baked example output** (throughput / latency curves, per-flow counter snapshots). Output is device-, firmware-, fabric-topology-, and workload-specific; pinning one would mislead operators elsewhere. - **Flag strings, subcommand names, probe-packet format tokens, or metric names beyond the DOCA release notes and `--help`.** This surface still evolves; the installed `--help` is the authoritative inventory. - **Wrappers, parsers, or scripts** consuming the tool's output. The format is documented; script against your installed version using the release notes. - **A tuning recommendation derived from a single observation.** CC tuning on a live fabric is high-stakes: the skill prescribes how to *capture evidence and compare against the factory PCC baseline*, and refuses to turn one observation into a parameter change without the user's own domain analysis. - **A `samples/` or `reference/` subtree.** This is a thin loader for a shipped CLI; substantive material lives in the release notes, in `--help`, and in `doca-pcc/SKILL.md` + `doca-dpa/SKILL.md`. ## Loading order 1. Read this skill first to confirm the user's question is in scope (SPCX-side custom CC work, not factory firmware PCC, not raw DPA cycle profiling, and not algorithm authoring detail). 2. **For the SPCX-vs-PCC decision tree, the authoring vs consumption split, the live-link precondition, the version overlay, the error taxonomy, the observability surface, and the safety posture, see the capabilities companion.** 3. **For the documented invocations and the prepare → smoke → contention-positive evaluation workflow — `install`, `configure`, `build`, `modify`, `run`, `test`, `debug`, `use` — see the tasks companion.** ## Related skills - `doca-pcc/SKILL.md` — the host-side Programmable Congestion Control library SPCX builds on and links. The SPCX-vs-PCC decision tree in the capabilities companion is the load-bearing routing rule; conflating the two is the most common programmable-CC first-touch error. - `doca-dpa/SKILL.md` — the DPA control library the algorithm's DPA-side body builds on: kernel-launch model, DPACC build flags, DPA-side comms / verbs. - `doca-rdma/SKILL.md` — the RDMA / RoCE flows being controlled. Without traffic in flight *and contention on the fabric* the algorithm has no signal; surface this precondition before any evaluation. - `doca-pcc-counters/SKILL.md` — read-only PCC counter inspection; the cheaper *"is anything happening on this port"* step before or during an SPCX evaluation. - `doca-hardware-safety/SKILL.md` — the bundle-wide hardware-safety meta-policy this skill's `## Safety policy` layers on. Deploying a wrong CC algorithm on a production fabric is a *meta-policy STOP* case. - `doca-public-knowledge-map/SKILL.md` — routing to the public SPCX, PCC, and DPA / DPACC guides. - `doca-version/SKILL.md` — canonical DOCA version handling. `## Version compatibility` in the capabilities companion adds the *tool ↔ `doca-pcc` ↔ DPACC ↔ firmware custom-PCC slot* matching rule. - `doca-setup/SKILL.md` — env preparation, install and DPACC compiler verification, BlueField firmware configuration (the custom-PCC slot is a firmware-level setting), and the *no install yet* path via the public NGC DOCA container. - `doca-debug/SKILL.md` — the cross-cutting debug ladder. Cross-link runtime evidence and counter snapshots into a `doca-debug` session when the cause sits below DOCA. - `doca-structured-tools-contract/SKILL.md` — the detect → prefer → fall back → report contract the command appendix in the tasks companion honors. - `doca-programming-guide/SKILL.md` — shared DOCA programming patterns, including the cross-library `DOCA_ERROR_*` taxonomy this tool's error layer overlays. The factory PCC algorithms inside ConnectX firmware are **not in scope**: they work without `doca_spcx_cc` and are configured through firmware knobs, not a host-side API. Route via `doca-public-knowledge-map/SKILL.md`.
© NVIDIA · Apache-2.0 · NVIDIA/skills