doca-compress — Claude Code skill: setup and use
doca-compress is a Claude Code skill for moving DEFLATE compression and DEFLATE or LZ4 decompression to DOCA Compress. It activates for task setup, buffer checks, and accelerator errors.
Apache-2.0 140 installs ★ 4,106 updated 2026-10-23
npx skills add NVIDIA/skills --skill doca-compress -a claude-codeWhat doca-compress does
doca-compress guides setup of hardware compression and decompression through the DOCA Compress library, along with troubleshooting its calls. It covers DEFLATE in both directions and LZ4 decompression in stream or block mode. LZ4 encoding is unsupported.
The instructions cover task configuration, per-task buffer limits, mmap permissions, and a round-trip test. They also address when to use the accelerator versus the CPU. The prerequisite is the DOCA SDK installed at /opt/mellanox/doca on Linux, with a BlueField DPU or ConnectX NIC attached. If DOCA is not installed yet, start with doca-setup/SKILL.md.
What it helps with
- configure DEFLATE compression on BlueField or ConnectX
- decompress incoming DEFLATE or LZ4 data
- diagnose
INVALID_VALUEduring task initialization - check per-task buffer limits and mmap permissions
Example prompts for the agent
- Set up DEFLATE compression through DOCA Compress on BlueField.
- Find why the compression task returns
INVALID_VALUEduring initialization. - Configure LZ4 decompression for incoming data on ConnectX.
How to install doca-compress
1Skills CLI (Vercel)
npx skills add NVIDIA/skills --skill doca-compress -a claude-code2Manually: put the files in place
~/.claude/skills/doca-compress/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/doca-compress/
1Skills CLI (Vercel)
npx skills add NVIDIA/skills --skill doca-compress -a codex2Manually: put the files in place
.agents/skills/doca-compress/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add NVIDIA/skills --skill doca-compress -a cursor2Manually: put the files in place
.cursor/skills/doca-compress/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install NVIDIA/skills skills/doca-compress2Manually: put the files in place
.github/skills/doca-compress/SKILL.md1Skills CLI (Vercel)
npx skills add NVIDIA/skills --skill doca-compress -a gemini-cli2Platform CLI
gemini skills install https://github.com/NVIDIA/skills --path skills/doca-compressManually: put the files in place
.devin/skills/doca-compress/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add NVIDIA/skills --skill doca-compress -a opencodeClaude.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-compress
How do I install doca-compress in Claude Code?
Run npx skills add NVIDIA/skills --skill doca-compress -a claude-code. The skill file is placed at ~/.claude/skills/doca-compress/SKILL.md.
What does doca-compress do?
It guides hardware compression and decompression setup with DOCA Compress, including task parameters and error diagnosis. It covers DEFLATE and LZ4 decompression; LZ4 encoding is unsupported.
What does doca-compress require?
It requires the DOCA SDK installed at /opt/mellanox/doca on Linux and an attached BlueField DPU or ConnectX NIC. For an uninstalled DOCA SDK, use doca-setup/SKILL.md first.
Source text
SKILL.md · Apache-2.0
--- license: Apache-2.0 name: doca-compress description: > Hardware compression offload with DOCA Compress on a BlueField DPU, ConnectX NIC, or host: DEFLATE compress and decompress, plus LZ4 decompress (stream and block; LZ4 encode is NOT supported), instead of CPU zlib / zstd. Trigger on "offload this gzip", "decompress incoming network data on the NIC", "compress task returns INVALID_VALUE on alloc_init", "submitted a task but no completion arrives", or "decompress LZ4 on the BlueField", even without naming DOCA Compress. Covers enabling compress-deflate, decompress-deflate, decompress-lz4-stream and decompress-lz4-block tasks on a doca_compress context, sizing source / destination doca_buf against the per-task cap query, mmap permissions, offload vs CPU decisions, a round-trip smoke, and DOCA_ERROR_* from Compress calls. Refuse and route elsewhere for zstd / Snappy / brotli, LZ4 encode (a CPU LZ4 library), pure mmap-to-mmap copies (doca-dma), or DOCA Core lifecycle internals. metadata: author: NVIDIA <[email protected]> kind: library doca_version: "3.5" tags: - doca - compress - deflate compatibility: > Requires DOCA SDK installed at /opt/mellanox/doca on Linux (Ubuntu 22.04/24.04 or RHEL/SLES) with a BlueField DPU or ConnectX NIC attached. Reads the user's local install via `pkg-config doca-compress` and inspects /opt/mellanox/doca/{lib,include,samples,applications}. The validation steps require a live DOCA install. --- # DOCA Compress ## Examples - **"Offload this gzip on the BlueField."** — this is in scope if the codec is DEFLATE (or LZ4 decompress). Do not invent LZ4 encode or zstd offload. - **"Compress task returns INVALID_VALUE on alloc_init."** — size the `doca_buf` against the per-task cap query before changing the algorithm. ## Instructions Follow Loading order below. Open the tasks companion for configure / test / debug. Open the capabilities companion for codec support and buffer-size policy. Do not open every companion file. **Where to start:** This skill assumes DOCA is already installed and the user is doing **hands-on Compress work** (bulk DEFLATE compression or decompression) on a BlueField / ConnectX / host 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 DOCA Compress express* on this version. If the user has not installed DOCA yet, route to `doca-setup/SKILL.md` first. If the user is asking *"should I even offload this compression to the accelerator?"*, the size-threshold path-selection rule in ## Capabilities and modes is the first stop — bulk compress is the canonical fit, tiny one-shot is not. ## Example questions this skill answers well The CLASSES of DOCA Compress 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. - **"Should I offload this compression to DOCA Compress, or just zlib/zstd on the CPU?"** — worked example: *"I am compressing a 4 MiB log buffer before writing it to storage; is doca-compress worth the setup vs zlib on the CPU?"*. Answered by the size-threshold path-selection rule in ## Capabilities and modes + the *"when NOT to use doca-compress"* bullets in ## Safety policy. - **"Does my device support the compress (or decompress) task I want, and how big a buffer can it move per submission?"** — worked example: *"is `doca_compress_task_compress_deflate` on this BlueField, and what is the max source size per task?"*. Answered by the per-task capability-query rule (`doca_compress_cap_task_compress_deflate_is_supported`, `_decompress_deflate_is_supported`, the matching `_get_max_buf_size` queries) in ## Capabilities and modes + the discovery step in ## configure. - **"I just need to decompress incoming network data — is that a valid standalone use of doca-compress?"** — worked example: *"my client receives DEFLATE-compressed payloads and never produces any compressed output of its own"*. Answered by the *"decompression-only"* note in ## Capabilities and modes task-type table + the per-task configuration matrix in ## configure step 5. - **"What permissions does the source / destination mmap need?"** — worked example: *"my `doca_compress_task_compress_deflate` returns `DOCA_ERROR_NOT_PERMITTED`"*. Answered by the permission matrix in ## Safety policy + the mmap-set-permissions checklist in ## test. - **"Is this DOCA Compress API available on my installed DOCA version?"** — worked example: *"is `doca_compress_task_decompress_deflate` in the DOCA I have installed?"*. Answered by the version-compatibility overlay in ## Version compatibility, which cross-links the canonical detection chain in `doca-version/SKILL.md` and adds the Compress-specific *"discover per-task support, do not assume"* bullets. - **"What does this `DOCA_ERROR_*` from a Compress call mean and which layer caused it?"** — worked example: *"`DOCA_ERROR_INVALID_VALUE` on `doca_compress_task_compress_deflate_alloc_init`"*. Answered by the Compress overlay on the cross-library taxonomy in ## Error 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 Compress library** — i.e., users whose code calls `doca_compress_*` (directly in C/C++, or through FFI/bindings from another language) to offload bulk DEFLATE compression or decompression onto a BlueField DPU or ConnectX accelerator. It is *not* for NVIDIA developers contributing to DOCA Compress itself. **Language scope.** DOCA Compress ships as a C library with `pkg-config` module name `doca-compress`. The shipped samples are written in C. C and C++ consumers are the canonical case and 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 lifecycle, capability-discovery, permission, error-taxonomy, and compress-vs-decompress 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 Compress work, in any language. Concretely: - Initializing a `doca_compress` context on a `doca_dev` and configuring at least one task type (`doca_compress_task_compress_deflate` and/or `doca_compress_task_decompress_deflate`) before `doca_ctx_start()`. - Choosing between the **compress** task and the **decompress** task for the user's data flow. The two task types are independent: a consumer that only decompresses inbound DEFLATE payloads is a valid shape and does not need to enable the compress task. - Setting permissions on `doca_mmap` correctly for the source buffer (`DOCA_ACCESS_FLAG_LOCAL_READ_ONLY` at minimum) and the destination buffer (`DOCA_ACCESS_FLAG_LOCAL_READ_WRITE`). - Sizing the source buffer against the per-task `doca_compress_cap_task_*_get_max_buf_size(devinfo)` ceiling and the destination buffer against the worst-case output size the algorithm can produce on this input. - Checking which task types this device's accelerator advertises via `doca_compress_cap_task_compress_deflate_is_supported` and `doca_compress_cap_task_decompress_deflate_is_supported` against the active `doca_devinfo`. - Validating against a round-trip (compress → decompress, or decompress → compare against a known DEFLATE-encoded fixture) before pushing bulk input through the accelerator. - Deciding *whether to offload at all* — the size-threshold rule in ## Capabilities and modes says doca-compress is the right answer only for bulk inputs (rule of thumb: ≥ a few KiB); below that, CPU compression beats the DMA-to-accelerator round-trip. - Debugging a `DOCA_ERROR_*` returned from a Compress call (lifecycle vs. buffer-sizing vs. permission vs. unsupported-task) and the task-completion event on the progress engine. - Designing or extending non-C bindings (Rust, Go, Python, …) that wrap the Compress C ABI — for the lifecycle, permission, capability, and compress-vs-decompress rules the wrapper must honor. Do **not** load this skill for general DOCA orientation, install of DOCA itself, non-DEFLATE compression libraries on CPU (use zlib / zstd / similar), or other DOCA libraries. 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 Compress-specific material lives in two companion files: - the capabilities companion — what DOCA Compress can express on this version: the four task types (compress-deflate, decompress-deflate, decompress-lz4-stream, and decompress-lz4-block, each independently capability-gated), the per-task capability-query surface (`doca_compress_cap_*` for task support and per-submission max buffer size), the Compress error taxonomy (mapped onto the cross-library `DOCA_ERROR_*` set), the observability surface (per-task completion events on the progress engine), the safety policy that gates source / destination mmap permission decisions, and the size-threshold path-selection rule (when to use doca-compress versus CPU compression or `doca-dma` for the no-compression copy case). - the tasks companion — step-by-step workflows for the six in-scope Compress verbs: `configure`, `build`, `modify`, `run`, `test`, `debug`. Plus a `## rollback` overlay (Compress-specific five-step teardown that drains in-flight tasks before `doca_ctx_stop`, unregisters mmap regions in reverse-register order, and re-verifies the device path with the round-trip smoke) and the 5-phase universal debug-loop instantiation appended to `## debug`. Plus a `Deferred task verbs` block that points out-of-scope questions at the right next skill. The skill assumes a host or BlueField where DOCA is already installed at the standard location and the user has the privileges their public install profile expects. 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 Compress application source code, in any language.** The verified Compress source code is the shipped C samples at `/opt/mellanox/doca/samples/doca_compress/`, plus the File Compression reference application linked from the public DOCA Compress guide. 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 in `doca-programming-guide/SKILL.md`, layered with the Compress-specific overrides in ## modify. - **Pre-encoded DEFLATE fixtures for arbitrary inputs.** The skill tells the agent to use a *round-trip* validation (compress → decompress and compare to the original, or decompress a known DEFLATE blob produced by a published CPU encoder like `zlib`) as the known-good smoke; it does not ship a fixture bank of its own. - **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, where `pkg-config --modversion doca-compress` is the source of truth. - **A `samples/`, `bindings/`, or `reference/` 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 1. Read this skill first to confirm the user's question is in scope. 2. **For the Compress capability matrix, the compress / decompress task split (including decompression-only as a standalone shape), per-task capability-query rules, permission matrix, error taxonomy, observability, and safety / path-selection policy, see the capabilities companion.** 3. **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 "Compress-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 DOCA Compress page lives at `docs.nvidia.com/doca/sdk/DOCA-Compress/`; the File Compression reference application is the canonical worked example. - `doca-setup/SKILL.md` — env preparation, install verification, 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 compatibility` cross-links the four-way match rule and adds only the Compress-specific *"discover per-task support + per-task max buffer size via cap query"* 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 canonical `pkg-config` + meson build pattern, the universal modify-a-shipped-sample first-app workflow, the universal lifecycle, the cross-library `DOCA_ERROR_*` taxonomy, and the program-side debug order. This skill layers Compress specifics on top. - `doca-dma/SKILL.md` — the right library when the data flow is a pure mmap-to-mmap copy with no compression required. This skill's path-selection rule routes to DMA when Compress is *not* the answer (e.g. the user only wants to move bytes, not encode them). - `doca-debug/SKILL.md` — the cross-cutting debug ladder (install / version / build / link / runtime / program / driver). Compress-specific debug (task-not-supported, source-buffer-too-large, destination-buffer-too-small) overlays on top of that ladder.
© NVIDIA · Apache-2.0 · NVIDIA/skills