Index of every page on this site: llms.txt
All skills
nvidia avatar

/doca-structured-tools-contract

@6b75e9e
by NVIDIA Corporationnvidia/skills4.1k stars
547
Run it yourself

Not for writing library code (name that library skill). Use this skill whenever another DOCA skill says "prefer the structured tool per doca-structured-tools-contract", or when the user wants a one-shot answer consolidating what multiple manual commands would produce — DOCA env / version / devices / capabilities / validate / host vs DPU state. Trigger even without the phrases "structured tool" or "env report as JSON" — typical phrasings include "is there one command that tells me everything about my DOCA install", "what version is X capability available since", "every PF/VF/SF visible on this BlueField with PCIe address", or "will this pipe pass validate before commit". Refuse and route elsewhere for general DOCA orientation, library API how-to, or install-from-scratch guidance — those belong to the per-library skill, doca-public-knowledge-map, or doca-setup.

Use this Skill: https://skilld.dev/gh/nvidia/skills/doca-structured-tools-contract

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈227 tokens for metadata: the name and description. ≈3.6k when used: this file. ≈5.9k more on demand in 4 files.

Description uses 11.3% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈904 characters, or 11.3%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

DOCA structured-tools contract

Where to start: Reach for this skill whenever a workflow says “prefer the structured tool per doca-structured-tools-contract”. Read ## The agent behavior contract first, then the matching schema in ## Schemas. If the host has the structured tool, prefer its output; if not, fall back to the manual chain in the same section and always report which path was taken.

Scope boundary. Writing library code is not a structured-tools question: name the library skill and stop. Checking a spec before commit IS in scope: apply the validate-before-commit schema.

Example questions this skill answers well

See references/examples.md.

When to load this skill

Load this skill whenever another skill's workflow says prefer the structured tool, OR the user wants a one-shot answer consolidating multiple manual commands. Concretely:

  • A per-artifact skill's Command appendix references this skill.
  • The user asks "is there one command that tells me X about my DOCA install".
  • The user asks "how do I know X is valid before I commit" for a library with a validate-before-commit call.
  • The agent computed the manual answer and wants to surface the structured-tool one-liner for next time.

Do not load for general DOCA orientation, library API questions, or install-from-scratch guidance — use the matching library skill + doca-public-knowledge-map + doca-setup. Running probes and fallbacks requires shell access to the target host, directly or via user-run commands.

Ground rules for any agent using this skill

  1. Detect first; never assume the tool is present. Each schema names the probe command deciding whether the tool is installed; run it before treating schema output as authoritative.
  2. Prefer structured when present; fall back to manual when not. When the probe succeeds and output validates against the selected schema, the structured JSON is the source of truth. When the probe fails or output is invalid, walk the manual chain and synthesize the equivalent answer.
  3. Report which path you took. Open the answer with “using structured <helper> (path: <path>)” OR “falling back to manual chain (structured <helper> probe failed: <reason>)”, substituting the schema-selected helper and the actual probe failure; never report a different helper than selected.
  4. Schemas are locked here; per-skill overlays are NOT. A per-artifact skill MAY add a Command-appendix row that uses a schema; it MUST NOT redefine it. Schema growth happens here; consuming appendixes inherit it.
  5. Never invent a JSON field not in the schema. Extra fields in pasted JSON are advisory; quote the schema as the boundary.
  6. Schemas describe contracts, not implementations. The helpers are optional and are not part of the DOCA packages; a site may provide its own. So never assume a helper named here is installed — never present one as available or send the user to install it. Probe, report absent in one line, then answer from the manual fallback.
  7. Privilege is never implicit. A fallback command requiring sudo is emitted for the user to run or executed only through an approved privileged channel — never silently elevate because the helper was absent. If none exists, ask the user to run it or report the gap.

The agent behavior contract

A four-step loop run every time a Command appendix references this contract:

  1. Detect. Run the schema's probe command against whatever helper your site provides (for example command -v <site env-report helper> or test -f <site capability-availability table path>). No such helper ships with public DOCA. Probes are read-only and safe; failed probes are expected.
  2. Prefer. If the probe succeeds, invoke the structured tool and parse its JSON per the schema in ## Schemas. It is authoritative only when parsing succeeds and every required field has the documented type. Malformed JSON, missing fields, or type mismatches fail the structured path: report that failure and use step 3. Ignore extra fields as advisory (rule 5). Do NOT run the manual chain "to double check" valid structured output — it replaces the chain.
  3. Fall back. If the probe fails, walk the manual chain in the same schema section, combining outputs in the listed order. If a manual command is unavailable, surface the gap and route to the matching skill (typically doca-setup). If that cannot resolve it, name the missing commands, state the answer cannot be completed, and stop rather than presenting partial data as complete.
  4. Report. Open the answer with one of:
    • “Using structured <tool> (path: <path>).” — probe succeeded and output validated.
    • “Falling back to manual chain (structured <tool> probe failed: <reason>).” — probe failed. Include the probe command and reason; for command -v, failure means not on PATH, not definitively absent. Do not suggest installing it (rule 6).
    • “Falling back to manual chain (<tool> output failed schema validation: <reason>).” — the helper exists but its output is malformed, missing required fields, or invalid types.

The report step proves the agent tried the helper first.

Schemas

Select the schema from the question shape: env/install state uses the env-report schema; capability minimum-version lookup uses the capability-availability table; per-device library capabilities use capability-snapshot; spec validation uses validate-before-commit; host-vs-DPU comparison uses the two collect-state schemas. When a per-skill Command appendix names a schema, use it directly. Each subsection names ONE structured tool, its probe, its top-level JSON shape, and the manual chain walked when the probe fails.

env-report schema

Detection probe: command -v <site env-report helper> (a hypothetical site-provided script that emits this JSON).

Top-level shape (JSON object):

Field Type Notes
version object pkg_config / applications_version / doca_caps / bfb (string|null) / consistent (bool)
devices array of object per visible PCIe function: pcie_address (e.g. 0000:03:00.0), kind (PF|VF|SF), name, representor_of (string|null), state (active|down|unknown), mtu (number)
libraries array of object one per public DOCA library: pkg_config_name, installed (bool), pc_path (string|null)
sample_paths array of object one per library: library, path (on-disk samples root)
drivers object mlx5_core_loaded (bool), mlx5_ib_loaded (bool), kernel_version (string)
hugepages object available_2m (number), available_1g (number), mount_point (string|null)
host_kind string host | bluefield | unknown
bf_mode string | null smartnic | dpu | switch | null (when host_kind != bluefield)

Manual fallback chain (in order; combine outputs to synthesize the same answer):

  1. pkg-config --modversion doca-common → version.pkg_config
  2. cat /opt/mellanox/doca/applications/VERSION → version.applications_version
  3. doca_caps --version → version.doca_caps
  4. doca_caps --list-devs → devices array (PCIe address + kind + representor)
  5. Find doca-common.pc first: if find /opt/mellanox/doca -name doca-common.pc -print -quit is empty, stop, surface the partial-install gap, and route to doca-setup; never expand an empty glob. Otherwise set PCDIR to its directory and run for pc in "$PCDIR"/*.pc; do m="${pc##*/}"; pkg-config --exists "${m%.pc}" && echo "$pc"; done → libraries array. If PCDIR is not a directory or no module resolves, surface the gap and route to doca-setup. PCDIR is commonly /opt/mellanox/doca/lib/<arch>-linux-gnu/pkgconfig on DOCA 3.3+.
  6. ls /opt/mellanox/doca/samples/ → sample_paths array
  7. lsmod | grep -E '^mlx5_(core|ib)' + uname -r → drivers object
  8. cat /proc/meminfo | grep -i Huge → hugepages object
  9. dmidecode -s system-product-name (or cat /proc/device-tree/model on BlueField) → host_kind
  10. mlxconfig -d <pcie> q INTERNAL_CPU_MODEL → bf_mode (when host_kind == bluefield)

capability-availability table schema

Detection probe: test -f <site capability-availability table path> (a hypothetical site-maintained JSON file).

Top-level shape (JSON object):

Field Type Notes
schema_version string semver of THIS contract; bumps on schema changes
generated_at string ISO-8601 generation timestamp
entries array of object one row per (library, capability) pair

Per-entry shape:

Field Type Notes
library string pkg-config module name (doca-flow, doca-rdma, doca-comch, …)
capability string machine-readable cap name; the per-library Command appendix lists which doca_<lib>_cap_* query it maps to
display_name string human-readable label; quoted when reporting
min_doca_version string first DOCA release in which the capability was available (semver)
max_doca_version string | null last release it was available in (null = still available)
source_url string the public docs URL the row was derived from
source_quote string the exact public-docs prose that established the row

Manual fallback chain:

  1. Identify the library + capability via the matching skill's CAPABILITIES.md table.
  2. Fetch its per-library doc page via doca-public-knowledge-map.
  3. Search it for the capability name; extract and quote the “available since” prose verbatim.
  4. Cross-check pkg-config --modversion doca-<library> on the user's host; if it is older than the “available since” line, the capability is not on this install regardless of the docs.

capability-snapshot schema

Detection probe: command -v <site capability-snapshot helper>.

Top-level shape (JSON object):

Field Type Notes
snapshot_at string ISO-8601 timestamp
doca_version string doca_caps --version at snapshot time
host_kind string host | bluefield
devices array of object one per doca_devinfo: pcie_address, library_capabilities (map of library → capability flags)

Manual fallback chain:

  1. doca_caps --list-devs → device enumeration
  2. Per-device detail: doca_caps --pci-addr <bdf> (side-effect free; see doca-caps). Only if a capability it does not print is required, use the library's own ## test workflow from its shipped sample; never write new test code for a snapshot.

validate-before-commit schema

Detection probe: command -v <site validate helper>. A library-specific constructor-time validation surface is not a detection probe and may mutate state. The public Flow header ships no doca_flow_pipe_validate symbol: never invent one, and never use doca_flow_pipe_create to test for the helper.

Top-level shape (JSON object):

Field Type Notes
library string which DOCA library the spec is for
spec_path string on-disk path to the spec being validated
result string pass | fail | skip
checks array of object per-check: name, status (pass | fail | skip), details, remediation (string | null)

Manual fallback chain:

  1. Find the library-specific validate surface in the matching skill's ## test workflow. For some libs this is a dedicated _validate call; constructor-time checks inside a mutating _create are not read-only validators. In particular, doca_flow_pipe_create belongs to doca-flow TASKS.md ## test after its preconditions; never invoke it as a pre-commit probe. If the caller requires read-only validation and the API exposes no dedicated validator, report result: skip, route to the per-library ## test workflow, and stop (skip steps 2 and 3).
  2. Invoke that read-only validator (never a mutating _create) before any commit / create / submit call.
  3. Map outcomes deliberately: DOCA_ERROR_INVALID_VALUE and DOCA_ERROR_NOT_SUPPORTED are result: fail; permission, transport, unavailable-device, and other operational errors are result: skip, with the doca_error_get_descr() text and remediation in a checks entry. Never turn an inability to run validation into a spec failure.

host-state and DPU-state schemas

Select the helper for the side where commands execute: a site-provided host-state helper on the host, a DPU-state helper on BlueField. Both being present does not imply cross-side access; for a diff, collect independently on each side and compare.

Detection probes: command -v <site host-state helper> (host) / command -v <site DPU-state helper> (BlueField).

Top-level shape (JSON object), shared by both:

| side | string | host | dpu | | doca_version | string | doca_caps --version | | firmware_version | string | flint -d <pcie> q output (sudo) | | kernel_version | string | uname -r | | mlx5_modules | array of string | loaded mlx5_* modules | | bf_mode | string | null | smartnic | dpu | switch | null | | devices | array of object | per-PCIe-function: pcie_address, kind (PF | VF | SF), state, mtu, representor_of |

Manual fallback chain (per side):

  1. doca_caps --version → doca_version
  2. uname -r → kernel_version
  3. lsmod | grep mlx5 → mlx5_modules
  4. devlink dev show + lspci | grep Mellanox + ip -j link → enumerate devices and PCIe addresses
  5. For each discovered PCIe target, flint -d <pcie> q via the approved privileged channel → firmware_version
  6. On a discovered BlueField target, mlxconfig -d <pcie> q INTERNAL_CPU_MODEL → bf_mode

The two sides are symmetric so the agent can diff them when diagnosing host ↔ BlueField mismatches.

Relationship to helper executables

The helpers are optional and site-provided (ground rule 6); any helper that implements a schema above emits it unchanged, so no other skill needs a change.

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alerts12d3 checks · Risk SAFE
  • Gen Agent Trust Hub20d

    This skill provides a secure diagnostic framework for NVIDIA DOCA installations. It defines a transparent 'Detect-Prefer-Fallback-Report' workflow that utilizes official vendor tools for read-only environment inspection while incorporating explicit safeguards against silent privilege escalation and command invention.

  • Socket12d

    No alerts

  • Snyk20d

    Risk: LOW · No issues

Signed by skilld at 6b75e9e. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 3 days ago
metadata
{
  "author": "NVIDIA",
  "kind": "knowledge",
  "doca_version": "3.6"
}
Other metadata
compatibility
No DOCA install required to read this skill (it is an overlay loaded against any DOCA artifact skill); its validation steps DO require a live DOCA install at /opt/mellanox/doca.

README badge

README badge for nvidia/skills/doca-structured-tools-contract