Skip to main content
skill CX Codex

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

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add NVIDIA/skills --skill doca-compress -a claude-code
Open on GitHub

What 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_VALUE during 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_VALUE during 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-code

2Manually: put the files in place

~/.claude/skills/doca-compress/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/doca-compress/

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

Similar skills

All skills for DevOps and infrastructure →

From the same set312

The whole set →

Project sponsors

Companies that keep this analytics open