doca-structured-tools-contract

What it does

Describes a contract for using a structured tool to consolidate DOCA environment, devices, capabilities, validation, and host vs DPU state information. It enables an agent to prefer the structured tool when available and valid, or fall back to a defined manual command chain, always reporting which path was taken.

How it works

• The agent first detects if a structured tool is installed by running the probe command named in the schema (e.g., command -v doca-env).
• If the probe succeeds and the structured tool's JSON validates against the schema, the agent uses the structured JSON as the authoritative output.
• If the probe fails or the JSON is invalid, the agent executes the manual fallback chain in the order listed (e.g., pkg-config --modversion doca-common; cat /opt/mellanox/doca/applications/VERSION; doca_caps --version; etc.), combining outputs to synthesize the answer.
• The agent must report which path was taken at the start of the answer, signaling either the structured path or the manual fallback path with reason.
• The agent should surface gaps if certain commands are unavailable and route to doca-setup when needed.

When to use it

Load this skill when another skill requests the structured tool path or a single-shot answer consolidating information from multiple commands (env, version, devices, capabilities, validate, host vs DPU state). It is triggered by phrases indicating a desire for an all-in-one view or when a workflow says "prefer the structured tool".

What it can touch

This contract references shell probes and a set of manual commands to gather data. It specifies the exact commands to run and the JSON schema outputs, but does not itself modify system state beyond detection and data collection. If the structured tool exists, its JSON is used; otherwise the manual command chain is executed.

Caveats

• The manual fallback requires running on a host with the listed commands; if a command is unavailable, a gap is surfaced and routing to doca-setup may occur.
• The structured output must strictly conform to the defined JSON schema; extra fields are advisory and not exposed as contract output.
• Probes exist to detect presence; failed probes do not imply absence of the tool, only that the structured path is not authoritative in that instance.