DOCA Structured Tools Contract
A governed fallback contract for consolidating DOCA environment, device, capability, validation, and host-DPU state data.
The skill mandates detection before use, structured-first behavior, read-only probes, explicit path reporting, and contains no malware, credential theft, or covert exfiltration indicators. However, it involves hardware/system-state collection, sudo flint, and potentially sensitive topology output without explicit user confirmation, sensitive-output handling, rollback guidance, or strong dependency-isolation boundaries, so points are deducted.
The four-step loop, JSON schemas, manual fallback chains, and gap reporting are reasonably clear. However, the structured executables are explicitly deferred, several manual commands assume specific privileges/platform tools, and the benchmark describes an lspci fallback that is absent from the corresponding schema, creating an internal inconsistency. Static evidence does not justify a higher score.
Trigger shapes, intended scenarios, and out-of-scope routing are well described across environment, version, device, capability, and validation requests. The skill nevertheless depends on other DOCA skills, a live DOCA installation, or future helper tools; Chinese-language behavior and variation across distributions or privilege environments are not established, so it is not full marks.
The document has clear layering around a behavior contract, schemas, dependencies, limitations, evaluation, and a roadmap. Deductions apply because the SKILL.md license differs from the skill-card's dual-license statement, author metadata, explicit version/changelog, named maintenance responsibility, and a stable update path are incomplete; the benchmark also records missing recommended Instructions and Examples sections.
It provides direct routing value for one-shot DOCA state queries and manual fallbacks, with usable field contracts and reporting requirements. However, the structured implementations are not yet shipped, fallback answers require multiple commands and synthesis, version lookup depends on other skills and external documentation, and comparative utility is not sufficiently verified, so the static ceiling applies.
Pinned schemas, command chains, evaluation assertions, and a benchmark summary provide some auditability. The evaluation dataset is unavailable, no committed CI/test suite covering this skill's key paths is shown, and external documentation is not individually bound within the skill, preventing independent reproduction; only limited credit is warranted.
- The structured helper implementations are not shipped, so real use will often fall back to a multi-command workflow; the schemas should not be treated as installed functionality.
- Before running flint, mlxconfig, dmidecode, or similar commands, confirm privilege, host scope, and whether hardware output is sensitive; the skill lacks explicit confirmation and redaction guidance.
- Some benchmark fallback commands do not match the SKILL.md schemas; reconcile them and add reproducible CI/test evidence before publication.
- Unify the SKILL.md, skill-card, and repository license statements, and add author, version, changelog, and maintenance-contact information.
What does this skill do, and when should you use it?
This is a knowledge skill in NVIDIA’s Agent Skills collection for workflows that need a consolidated DOCA answer instead of several unrelated commands. It defines schemas for environment state, capability version lookup, per-device capabilities, pre-commit validation, and host-versus-DPU collection. An agent probes for the relevant structured helper, validates its JSON, and falls back to the documented manual chain when necessary. The skill defines these contracts but does not ship the executable helpers; their implementations are deferred to a later PR.
It selects a schema based on the question and instructs the agent to run the matching detection probe. Depending on the schema, the workflow reads version files and package metadata, enumerates PCIe functions, checks DOCA capabilities, gathers driver and hugepage state, invokes safe validation surfaces, or collects host and DPU state for comparison. Results are constrained to the documented fields, combined in the prescribed order, and reported with the exact structured or manual path taken. Commands that require privilege, such as firmware queries, must use an already approved privileged channel and must not trigger implicit elevation.
- A DOCA engineer wants one consolidated view of installed versions, visible devices, libraries, drivers, and hugepages.
- A BlueField operator needs PF, VF, and SF inventory with PCIe addresses, representor relationships, and device state.
- A developer needs to determine when a DOCA capability became available and compare that with the installed package version.
- An engineer wants a safe validation result before committing or creating a DOCA specification.
- A troubleshooter needs independent host and DPU snapshots to diagnose version, firmware, kernel, module, or device mismatches.
What are this skill's strengths and limitations?
- Defines explicit JSON contracts for environment, version, device capability, validation, and cross-side state workflows.
- Requires detection, schema validation, path reporting, and deliberate handling of operational failures.
- Covers important DOCA and BlueField details including PCIe functions, PF/VF/SF types, firmware, and privilege boundaries.
- The skill states that the executable helpers are deferred and are not provided by this contract.
- Validation requires a live DOCA installation at /opt/mellanox/doca, while some manual probes require approved privileged access.
- It is a routing and contract layer, not a general DOCA orientation guide, library API tutorial, or from-scratch installation guide.
How do you install this skill?
Install the individual skill through the repository’s documented skills CLI flow:
npx skills add nvidia/skills --skill doca-structured-tools-contract --yes
The README does not specify the exact local destination; the CLI prompts for the installation target.
How do you use this skill?
After installation, ask a relevant question such as “Is there one command that tells me everything about my DOCA install?” or “Diff host vs DPU state.” The agent should run the selected schema’s probe first, use valid structured JSON when available, and otherwise report the actual probe failure before executing that schema’s manual chain.