Enables agents to manage host-to-DPU PCIe control-plane messaging using server/client roles and slow-path or fast-path communication modes.
- GitHub stars
- 3,934
- Files
- 8
- Last commit
- Nov 11, 2026
- License
- Apache-2.0
- Allowed tools
- —
What does the doca-comch skill do?
doca-comch enables agents to manage host-to-DPU PCIe control-plane messaging using server/client roles and slow-path or fast-path communication modes.
Summary generated from the skill's SKILL.md.
About the doca-comch skill
Developers building applications that exchange control or data messages between a host and a BlueField DPU over PCIe can use this skill to manage DOCA Comch communication. It assists with configuring server and client roles, selecting between slow-path message-oriented modes and fast-path producer-consumer modes, and querying hardware capabilities like maximum message size. The skill is intended for hands-on work involving the doca_comch_* API on Linux systems with a live DOCA installation.
When an agent loads this skill, it provides guidance on lifecycle workflows, error debugging for DOCA_ERROR_* returns, and version-specific changes such as the rename from Comm Channel to Comch in version 2.5. It relies on the local DOCA SDK installation at /opt/mellanox/doca and uses pkg-config to verify the library. The skill acts as a thin loader that directs users to specialized companion files for detailed capability matrices or step-by-step tasks like building, running, or testing Comch applications.
What an agent can do with it
- 1Debug API error codesIdentify the cause of specific DOCA_ERROR returns during Comch task submissions or server creation.
Written from the skill's SKILL.md. Every use case is checked against a quote from it.
How to install the doca-comch skill
Each command copies the skill folder into the client's skills directory. Restart the client or start a new session to load it.Install the doca-comch skill in Claude Code
~/.claude/skills/doca-comch/SKILL.md
$ npx degit NVIDIA/skills/skills/doca-comch ~/.claude/skills/doca-comchInstall the doca-comch skill in Claude Code (project)
.claude/skills/doca-comch/SKILL.md
$ npx degit NVIDIA/skills/skills/doca-comch .claude/skills/doca-comchInstall the doca-comch skill in Codex
~/.agents/skills/doca-comch/SKILL.md
$ npx degit NVIDIA/skills/skills/doca-comch ~/.agents/skills/doca-comchInstall the doca-comch skill in Gemini CLI
~/.gemini/skills/doca-comch/SKILL.md
$ npx degit NVIDIA/skills/skills/doca-comch ~/.gemini/skills/doca-comchInstall the doca-comch skill in Claude.ai
npx degit NVIDIA/skills/skills/doca-comch doca-comch && zip -r doca-comch.zip doca-comch # claude.ai → Customize → Skills → + → Create skill → Upload a skill → doca-comch.zip
Automated checks
Ran Nov 15, 2026Full report →Passed our automated checks. That is not a security audit: read the scripts before you let an agent run them. How checks work
- Source repository linked and reachablenvidia/skills/skills/doca-comch is public and reachablegithub.com/nvidia/skills/tree/HEAD/skills/doca-comch ↗Pass
- Open source license (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗Pass
- Commit or release in the last yearLast commit 2026-11-11github.com/nvidia/skills/commits ↗Pass
- No download-and-run or credential theft in scriptsNo scripts in the skill folderPass
- No hidden instructions in SKILL.mdNo override phrases, safeguard switches, credential requests or hidden charactersgithub.com/nvidia/skills/blob/HEAD/skills/doca-comch/SKILL.m ↗Pass
- Pre-approved tools are scopedNo pre-approved tools; the agent asks before using onegithub.com/nvidia/skills/blob/HEAD/skills/doca-comch/SKILL.m ↗Pass
- SKILL.md follows the Agent Skills formatValid name and description; says when to use it; 275 linesgithub.com/nvidia/skills/blob/HEAD/skills/doca-comch/SKILL.m ↗Pass
SKILL.md
View on GitHubDOCA Comch
Examples
- "Send a control message from host to BlueField over PCIe." — this is in scope. Pick server (DPU) vs client (host) and stay on the Comch send/recv path; do not fall back to TCP.
- "Connect callback never fires." — check role, representor visibility, and the 2.5 rename overlay before rewriting the app as raw verbs.
Instructions
Follow Loading order below. Open the tasks companion for configure / modify / debug. Open the capabilities companion for slow-path vs fast-path and the 2.5 rename. Do not open every companion file.
Where to start: This skill assumes DOCA is already installed and
the user is doing hands-on Comch work on a BlueField + host
pair with DOCA. Open the tasks companion if the user wants to
do something (configure / build / modify / run / test / debug);
open the capabilities companion when the question is
what can Comch express on this version. If the user has not
installed DOCA yet, route to
doca-setup/SKILL.md first. If the user is
asking "is Comch even on this DOCA" because the docs they read
mention doca-comm-channel, route to
Version compatibility
for the 2.5 rename.
Example questions this skill answers well
The CLASSES of Comch questions this skill is built to answer, each with one worked example. The agent should treat the class as the load-bearing piece — the worked example is a single instance.
- "How do I bring up a Comch channel between host and DPU?" —
worked example: "server side on the DPU, client side on the
host, exchange a first control message". Answered by the
role-selection + lifecycle workflow in
configure +
Capabilities and modes
server-vs-client table. - "How do I move bulk data over Comch with low CPU?" — worked
example: "stream a 64 KiB chunk every 100 µs from the host
driver to a DPU agent". Answered by the producer / consumer
fast-path described in
Capabilities and modes
- the channel-setup workflow in
configure
step 4, with the "slow-path vs fast-path" selection rule. - "What is the maximum message size I can send?" — worked
example: "can I send a 4 MiB control message in one shot?".
Answered by the capability-query rule
(
doca_comch_cap_get_max_msg_size) inCapabilities and modes
- the property-set workflow in
modify.
- "Why doesn't the DPU side see the representor?" — worked
example: "
doca_comch_server_createreturnsDOCA_ERROR_NOT_PERMITTEDon a freshly imaged BlueField". Answered by the representor + permission overlay inSafety policy
- the env-prep checklist in
configure step 1, which
routes representor-side env questions todoca-setup/SKILL.md. - "Is this Comch capability on my installed DOCA version?" —
worked example: "is
doca_comch_producerin DOCA 2.6.0, or do I still need the old slow-path API?". Answered by the version-compatibility overlay inVersion compatibility,
which cross-links the canonical detection chain indoca-version/SKILL.mdand adds the Comch-specific 2.5 rename rule. - "What does this
DOCA_ERROR_*from a Comch call mean and which layer caused it?" — worked example: "DOCA_ERROR_AGAINon submitting adoca_comch_task_sendviadoca_task_submit". Answered by the Comch overlay on the cross-library taxonomy inError taxonomy
- the layered ladder in
debug that escalates to
doca-debug/SKILL.md.
Audience
This skill serves external developers building applications that
consume the DOCA Comch library — i.e., users whose code calls
doca_comch_* (directly in C/C++, or through FFI/bindings from
another language) to exchange control or data messages between a
host process and a BlueField agent over PCIe. It is not for
NVIDIA developers contributing to DOCA Comch itself.
Language scope. DOCA Comch ships as a C library with
pkg-config module name doca-comch. The shipped samples are
written in C. C and C++ consumers are the canonical case; the
worked examples in the tasks companion assume that path. Other-language
consumers (Rust, Go, Python, …) consume the same *.so through
FFI or language-specific bindings; the skill's contribution in
that case is to keep the role-split, lifecycle,
capability-discovery, permission, and error-taxonomy guidance
language-neutral, and to route the agent to the public C ABI as
the authoritative surface that any wrapper will eventually call.
When to load this skill
Load this skill when the user is doing hands-on DOCA Comch work, in any language. Concretely:
- Initializing a
doca_comch_serveron the DPU side or adoca_comch_clienton the host side, on a representor or PCIe address the host can reach. - Configuring at least one of: a recv callback for slow-path
messages, a producer for fast-path outbound data, a consumer for
fast-path inbound data, before
doca_ctx_start(). - Reading or setting comch properties via
doca_comch_set_*anddoca_comch_cap_get_*— max message size, max number of clients (server side), producer / consumer queue sizing. - Establishing a connection between the two sides and reacting to connection-state transitions via the connection callbacks registered before start.
- Choosing between the slow-path (send-task / recv-callback, message-oriented, lower throughput, single-call simplicity) and the fast-path (producer / consumer, asynchronous, much higher throughput, two-context setup).
- Debugging a
DOCA_ERROR_*returned from a Comch call (lifecycle vs. permission vs. capability vs. would-block) and the connection state machine across the host / DPU pair. - Designing or extending non-C bindings (Rust, Go, Python, …) that wrap the Comch C ABI — for the lifecycle, role-split, permission, and capability rules the wrapper must honor.
Do not load this skill for general DOCA orientation, install
of DOCA itself, or non-Comch library questions. For those, use
doca-public-knowledge-map/SKILL.md.
What this skill provides
This is a thin loader. The body keeps only the orientation needed to pick the right next file. The substantive Comch-specific material lives in two companion files:
- the capabilities companion — what Comch can express on this version: the
server vs client role split, the slow-path send-task /
recv-callback surface, the producer / consumer fast-path
surface, the capability-query surface
(
doca_comch_cap_get_*), the Comch error taxonomy (mapped onto the cross-libraryDOCA_ERROR_*set), the observability surface (connection state callbacks, task completion callbacks), and the safety policy that gates representor and permission decisions. - the tasks companion — step-by-step workflows for the six in-scope Comch
verbs:
configure,build,modify,run,test,debug. Plus aDeferred task verbsblock that points out-of-scope questions at the right next skill.
The skill assumes a host + BlueField pair where DOCA is already
installed at the standard location and the user has the privileges
their public install profile expects (in particular, sudo on the
DPU side to see the host representor). It does not cover installing
DOCA — that path goes through
doca-setup/SKILL.md.
What this skill deliberately does not ship
This skill is agent guidance, not a samples or templates bundle. To keep the boundary clean, it deliberately does not contain — and pull requests should not add:
- Pre-written DOCA Comch application source code, in any
language. The verified Comch source code is the shipped C
samples at
/opt/mellanox/doca/samples/doca_comch/<name>/. The agent's job is to route the user to those files and prescribe a minimum-diff modification on them via the universal modify-a-sample workflow indoca-programming-guide/SKILL.md, layered with the Comch-specific overrides inmodify.
- Standalone build manifests (
meson.build,CMakeLists.txt,Cargo.toml, …) parked inside the skill. The agent constructs the build manifest in the user's project directory against the user's installed DOCA, wherepkg-config --modversion doca-comchis the source of truth. - A
samples/,bindings/, orreference/subtree of any kind. A mock or incomplete artifact in this skill's tree, even one labeled "reference", is misleading: users will read it as buildable.
Loading order
- Read this skill first to confirm the user's question is in scope.
- For the Comch capability matrix, role split, slow-path / fast-path surfaces, permission policy, error taxonomy, observability, and safety policy, see the capabilities companion.
- For step-by-step workflows — configure, build, modify, run, test, debug — see the tasks companion.
Both companion files cross-link to each other,
doca-version/SKILL.md for the canonical
version-handling rules, and
doca-public-knowledge-map/SKILL.md
whenever the right answer is "look it up in the public docs or
the installed package layout" rather than "Comch-specific
guidance".
Related skills
doca-public-knowledge-map/SKILL.md— the routing table for every public DOCA documentation source and the on-disk layout of an installed DOCA package. The Comch URL slug isDOCA-Comch(DOCA 2.5+), notdoca-comm-channel.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-version/SKILL.md— canonical DOCA version-handling rules. This skill's## Version compatibilitycross-links the four-way match rule and adds the Comch-specific 2.5 rename overlay.doca-structured-tools-contract/SKILL.md— the bundle's structured-tools precedence rule (detect / prefer / fall back / report). The Command appendix in the tasks companion honors this contract.doca-programming-guide/SKILL.md— general DOCA programming patterns shared by every library: the canonicalpkg-config+ meson build pattern, the universal modify-a-shipped-sample first-app workflow, the universal lifecycle, the cross-libraryDOCA_ERROR_*taxonomy, and the program-side debug order. This skill layers Comch specifics on top.doca-debug/SKILL.md— the cross-cutting debug ladder (install / version / build / link / runtime / program / driver). Comch-specific debug (lifecycle violations, representor visibility, slow-path vs fast-path queue-full symptoms) overlays on top of that ladder.
Files in this skill
8doca-comch skill questions
How do I install the doca-comch skill in Claude Code?
Run npx degit NVIDIA/skills/skills/doca-comch ~/.claude/skills/doca-comch. Claude Code loads skills from ~/.claude/skills (all projects) or .claude/skills (one project) and uses a skill when its description matches the task.
Which clients can use the doca-comch skill?
Any client that reads the Agent Skills format: Claude Code, Codex, Gemini CLI and claude.ai (upload as a ZIP). Scripts in the skill run only where the client allows code execution.
How do I bring up a Comch channel between host and DPU?
You should set up the server side on the DPU and the client side on the host, then exchange a first control message using the role-selection and lifecycle workflow.
What is the difference between slow-path and fast-path in Comch?
The slow-path uses send-task and recv-callback for message-oriented communication with lower throughput, while the fast-path uses producer/consumer modes for high-throughput asynchronous data streaming.
Can I send a 4 MiB control message in one shot?
You must first query the maximum message size capability using the doca_comch_cap_get_max_msg_size function to verify if your message fits.