| license | Apache-2.0 |
| name | doca-hardware-safety |
| description | Use this skill whenever the agent is about to recommend or apply a change that touches DPU / NIC hardware state on a live system — mlxconfig firmware-parameter write, NIC firmware burn, BFB reflash, NIC ↔ DPU mode flip, SR-IOV or device-emulation slot enable, kernel boot-parameter change (IOMMU, hugepages, VFIO), PCIe rebind / rescan / link-state flip, or BlueField cold reboot. Wraps the change in pre-flight inventory, OOB reachability, a maintenance window, the mlxconfig cold-power-cycle rule, replica rehearsal, and rollback. Trigger even when the user does not say "hardware safety" — implicit phrasings: "flip BlueField mode over SSH", "enable SR-IOV and reboot", "burned firmware but mlxconfig shows old value", "reflashed BFB and lost representors", "reflash during business hours", "vendor says this is one-way". Refuse for general DOCA orientation (doca-public-knowledge-map), install or env debug (doca-setup), and program-side debug (doca-debug, doca-programming-guide) — those belong to other skills.
|
| metadata | {"kind":"library"} |
| 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 with a BlueField DPU or ConnectX NIC, plus out-of-band console reachability (BMC, RShim, or operator-managed console) for any link-breaking change.
|
DOCA hardware safety
Where to start: This skill is the bundle's single source of truth
for the discipline that wraps every change touching DPU / NIC hardware
state on a live system. Open
TASKS.md when the operator is about to apply a
hardware-touching change and needs the change-application discipline
(pre-flight inventory → out-of-band path → window → apply → verify
→ rollback). Open CAPABILITIES.md when the
question is what does hardware-safety even cover (the class of
changes in scope, the failure modes the policy prevents, the
observability surface that gates a change, and the meta-policy that
every per-artifact ## Safety policy overlays).
Every per-artifact skill (services, libraries, tools) in the bundle
that recommends a hardware-touching action overlays this meta-policy
with artifact-specific safety. The per-artifact ## Safety policy
anchors do NOT redefine the cross-cutting discipline — they layer the
artifact's own concerns on top of it. This skill is the layer they all
build on.
Example questions this skill answers well
The CLASSES of hardware-safety questions this skill is built to
answer, each with one worked example. The agent should treat the
class as load-bearing — the worked example is a single instance.
- "I'm about to apply a hardware-touching change. What do I have to
capture before I touch anything?" — worked example: "the
per-artifact skill told me to flip a firmware-level emulation slot;
what do I capture first?". Answered by the pre-flight inventory
in
TASKS.md ## configure plus the
inventory taxonomy in
CAPABILITIES.md ## Capabilities and modes.
- "This change might drop the link I'm using to manage the
BlueField. Is that safe?" — worked example: "I'm about to flip
the BlueField between NIC and DPU mode over the same management
link". Answered by the out-of-band access rule in
CAPABILITIES.md ## Safety policy
plus the OOB-precondition gate in
TASKS.md ## configure.
- "The per-artifact skill said to write an
mlxconfig parameter,
then reboot. Is that the right sequence?" — worked example:
"the storage-emulation skill told me to enable a firmware slot
via mlxconfig and then warm-reboot to apply it". Answered by
the mlxconfig-class rule in
plus the apply-with-cold-power-cycle workflow in
.
