/doca-version

license: Apache-2.0
name: doca-version
description: >
  Use this skill when the user is doing DOCA version handling —
  detecting the installed release, validating the four-way match
  across pkg-config doca-common, applications/VERSION, doca_caps
  --version, and bfver/mlnx-release on BlueField, reasoning about
  NGC container tags, looking up whether a capability is on the
  installed release, or diagnosing build-vs-runtime drift. Trigger
  even when the user does not explicitly say "DOCA version" or
  "four-way match" — typical implicit phrasings include "program
  built but does nothing on the wire", "undefined reference to a
  symbol the docs claim exists", "DOCA_ERROR_NOT_SUPPORTED at
  runtime", "counter didn't increment", "what does `latest` mean
  for this tag", or "is my LTS still supported". Refuse and route
  elsewhere for installing or choosing DOCA packages (doca-setup),
  per-library API/capability questions (matching library skill),
  the cross-library DOCA_ERROR_* taxonomy (doca-programming-guide),
  or the general debug ladder (doca-debug) — those belong to other
  skills.
metadata:
  kind: library
compatibility: >
  No DOCA install required to read this skill (it is an overlay
  loaded against any DOCA artifact skill); the validation steps
  within DO require a live DOCA install at /opt/mellanox/doca.

DOCA version

**Where to start:** This skill is the bundle's single source of truth for DOCA *version handling*. Open [`TASKS.md`](TASKS.md) if the user wants to *do* something with the version (detect / validate / diagnose mismatch); open [`CAPABILITIES.md`](CAPABILITIES.md) when the question is *what does version handling cover* (the four-way match, the detection chain, NGC semantics, the per-library overlay pattern). Every other skill in the bundle that touches version routes here — they MUST NOT redefine the rules.

Example questions this skill answers well

The CLASSES of version-handling 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.

• **"What DOCA version do I actually have installed?"** — worked

example: *"the docs say 3.3 but I'm not sure what's on this host"*. Answered by the canonical detection chain in [`TASKS.md ## configure`](TASKS.md#configure) + [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes) source-of-truth table.

• **"My program built but does nothing on the wire — is my install

consistent?"** — worked example: *"`pkg-config --modversion` says 3.3.0; `doca_caps --version` says 3.2.0"*. Answered by the four-way match rule in [`CAPABILITIES.md ## Version compatibility`](CAPABILITIES.md#version-compatibility)

• the partial-install diagnosis in

[`TASKS.md ## debug`](TASKS.md#debug).

• **"Is this DOCA capability / API / sample on the version I

have?"** — worked example: *"is the symmetric-RSS hash mode in Flow 2.6.0"*. Answered by the version-matrix lookup procedure in [`TASKS.md ## test`](TASKS.md#test) (which uses the `version-matrix.json` schema defined in [`doca-structured-tools-contract`](../doca-structured-tools-contract/SKILL.md#schemas) with fallback to per-library docs via [`doca-public-knowledge-map`](../doca-public-knowledge-map/SKILL.md)).

• **"Can I run my host package version X against BFB version Y?"** —

worked example: *"host is 3.3.0 LTS, BlueField BFB is 3.1.0"*. Answered by the routing to the [DOCA Compatibility Policy](https://docs.nvidia.com/doca/sdk/doca-compatibility-policy/index.html) documented in [`CAPABILITIES.md ## Version compatibility`](CAPABILITIES.md#version-compatibility).

• **"I'm inside the NGC DOCA container — what does the version

match look like?"** — worked example: *"do I still need to check pkg-config / applications/VERSION / doca_caps separately?"*. Answered by the NGC container rule in [`CAPABILITIES.md ## Version compatibility`](CAPABILITIES.md#version-compatibility)

• the container path in

[`TASKS.md ## configure`](TASKS.md#configure).

• **"How do I write a per-library version-compatibility section

for a new skill?"** — worked example: *"adding `doca-comch` to the bundle, what does its `## Version compatibility` look like?"*. Answered by the per-library overlay pattern in [`CAPABILITIES.md ## Safety policy`](CAPABILITIES.md#safety-policy)

• the worked-example template in

[`TASKS.md ## modify`](TASKS.md#modify).

• **"My `apt list` shows DOCA `3.3.0109`, but `/etc/apt/sources.list.d/doca.list`

is pinned at `latest` / a different release — is the next `apt install doca-*` going to silently upgrade me?"** — worked example: *"I rolled back BFB to 3.1.0105 but my sources still point at the latest channel."* Answered by the apt-source consistency precheck in [`TASKS.md ## apt-source consistency`](TASKS.md#apt-source-consistency), which enumerates the three legitimate shapes of a configured DOCA apt source (network URL, local file-repo, RHEL/OEL equivalent) and the *do-not-install-until-the-source-matches* rule that protects pinned installs from accidental drift.

When to load this skill

Load this skill whenever version handling is the load-bearing concern. The decision must be made **before** the agent composes its first sentence — the activation checklist below is the same one referenced from [`AGENTS.md ## Cross-cutting overlay activation triggers`](../../AGENTS.md#cross-cutting-overlay-activation-triggers), mirrored here so the activation rule is at hand whenever this skill is consulted.

Agent activation checklist — load this skill at the START of the answer when any cell below is true

| Trigger class | Concrete prompt-side signals (any one fires the overlay) | | --- | --- | | Direct version question | *"what DOCA version do I have"*, *"is X consistent"*, *"is feature Y supported on version Z"*, *"can I mix host package version A with BFB versi