Doca Comm Channel Admin

NVIDIAOfficialCreated by NVIDIA

Skill
Tool integration
Software development
Apache-2.0
Medium risk

From the author

Use this skill to enumerate host↔DPU DOCA comch (formerly Comm Channel) servers and connections via the shipped doca_comm_channel_admin binary — listing comch-capable devices and decoding the per-device server / connection table (server name, PID, in-use / max, PCIe address). The shipped binary is a SINGLE-SHOT SCAN-AND-PRINT tool with no registered arguments — NO list / inspect / drain / restart subcommands; one inventory pass over every comch-capable doca_dev on this side. Channel reset / drain / restart go to doca-comch (program side), doca-setup / doca-hardware-safety (driver reload), or BFB / RShim — NOT to this binary. Trigger on phrasings like "list comch servers", "which channels are active on this BlueField", or "verify admin tool sees same channel as program." Refuse and route elsewhere for the comch programming API, library install, protocol design, channel reset, or general orientation.

— the description by NVIDIA

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

This skill provides guidance for using the doca_comm_channel_admin binary to perform a read-only, single-shot inventory of DOCA Comm Channel (comch) servers and connections. It is designed for operators and agents needing to verify channel health or debug connectivity issues between a host and a DPU. The tool scans all comch-capable devices and outputs status tables, serving as an observability primitive to complement program-side debugging.

What it does

Invokes the doca_comm_channel_admin binary for a single-shot scan.
Enumerates comch-capable devices on the current system.
Decodes and prints server and connection tables including PIDs and PCIe addresses.
Provides a read-only view of channel state for diagnostic purposes.
Facilitates cross-checking between program-reported status and actual hardware state.

When to use it

When you need to list currently active comch channels on a host or DPU.
When debugging a silent stall or connection error in a Comch-using application.
When verifying that a channel is healthy before declaring a service ready.
When you need to capture a snapshot of channel state as evidence for deeper debugging.

Advantages

Provides an external, objective view of channel state independent of the application.
Simple, zero-argument execution model for quick inventory.
Helps distinguish between application-level logic errors and underlying channel connectivity issues.
Standardized approach for observability across different DOCA environments.

Usage examples

“Which comch servers and connections are currently visible?”: The agent executes the doca_comm_channel_admin tool to output the current SERVERS and CONNECTIONS tables.
“My program reports CONNECTED but the admin tool lists zero channels. What is happening?”: The agent uses the tool to verify the hardware-level view, then investigates representor binding or potential mismatches between the program and the admin tool's perspective.

Install

Download the skill as a ZIP:
https://autogineer.com/agent-skills/nvidia/doca-comm-channel-admin/download

Unzip it into the cross-client skills folder of your project:

mkdir -p .agents/skills && unzip doca-comm-channel-admin.zip -d .agents/skills

Documentation by NVIDIA

DOCA Comm Channel Admin Tool

Examples

"Which comch servers and connections are currently visible?" — this is in scope. Stay on the admin CLI; do not open a new comch channel from this skill.
"The program reports CONNECTED but the admin tool lists zero channels." — cross-check representor binding before rewriting the comch app.

Instructions

Follow Loading order below. Open the tasks companion for run / debug. Open the capabilities companion for table columns and error layers. Do not open every companion file.

Actual binary contract. doca_comm_channel_admin is one zero-application-argument, read-only scan-and-print operation. It scans every comch-capable doca_dev on the current side via resourcedump (MFT) and prints SERVERS and CONNECTIONS tables. It has no list, inspect, device-scope, drain, restart, or other application operation. This skill does not retain conceptual workflows under invented command names.

Where to start: This is a tool skill for invoking the DOCA Comm Channel Admin Tool — the read-only inventory CLI counterpart to the doca-comch/SKILL.md library. The shipped doca_comm_channel_admin binary takes no arguments beyond ARGP defaults (--help, --version, --log-level, --sdk-log-level, --json) and performs one inventory pass per invocation: it walks every doca_dev on this side, filters to comch-capable devices, shells out to resourcedump (MFT) on each, and prints two ASCII tables (SERVERS and CONNECTIONS). There is no list subcommand, no inspect subcommand, no drain flag, and no restart flag — those are not part of the tool's surface. Open the tasks companion and start at ## run for the single-shot invocation, or ## debug when the user reports the tool sees a different channel set than the program. Open the capabilities companion when the question is what the printed tables actually mean and what is not in this tool's scope. If the user has not installed DOCA yet, route to doca-setup/SKILL.md first; if the user needs MFT (resourcedump on PATH with the privilege documented for the installed release), doca-setup + doca-public-knowledge-map cover that. If the user is holding pre-2.5 docs that mention "Comm Channel", route to doca-comch/SKILL.md for the rename rule. If the user wants to change channel state, route to the program-side reconnect lifecycle in doca-comch/SKILL.md or to BlueField mode / driver reload in doca-setup/SKILL.md + doca-hardware-safety/SKILL.md — not to this tool.

Example questions this skill answers well

The CLASSES of admin-tool 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.

"Which comch servers and connections are currently visible?" — worked example: "print every server and connection row visible on this side". Answered by the scan-and-print surface in the capabilities companion
- the single invocation in the tasks companion.
"What does the tool report for this server or connection?" — locate the matching row in the SERVERS or CONNECTIONS table; there is no second per-channel query. Answered by the capabilities companion
- the tasks companion.
"How do I know the admin tool's view matches what my Comch program sees?" — worked example: "the program reports CONNECTED but the admin tool lists zero channels". Answered by the cross-checking pattern in the tasks companion and the representor-binding layer in the capabilities companion.
"Is this admin tool on my installed DOCA version, and does it match the comch library version?" — worked example: "is the tool available on DOCA 2.4". Answered by the overlay in the capabilities companion, which redirects to the canonical doca-version/SKILL.md rules and adds the Comm Channel Admin Tool specifics.
"The tool prints nothing — is the install broken or is there genuinely no channel?" — worked example: "list returned an empty result on a host with a known-good Comch client". Answered by the empty-output interpretation rules in the tasks companion + the capabilities companion.

Audience

This skill serves external operators and AI agents who need to inventory a host-DPU comch channel from the outside — after the doca-comch/SKILL.md library has been used to create the channel from a program. Concretely:

A platform operator who runs a Comch-using service on BlueField and needs to confirm the channel is healthy before declaring the service ready.
A developer of a Comch consumer who sees DOCA_ERROR_AGAIN or a silent stall on the program side and wants to read the channel's state from outside the program rather than guessing.
An AI agent capturing the external server/connection rows before recommending a program-side code or lifecycle change.

It is not for users debugging the admin tool itself, not a substitute for the live public DOCA Comm Channel Admin Tool guide, and not the right place for users learning the comch API — that audience belongs in doca-comch/SKILL.md.

The tool is shipped as a CLI binary under /opt/mellanox/doca/tools/, not a library you link against. The skill uses the same kind: tool three-file shape as the rest of the bundle so the agent's task-verb contract (configure / build / modify / run / test / debug) is uniform across libraries, services, and tools.

When to load this skill

Load this skill when the user is — or the agent needs to — invoke the DOCA Comm Channel Admin Tool on a real host or BlueField Arm with DOCA installed (or inside the public NGC DOCA container with the right device passthrough). Concretely:

Listing currently active comch channels on a host or DPU.
Reading the row for one named server or connection from the complete zero-argument scan.
Cross-checking the admin tool's view against the program-side connection callback state when the two appear to disagree.
Capturing a side-effect-free channel snapshot as prerequisite evidence for a later debug session that crosses program / channel / driver layers.

Do not load this skill for general DOCA orientation, the comch programming API, library install, or comch protocol design. For those, route to doca-public-knowledge-map/SKILL.md, doca-comch/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 the Comm Channel Admin Tool reports: the two read-only tables, the version-availability overlay that redirects to doca-version/SKILL.md, the layered error taxonomy (tool-not-installed / device-binding / channel-discovery / channel-state-stuck / permission / version / cross-cutting), the tool's role as an observability primitive for doca-comch/SKILL.md debug sessions, and the read-only safety policy.
the tasks companion — step-by-step workflows for the in-scope task verbs: configure (route to install), build (route to install), modify (refuse), run (one scan-and-print), test (cross-check the printed rows), debug (the layered diagnosis ladder), plus a Deferred task verbs block and a Command appendix that honors the bundle's doca-structured-tools-contract/SKILL.md preamble.

The skill assumes a host or BlueField where DOCA is already installed (or the public NGC DOCA container is running with the right device passthrough) and the operator has whatever privileges the public DOCA Comm Channel Admin Tool guide requires.

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:

Verbatim flag inventories, subcommand names, or output column names. The public DOCA Comm Channel Admin Tool guide on docs.nvidia.com and the installed --help on the user's version are the joint source of truth; copying them here pins the skill to one release and silently rots when the tool evolves. The skill routes the agent at those sources instead.
Pre-baked example output. Output is install-, version-, and channel-state-specific. A captured example will mislead an operator on a different platform / state.
Wrappers, parsers, or scripts in any language that consume the admin tool's output. The output format is documented; users who want to script against it should read the live guide and write the parser against their installed version.
A samples/ or reference/ subtree. This is a thin loader for a documented CLI; substantive material lives on the public page and in --help.

Loading order

Read this skill first to confirm the user's question is in scope (the user wants to inventory a comch channel from the outside, not learn the comch API).
For what the tool reports, version availability, the layered error surface, observability, and safety posture, see the capabilities companion.
For the single invocation and cross-check workflow — configure, build, modify, run, test, debug, plus the Command appendix — see the tasks companion.

doca-comch/SKILL.md — the library whose channels this tool inventories. Pair them in every triage session: the program-side connection callback and the admin tool's channel state are the two halves of the same picture.
doca-public-knowledge-map/SKILL.md — routing to the public DOCA Comm Channel Admin Tool guide and the rest of the public DOCA documentation set.
doca-version/SKILL.md — canonical DOCA version-handling rules. The ## Version compatibility section in the capabilities companion is a concise overlay that redirects here for the body.
doca-structured-tools-contract/SKILL.md — the bundle's detect → prefer → fall back → report contract for structured helper tools. The Command appendix in the tasks companion honors this contract.
doca-setup/SKILL.md — env preparation, install verification, representor visibility checks, and the I have no install yet path with the public NGC DOCA container. This skill assumes its preconditions are satisfied.
doca-debug/SKILL.md — the cross-cutting debug ladder. The Comm Channel Admin Tool slots in at the runtime layer as the read-only inventory surface before any code change is recommended.

Files

ATTRIBUTION.mdAdded by AutoGineer927 B
BENCHMARK.md10.5 KiB
CAPABILITIES.md12.6 KiB
LICENSELicence file added by AutoGineer11.2 KiB
SKILL.md11.9 KiB
SKILLCARD.yaml2.6 KiB
TASKS.md15.0 KiB
evals/evals.json2.5 KiB
skill-card.md4.7 KiB
skill.oms.sig5.1 KiB

CAPABILITIES.md

DOCA Comm Channel Admin Tool — Capabilities

Actual binary contract. The tool has one read-only operation: invoke it with zero application arguments, let it scan every comch-capable device on the current side through resourcedump (MFT), and read the SERVERS and CONNECTIONS tables. It has no per-device scope, per-row follow-up, or state-changing operation.

Where to start: The tool is a single admin CLI; the pattern overview below names the recurring admin-tool questions. Pick the pattern first, then drill into the H2 that owns the substance. For the how of executing each pattern, jump to TASKS.md. For the comch programming surface the channels were created against, see doca-comch/CAPABILITIES.md.

This file is loaded by SKILL.md. It documents what the tool reports, what versions it ships in, the layered error and observability surfaces, and its read-only safety policy.

Pattern overview

Every Comm Channel Admin Tool question this skill teaches resolves into one of THREE patterns. The patterns are CLASSES — they apply across every DOCA install that ships the tool, not just one platform.

Admin-tool pattern	Class shape	Where the substance lives
1. Scan and print	Run the zero-application-argument binary once; it scans every comch-capable device on this side and prints SERVERS and CONNECTIONS tables	`## Capabilities and modes` + TASKS.md ## run
2. Cross-check against the program	Match the relevant printed row with the program-side `doca_comch_*` connection callback; if needed, run the same zero-argument scan on the other side	`## Observability` + TASKS.md ## test
3. Diagnose empty / mismatched / failed output	Map absent rows or a `resourcedump` failure to the correct layer before any code change	`## Error taxonomy` + TASKS.md ## debug

Two cross-cutting rules that apply to every pattern above:

One invocation only. Do not synthesize a list, inspect, or device-selection argument. Locate the target in the printed rows or run the same zero-argument scan on the other side.
The admin tool is one half of the picture. The other half is the program-side doca_comch_* connection callback per doca-comch CAPABILITIES.md ## Observability (doca-comch/CAPABILITIES.md#observability). An agent that quotes the admin tool's state without the program side (or vice versa) is missing half the evidence.

Capabilities and modes

The DOCA Comm Channel Admin Tool ships as a CLI binary under /opt/mellanox/doca/tools/ on every DOCA install that includes the tool. There is no daemon, no library to link against, and no programmatic API; the user's entire interaction model is invoke the binary and read the two printed read-only tables. The binary registers ZERO application-level arguments. It performs only the scan-and-print operation described here.

The tool exposes a single, read-only family of operations, documented in the public DOCA Comm Channel Admin Tool guide (reached via doca-public-knowledge-map ## DOCA tools (doca-public-knowledge-map/SKILL.md#doca-tools)):

Read-only operations (the entire tool surface). The binary scans every DOCA device on the side it runs on (host or BlueField Arm), shells out to resourcedump for the devices that support a comch client / server, and prints two tables — a CONNECTIONS table and a SERVERS table — naming each channel's server name, owning PID, PCIe address, and interface (plus the connected / max-connection counts for servers). These cost nothing to run and are the agent's default reach when the user reports a Comch-side issue.

Changing channel or device state is outside this binary and this skill. Route program lifecycle work to doca-comch/SKILL.md, and driver or device work to doca-setup/SKILL.md plus doca-hardware-safety/SKILL.md.

The tool runs on both sides of a host ↔ DPU pair — the host sees host-side clients (each bound to a BlueField PCIe address), and the BlueField Arm sees the DPU-side server (bound to a host representor). The set of channels visible from one side is not necessarily symmetric with the other side; the cross-checking pattern in TASKS.md ## test is how the agent reconciles the two views.

There is no application subcommand or device-scope argument to discover. Use the zero-argument operation and read the table headings emitted by the installed binary.

Version compatibility

For the canonical DOCA version-detection chain, the four-way match rule, NGC container semantics, and the headers-win-over-docs rule, see doca-version/SKILL.md. The body lives there; this skill does not duplicate it.

The Comm Channel Admin Tool-specific overlay is:

The tool ships under the Comm Channel name even on DOCA installs ≥ 2.5. The companion library was renamed to doca-comch in DOCA 2.5 (see doca-comch CAPABILITIES.md ## Version compatibility (doca-comch/CAPABILITIES.md#version-compatibility) for the rename); the admin tool's public guide URL slug remains DOCA-Comm-Channel-Admin-Tool. An agent searching for "DOCA Comch Admin" on docs.nvidia.com should fall back to the Comm Channel Admin Tool guide and surface the naming asymmetry to the user, not assume the tool is missing.
Confirm the tool is present before assuming availability. If the user reports the binary is absent under /opt/mellanox/doca/tools/, the right answer is to confirm the installed DOCA version per doca-version TASKS.md ## configure (doca-version/TASKS.md#configure) and route to doca-setup/SKILL.md for an upgrade or reinstall, not to recommend a wrapper script that simulates the tool from outside.
Where it runs: on the x86 / Arm host that has DOCA installed, or on the BlueField Arm side. Same binary, same flags; the set of channels it sees differs by side per ## Capabilities and modes.
Tool version must match the comch *.so it inspects. A program built against one DOCA train inspected by an admin tool from a different train is the same partial-install hazard as case (a) ≠ (c) in the four-way-match rule. When in doubt, run pkg-config --modversion doca-comch and the tool's own --version per doca-version CAPABILITIES.md ## Version compatibility (doca-version/CAPABILITIES.md#version-compatibility) and quote both.

Error taxonomy

The error layers the agent should distinguish, in escalating order:

Tool-not-installed. The admin-tool binary does not exist under /opt/mellanox/doca/tools/. Cause: DOCA is not installed on this host, the install does not include the Comm Channel tooling subpackage, or the install version pre-dates the tool's availability. Routing: doca-setup ## install (doca-setup/TASKS.md#configure) and the version-compatibility overlay above.
resourcedump prerequisite / execution layer. The binary depends on the MFT resourcedump executable for each scanned device. If MFT is not installed, resourcedump is absent from PATH, privileges are insufficient, or a child invocation exits non-zero, capture the admin tool's exit status and full stderr plus the failing resourcedump exit/stderr. Do not interpret missing tables as “no channels.” Route MFT install, PATH, and privilege remediation to doca-setup ## debug (doca-setup/TASKS.md#debug), then rerun the same zero-argument scan.
Device-binding layer. The tool runs but cannot scan a DOCA device on this side. The underlying driver stack may be absent or the expected representor invisible. The tool's exit status, stderr, and resourcedump diagnostics are ground truth. Routing: doca-setup ## debug (doca-setup/TASKS.md#debug).
Row-discovery layer. The scan exits successfully and prints both tables, but the expected server or connection row is absent. Inspect the rows already printed; do not rerun with an invented device scope. Cross-check the program callback and, if necessary, run the same zero-argument scan on the other side. The program may never have reached the CONNECTED transition (route to doca-comch TASKS.md ## debug (doca-comch/TASKS.md#debug)), or the channel may already have been destroyed.
Version layer. The admin tool runs but its view of the channel disagrees with what the program-side doca_comch_* API reports — typically because the tool and the *.so came from different DOCA installs. This is a partial-install hazard; routing belongs in doca-version TASKS.md ## debug (doca-version/TASKS.md#debug) layer 2 and the overlay in ## Version compatibility above.
Cross-cutting layer. When the scan and program-side view disagree after the version match passes, the cause may be below the comch layer — driver, firmware, BlueField mode, or hardware. Escalate to doca-debug TASKS.md ## debug (doca-debug/TASKS.md#debug) with the captured admin-tool inspection plus the program-side trace as evidence.

doca_comm_channel_admin-class tooling does not itself return DOCA_ERROR_* values to a calling program — those are owned by the doca-comch/SKILL.md library API. The tool's CLI exit codes and printed messages are its own narrow surface; the agent maps those into the layers above before interpreting any program-side DOCA_ERROR_*.

Observability

The Comm Channel Admin Tool is itself an observability primitive for the rest of the comch surface — it is what other skills load to observe a comch channel from outside the program. Specifically:

doca-comch TASKS.md ## debug (doca-comch/TASKS.md#debug) layer 5 (runtime) prescribes confirming the channel's external state before any program-side code change; the admin tool's read-only enumeration + inspection is the documented way to produce that evidence.
doca-debug TASKS.md ## debug (doca-debug/TASKS.md#debug) consumes the captured admin-tool inspection as the channel-state half of the cross-cutting debug ladder, paired with the program-side connection-callback trace per doca-comch CAPABILITIES.md ## Observability (doca-comch/CAPABILITIES.md#observability) and (when present) the BlueField driver and firmware view via doca-setup CAPABILITIES.md ## Observability (doca-setup/CAPABILITIES.md#observability).
The admin tool's own output is the artifact downstream debug consumes. Save it (file, paste buffer, conversation artifact); without it, the next debug step starts guessing.

The tool does not emit metrics, traces, or DOCA logs of its own beyond the printed CLI output. For the program-side observability surface (DOCA_LOG_LEVEL, --sdk-log-level, the trace build flavor) see doca-debug CAPABILITIES.md ## Observability (doca-debug/CAPABILITIES.md#observability). For cross-checking against the BlueField driver / firmware / representor view, see doca-setup CAPABILITIES.md ## Observability (doca-setup/CAPABILITIES.md#observability).

Safety policy

Overlay on the bundle-wide hardware-safety meta-policy. The rules below are this skill's per-artifact overlay on the cross-cutting rules in doca-hardware-safety CAPABILITIES.md ## Safety policy (doca-hardware-safety/CAPABILITIES.md#safety-policy) (specifically ### Per-artifact overlay pattern (doca-hardware-safety/CAPABILITIES.md#per-artifact-overlay-pattern)). When the two layers disagree, the stricter wins; when either layer says STOP, the agent stops.

The Comm Channel Admin Tool is read-only:

Invoke only the zero-application-argument scan. Do not add list, inspect, device-scope, drain, restart, or other invented arguments.
Preserve evidence. Capture exit status, stdout tables, and stderr together. Quote relevant SERVERS / CONNECTIONS rows verbatim.
Fail closed on resourcedump. Missing MFT, a missing PATH entry, insufficient privilege, non-zero child exit, or child stderr is a setup failure, not an empty-channel result. Route to doca-setup/SKILL.md before interpreting the tables.

Public-source pointer

The single canonical public source for the DOCA Comm Channel Admin Tool is the DOCA Comm Channel Admin Tool page on docs.nvidia.com, reachable through doca-public-knowledge-map ## DOCA tools (doca-public-knowledge-map/SKILL.md#doca-tools). Do not invent application arguments or output columns beyond what that page and the installed binary document. For the comch library the channels were created against, the public source is the DOCA Comch page, reached the same way and named on the doca-comch/SKILL.md skill.

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

The author says: Requires DOCA SDK installed at /opt/mellanox/doca on Linux (Ubuntu 22.04/24.04 or RHEL/SLES) with the Comm Channel tooling subpackage so the CLI is present under /opt/mellanox/doca/tools/. Runs from either the x86/Arm host or the BlueField Arm side; a live host↔DPU comch channel created via the doca-comch library is needed for non-empty tables. The validation steps require a live DOCA install.

Security

What our scanner noticed· Medium risk

Large base64-encoded blobs

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Created by

NVIDIA

Publisher

NVIDIA (Official)

Source

NVIDIA/skills · skills/doca-comm-channel-admin · commit fce3cca

Licence

Apache License 2.0 (redistribution allowed)

LICENSE (added by AutoGineer from LICENSE-APACHE)
ATTRIBUTION.md (written by AutoGineer)

Synced

2026-11-09

AutoGineer is not affiliated with or endorsed by NVIDIA or NVIDIA.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download doca-comm-channel-admin.zip