Windows Storage Health Skill

A reusable, privacy-safe Windows storage health skill for AI agents and automation.

• The reusable windows-storage-health Codex skill in SKILL.md.
• A PowerShell collector that checks every physical disk by default.
• Correct protocol separation: NVMe SMART/Health log pages, ATA/SATA SMART pass-through, and protocol-aware fallbacks.
• Automatic smartctl -x -j fallback when native SATA/ATA access is blocked.
• A prediction-only fallback when neither raw path is available.
• Structured output suitable for agent indexing and JSON ingestion.
• Guidance for interpreting vendor-specific SMART attributes without overclaiming.

windows storage disk-health storage-health smart sata ata nvme smartmontools powershell skill codex-skill ai-agents

Run PowerShell as Administrator when raw SATA/ATA SMART is required. Native NVMe health queries use a separate protocol path:

powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\Get-DiskHealth.ps1 -AsJson

The command checks all disks. To inspect selected disks:

powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\Get-DiskHealth.ps1 -DiskNumber 0,1 -AsJson

If smartctl.exe is installed, the wrapper automatically tries it after native ATA pass-through fails. Install smartmontools with:

winget install --id smartmontools.smartmontools --exact

Use -SmartctlPath when smartctl is installed in a nonstandard location. Use -RequireRawSataSmart when a report must fail instead of falling back to prediction-only evidence; the script exits with code 2 if any SATA disk lacks raw SMART.

Serial numbers are redacted by default. Do not use -IncludeSerial for public logs or issue reports.

The collector reports the access path separately from the assessment:

• NoFailureEvidence: SMART data was read and no current failure evidence was found.
• Attention: a critical warning, media error, SMART threshold failure, or failure prediction was found.
• WindowsHealthySmartDetailUnavailable: Windows is healthy/online, but only the prediction fallback was available.
• WindowsHealthySmartUnavailable: Windows is healthy/online, but SMART could not be accessed.

Raw SATA SMART through Windows ATA pass-through requires an elevated Administrator token. Without it, Windows may return Win32 error 5 (Access Denied); the collector reports that limitation explicitly and does not call the disk healthy merely because prediction returned false.

No SMART report is a guarantee against sudden failure. Keep backups and correlate SMART with event logs, filesystem checks, temperature, power-loss history, and symptoms.

NVMe and SATA use different protocols. SATA does not use the NVMe SMART log-page request. The collector first uses read-only ATA SMART READ DATA and SMART READ THRESHOLDS commands through IOCTL_ATA_PASS_THROUGH, uses the zero-based ATA task-file register layout, rejects empty attribute payloads, parses the standard 12-byte attribute records, joins thresholds by ID, and checks the ATA status and checksum. When that path is unavailable, the wrapper parses smartmontools JSON output. It does not enable SMART, start tests, clear logs, or write media.

USB bridges, RAID controllers, vendor storage filters, and permission policy may block or rewrite ATA pass-through. For those paths, use smartmontools' --scan-open result and the appropriate bridge or RAID device type.

See references/sata-smart-windows.md for the protocol details and source links.

See examples/sample-report.json. It is synthetic and contains no real serial numbers.

MIT. See LICENSE.