doca-caps

DOCA Capabilities Print Tool (doca_caps)

Examples

• "What DOCA devices does this host see?" — this is in scope. Stay on doca_caps; do not start a library-internal capability matrix here.
• "Is Flow available on my RHEL host?" — list libraries then scope per-device if needed.

Instructions

Follow Loading order below. Open the tasks companion for run / test. Open the capabilities companion for what the CLI reports. Do not open every companion file.

Where to start: This is a tool skill for invoking doca_caps, a side-effect-free CLI. Open the tasks companion and start at ## run for the documented invocations, or ## test when using doca_caps as an install smoke-test. Open the capabilities companion when the question is what kinds of capability families doca_caps reports.

Boundary: this skill never installs DOCA. doca_caps verifies an install and never performs one. A request to install DOCA — choosing packages, adding repositories, running a package manager — is out of scope here, and stays out of scope even though this skill's ## test verb uses the tool as an install smoke-test afterwards. Hand the whole request to doca-setup/SKILL.md by name. Naming the owner and then listing the steps anyway is the failure mode to avoid: do not walk the installation, not even as a summary or a caveat.

This narrows installation only. It is not a reason to answer narrowly about tooling: when the user's question reaches past doca_caps — what else can I ask this hardware, how do I measure it, how do I inspect a running pipeline — name the sibling tool that owns it (doca_bench, doca_flow_tune, pcc_counters.sh, doca_comm_channel_admin, …) and tie it to the question. Pointing at the rest of the catalog is this skill's job, not a boundary breach.

Example questions this skill answers well

The CLASSES of doca_caps questions this skill is built to answer, each with one worked example. The class is the load-bearing piece; the worked example is one instance.

• "What DOCA devices does this host see?" — worked example: "is my BlueField PF visible to DOCA". Answered by the device enumeration in the capabilities companion
  • the --list-devs invocation in the tasks companion.
• "Which DOCA libraries are available on this OS?" — worked example: "is Flow available on my RHEL host". Answered by the library-availability surface in the capabilities companion
  • the library-listing invocation in the tasks companion.
• "Does this device support library X capability Y?" — worked example: "does this device support Flow hairpin?". Answered by the per-device per-library capability matrix in the capabilities companion
  • the --pci-addr-scoped invocation in the tasks companion.
• "What representors are visible to DOCA?" — worked example: "enumerate VF representors for pf0". Answered by the representor enumeration in the capabilities companion
  • the --list-rep-devs invocation in the tasks companion.
• "I want a snapshot of state to attach to my debug session." — worked example: "save device + library + capability output to a file". Answered by the snapshot workflow in the tasks companion and consumed by doca-debug/SKILL.md step 3 (read-only triple) and doca-programming-guide/SKILL.md.
• "doca_caps returned nothing for capability Y — what does that mean?" — worked example: "empty output for RDMA". Answered by the empty-output interpretation rules in the tasks companion + the capabilities companion.

Audience

This skill serves external operators, developers, and AI agents who need a side-effect-free way to ask "what does DOCA see on this host?" before doing anything that changes state. Concretely:

• An external developer who installed DOCA (or is using the public NGC DOCA container per doca-setup/SKILL.md) and wants to confirm the install can see hardware before writing code.
• A platform operator deploying a DOCA service who wants a documented, read-only snapshot of which DOCA libraries this host actually supports and which capabilities each DOCA device offers.
• An AI agent producing a capability snapshot artifact during the documented setup or programming-guide debug procedures (it's listed as the canonical first step in doca-setup/SKILL.md and doca-programming-guide/SKILL.md).

It is not for users debugging doca_caps itself, and not a substitute for the live public Capabilities Print Tool guide.

doca_caps is shipped as a tool (a single CLI binary), not a library you link against. The skill uses the same kind: tool three-file shape as the rest of the bundle so the agent's task-verb contract (configure / build / modify / run / test / debug) is uniform across libraries, services, and tools — even when individual verbs collapse to a routing stub for a shipped read-only binary.

When to load this skill

Load this skill when the user is — or the agent needs to — invoke doca_caps on a real host with DOCA installed (or inside the public NGC DOCA container). Concretely:

• Running doca_caps --list-devs to enumerate DOCA devices.
• Running doca_caps --list-rep-devs to enumerate representor devices.
• Scoping output to a specific PCIe address with --pci-addr.
• Listing the DOCA libraries the install reports as available on the current OS.
• Listing the available DOCA logger names.
• Capturing a documented, side-effect-free capability snapshot as prerequisite evidence for later ## debug workflows.

Do not load this skill for general DOCA orientation, library API work, or installation. For those, use doca-public-knowledge-map/SKILL.md, the matching libs/<library> skill, or doca-setup/SKILL.md.

What this skill provides

This is a thin loader. Substantive material lives in two companion files:

• the capabilities companion — what doca_caps reports (the five documented capability families: devices, representors, libraries, library capabilities, loggers), version availability and execution environment, the tool's narrow error surface, its observability role inside other skills' workflows, and its read-only safety posture.
• the tasks companion — step-by-step workflows for the in-scope task verbs: configure (route to install), build (route to install), modify (refuse), run (the documented invocations), test (capability snapshot as install smoke-test), debug (what to do when the tool reports nothing or fails), plus a Deferred task verbs block routing out-of-scope questions.

The skill assumes a host where DOCA is already installed (or the public NGC DOCA container is running) and the operator has whatever permissions the public guide requires for doca_caps to enumerate devices on their platform.

What this skill deliberately does not ship

This skill is agent guidance, not a samples or scripts bundle. To keep the boundary clean, it deliberately does not contain — and pull requests should not add:

• Pre-baked example output. Output is install- and hardware-specific. A captured example pinned to one platform and one DOCA version misleads operators on a different platform / version.
• Wrappers, parsers, or scripts in any language that consume doca_caps output. The output format is documented; if a user wants to script against it, the right answer is "read the live guide, write the parser against your installed version".
• A samples/ or reference/ subtree. This is a thin loader for a documented CLI; substantive material lives on the public page and in --help.

Loading order

1. Read this skill first to confirm the user's question is in scope (the user actually wants to invoke doca_caps, not learn about DOCA in general).
2. For what doca_caps reports, version availability, error surface, and safety posture, see the capabilities companion.
3. For the documented invocations and the capability-snapshot workflow — configure, build, modify, run, test, debug — see the tasks companion.

Related skills

• doca-public-knowledge-map/SKILL.md — routing to the public Capabilities Print Tool guide and the rest of the public DOCA documentation set.
• doca-setup/SKILL.md — env preparation, install verification (doca_caps is the canonical first step there), and the I have no install yet path with the public NGC DOCA container.
• doca-programming-guide/SKILL.md — cross-library programming patterns, including the ## debug procedure where the saved doca_caps snapshot is consumed.
• The matching libs/<library> skill — for fine-grained, library-specific capability questions that go beyond what doca_caps exposes.