/doca-structured-tools-contract

license: Apache-2.0 AND CC-BY-4.0
name: doca-structured-tools-contract
description: >
  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 that consolidates info multiple
  manual commands would produce — DOCA env / version / devices /
  capabilities / validate / host vs DPU state. Trigger even when
  the user does not explicitly mention "structured tool" or
  "doca-env --json" — typical implicit 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", "will this pipe
  pass validate before commit", "diff host vs DPU state", or "why
  does the agent give a one-line answer on host A and five commands
  on host B". Refuse and route elsewhere for general DOCA
  orientation, specific library API how-to, or install-from-scratch
  guidance — those belong to the per-library skill,
  doca-public-knowledge-map, or doca-setup.
metadata:
  kind: knowledge
compatibility: >
  No DOCA install required to read this skill (it is an overlay
  loaded against any DOCA artifact skill); the validation steps
  within DO require a live DOCA install at /opt/mellanox/doca.

DOCA structured-tools contract

**Where to start:** Reach for this skill whenever a workflow in another skill says *"prefer the structured tool per `doca-structured-tools-contract`"*. Read [`## The agent behavior contract`](#the-agent-behavior-contract) first; then drill into the matching schema in [`## Schemas`](#schemas). If the host has the structured tool, prefer its output. If it does not, fall back to the manual command chain in the same schema section. **Always report which path was taken** so the user can fix the gap (or so a future bundle update can detect that the structured path was never tried).

Example questions this skill answers well

See [`references/examples.md`](references/examples.md) for the five worked routing examples. Keep this loader focused on detection, fallback behavior, and the authoritative schemas below.

When to load this skill

Load this skill whenever another skill's workflow tells the agent to *prefer the structured tool*, OR whenever the user's question implies they want a single one-shot answer that consolidates information multiple manual commands would otherwise produce.

Concretely:

• A library / service / tool skill's Command appendix references

this skill in its first column.

• The user asks "is there one command that tells me X about my DOCA

install" (env / devices / version / capabilities / hardware topology).

• The user asks "how do I know X is valid before I commit" for

any DOCA library that has a validate-before-commit call.

• The agent has computed the manual fallback answer and wants to

*also* surface the equivalent structured-tool one-liner so the user can adopt it next time.

Do **not** load this skill for general DOCA orientation, for specific library API questions, or for install-from-scratch guidance. For those, use the matching library skill + [`doca-public-knowledge-map`](../doca-public-knowledge-map/SKILL.md)

• [`doca-setup`](../doca-setup/SKILL.md).

Running probes and fallbacks requires shell access to the target host, either directly by the agent or through commands the user runs.

Ground rules for any agent using this skill

1. **Detect first; never assume the tool is present.** Each schema below names the *probe command* that decides whether the structured tool is installed on this host. Run the probe before reading the schema's output as authoritative. 2. **Prefer structured when present; fall back to manual when not.** When the probe succeeds and the output validates against the selected schema, the structured JSON is the source of truth. When the probe fails or the output is invalid, walk the manual command chain in the same schema section and synthesize the equivalent answer. 3. **Report which path you took.** Always tell the user at the start of the answer: *"using structured `<helper>` (path: `<path>`)"* OR *"falling back to manual chain (structured `<helper>` probe failed: `<reason>`)"*, substituting the helper selected by the schema and the actual probe failure. Never report a helper different from the one the schema selected. 4. **Schemas are locked here; per-skill overlays are NOT.** A library / service / tool skill MAY add a per-skill row to its own Command appendix that *uses* a schema; it MUST NOT redefine the schema. If a schema needs to grow, the change happens here first and every Command appendix that consumes it inherits the change automatically. 5. **Never invent a JSON field that is not in the schema.** The structured tool's output is exactly the shape this contract says it is. If the user pastes JSON that contains a field not in the schema, treat the extra field as advisory and quote the official schema as the boundary. 6. **Schemas describe contracts, not implementations.** The executables that satisfy these contracts are deferred to a subsequent PR on the maintainer roadmap. This skill exists so every other skill in the bundle can be *infra-aware* before the executables ship. 7. **Privilege is never implicit.** A manual fallback command that requires `sudo` is emitted for the user to run or executed only through an already approved privileged channel. Never silently elevate merely because the structured helper was absent. Do not assume such a channel exists; if it does not, ask the user to run the command or report the privileged-data gap.

The agent behavior contract

The contract is a four-step loop the agent runs every time a skill's Command appendix references this contract:

1. **Detect.** Run the probe command listed in the schema section for the relevant tool. Examples: `co