Index of every page on this site: llms.txt
All skills
nvidia avatar

/doca-spcx-cc

@6b75e9e
by NVIDIA Corporationnvidia/skills4.1k stars
547
Run it yourself

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.

Use this Skill: https://skilld.dev/gh/nvidia/skills/doca-spcx-cc

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈257 tokens for metadata: the name and description. ≈4k when used: this file. ≈20k more on demand in 6 files.

Description uses 12.8% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈1025 characters, or 12.8%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

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 status reports DOCA_PCC_PS_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 installed --help, the DOCA release notes, or the public DOCA PCC guide, 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. Flags can change between releases; --help wins.
  • 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 DOCA release notes and the public PCC, DPA, and 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.

Source: SKILL.md on GitHub

No rule matched.

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alerts15d3 checks · Risk SAFE
  • Gen Agent Trust Hub20d

    The doca-spcx-cc skill provides safe and well-documented instructions for operators and developers using NVIDIA's SPCX congestion-control tool. It includes extensive safety guardrails, such as mandatory testing on non-production replicas and rehearsed rollback procedures to factory firmware settings, ensuring high-stakes network operations are performed responsibly and securely.

  • Socket15d

    No alerts

  • Snyk20d

    Risk: LOW · No issues

Signed by skilld at 6b75e9e. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 3 days ago
Other metadata
metadata
{
  "author": "NVIDIA <doca-feedback@nvidia.com>",
  "kind": "tool",
  "doca_version": "3.6",
  "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.

README badge

README badge for nvidia/skills/doca-spcx-cc