doca-version

Files (7)

• BENCHMARK.md
• CAPABILITIES.md
• SKILL.md
• TASKS.md
• evals.json · evals/
• skill-card.md
• skill.oms.sig

SKILL.md (first lines)

# DOCA version

## Examples

- **"What DOCA version do I actually have installed?"** — run the
  four-source detection chain and require a four-way match.
- **"The program built but does nothing on the wire."** — treat
  mixed-install drift as a version problem before rewriting application
  code.

## Instructions

Follow Loading order below. Open the tasks companion for detect /
validate / diagnose, and the capabilities companion for the four-way
match and NGC tag rules. Do not open every companion file.

**Where to start:** This skill is the bundle's single source of
truth for DOCA *version handling*. Open
the tasks companion if the user wants to *do* something with the
version (detect / validate / diagnose mismatch); open
the capabilities companion 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
  ## configure +
  ## 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
  ## Version compatibility
  + the partial-install diagnosis in
  ## 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
  ## test (which uses the
  `version-matrix.json` schema defined in
  `doca-structured-tools-contract/SKILL.md#schemas`
  with fallback to per-library docs via
  `doca-public-knowledge-map/SKILL.md`).
- **"Can I run my host package version X against BFB version Y?"** —
  worked example: *"host is 3.5.0 GA, BlueField BFB is 3.2.3 LTS"*.
  Answered by the routing to the
  [DOCA Compatibility Policy](https://docs.nvidia.com/doca/sdk/doca-compatibility-policy/index.html)
  documented in
  ## 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
  ## Version compatibility
  + the container path in
  ## 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
  ## Safety policy
  + the worked-example template in
  ## 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
  ## 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` (bundle `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 version B"*, *"is my LTS still supported"*, *"what does the version string mean"* |
| Container tag question | any prompt that mentions a specific NGC container tag, or asks about `latest`, or asks how to pin a tag in a Dockerfile / pod spec / Compose file. The agent MUST also cite the *"never invent a tag string from memory, never quote `latest` without confirming it"* rule from ## Safety policy. |
| Build vs runtime drift | any debug session where the symptom is *"the program built fine but DOCA_ERROR_NOT_SUPPORTED at runtime"*, *"undefined reference to a symbol the docs say exists"*, *"my code does nothing on the wire"*, *"counter didn't increment"* — these are the canonical partial-install symptoms |
| Upgrade / downgrade plan | the user is planning to upgrade or downgrade DOCA on a host already running other DOCA workloads, or to refresh the BFB on a BlueField pair already attached to a host |
| Per-artifact cross-link | a per-artifact skill's `## Version compatibility` section cross-links here for the rule body, OR the agent is about to author a new per-artifact skill and needs the overlay template |

When any cell above fires, the agent MUST:

1. Cite the **four-source detection chain** from ## Capabilities and modes explicitly in the answer — `pkg-config --modversion doca-common` → `cat /opt/mellanox/doca/applications/VERSION` → `doca_caps --version` → `bfver` plus `cat /etc/mlnx-release` (BlueField hosts). Do not paraphrase or summarize the chain; cite the commands by name. Do NOT substitute `mlxprivhost` or `bfb-info` for the BFB leg — those are common hallucinations and the bundle explicitly bans them in ## Capabilities and modes.
2. State the **four-way match rule** from ## Version compatibility verbatim if the prompt could possibly involve a mismatch (every deploy-shape question and every debug-shape question can; orientation-shape questions usually cannot).
3. Refuse to invent a version string. If the agent doesn't have the actual `pkg-config --modversion` output from the user's host, the answer must say so and route to the detection chain — not assert a version from training-data recall.

## Universal version-coherence trigger

Whenever ANOTHER overlay (e.g. `doca-setup/SKILL.md`, `doca-hardware-safety/SKILL.md`, `doca-container-deployment/SKILL.md`, `doca-bare-metal-deployment/SKILL.md`) calls a `## test` / `## configure` / `## modify` step that requires *"the install is healthy"* or *"versions are consistent"*, that step MUST resolve to a citation of this skill's four-source detection chain and four-way match rule. The agent does NOT redefine the rule per-overlay — every step that needs a version verification must route here. This is the *only* place in the bundle that owns the rule body.

Do **not** load this skill for general DOCA orientation, for
install procedures (use `doca-setup/SKILL.md`),
or for library-specific API questions (use the matching library

From NVIDIA/skills, Apache-2.0.

More from NVIDIA/skills