/doca-structured-tools-contract

license: Apache-2.0 AND CC-BY-4.0
name: doca-structured-tools-contract
description: >
  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 "doca-env --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.
metadata:
  author: NVIDIA
  kind: knowledge
  doca_version: "3.5"
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.

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`](#the-agent-behavior-contract) first, then the matching schema in [`## Schemas`](#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`](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. Examples: `command -v doca-env`, `test -f <site version-matrix.json path>`, `command -v doca-capability-snapshot`. Probes are read-only and safe. The helpers are optional, so failed probes are expected. 2. **Prefer.** If the probe succeeds, invoke the structured tool and parse its JSON per the schema in [`## Schemas`](#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