Helper - Windows Hardware Diagnostics

1. Skill Positioning

windows-hardware-doctor is a hardware diagnostic and security handling skill for Windows PCs. It allows the agent to handle the following issues using a "evidence gathering, judgment, and modification" approach:

• Hardware inventory and quick health check;
• Abnormal device, yellow exclamation mark, driver problem;
• CPU, memory, graphics card, crashes, freezes, and black screens;
• HDD, SSD, NVMe, SMART, disk events and data risks;
• Disk space analysis, backup planning, and cleanup candidate organization;
• USB, peripherals, interfaces, power supply, and physical connection issues;
• Provide careful physical inspection recommendations after completing software certification.

It is not a "one-click fix tool". Its core value is to help the Agent collect verifiable evidence, determine the level of risk, distinguish between facts and speculation, and wait for the user's explicit approval before any operation that may change the system or data.

2. Agent Capabilities Overview

3. Core Working Methods

The agent should follow the following closed loop:

1. Inquire about symptoms, onset time, frequency of occurrence, recent software and hardware changes, and whether the data is at risk.
2. Establish hardware and event baselines using native read-only methods.
3. Load corresponding diagnostic data according to the problem type, instead of stuffing all information into the context at once.
4. Simultaneously check device status, drivers, resources, storage reliability, and critical system events.
5. Categorize the conclusions as "confirmed, likely, possible, not yet tested".
6. Recommend the smallest, reversible next step; destructive or irreversible operations should be placed last.
7. After obtaining approval and implementing the changes, re-examine and report the differences before and after.

This process can reduce misinterpretation of a single signal. For example:

High CPU utilization only indicates a high current load and does not automatically mean the CPU is damaged;
Event 41 only proves that an abnormal shutdown occurred, but does not prove that the root cause is the power supply;

• SMART displaying Healthy does not rule out disk problems on its own;
• An empty temperature field indicates that Windows has not exposed any sensors, but does not mean that the temperature is normal;
• An older driver date alone cannot prove that the driver needs to be updated.

4. Built-in Tools and Actual Output

4.1 Get-HardwareAudit.ps1

This script generates JSON hardware audit results, with key fields including:

• Meta: Collection time, Windows version, whether it is run as administrator, event time window;
• Verdict: Quick determination;
• Attention: Signals that need to be paid attention to;
• MissingSections: Modules that are missing due to unavailable permissions or interfaces;
• CPU, MemorySummary, MemoryModules, GPU;
• DiskDrives, PhysicalDisks, Volumes;
• ProblemDevices, UnsignedOrIncompleteDrivers;
• Battery, RelevantSystemEvents, Limitations.

By default, it hides the memory module serial number/part number, GPU and disk PnP ID, and disk serial number. -IncludeIdentifiers should only be used when exact device matching is absolutely necessary.

The script may currently return:

• HEALTHY_NO_OBVIOUS_FAULTS: No obvious faults were found in the snapshot;
• ATTENTION: A signal requiring attention has been detected;
• INCOMPLETE: Some data sources are unavailable, so a complete health conclusion cannot be drawn from this information.

The automatic rules for ATTENTION currently cover: PnP anomalies, unhealthy physical disks, volume free space below 10%, and WHEA/disk/partial storage controller events.

4.2 Get-LargeFiles.ps1

This script recursively searches for files only within existing directories explicitly specified by the user, and supports:

• Minimum file size, default 500 MB;
• Return the number of items, default is the first 50, maximum is 1000;
• Output file size, last modified time, and full path;
• List only candidate files, without deleting, moving, or compressing them.

5. Example Input and Output

The following output is a sample result consistent with the current Skill design, used to demonstrate how the Agent should be expressed; the specific data may vary depending on the computer.

Example 1: Random freeze, perform read-only check first

Example Input

My Windows 11 desktop computer has been randomly freezing recently. Please quickly check the CPU, memory, graphics card, disk, and any malfunctioning devices. Do not change any settings yet.

Example Output

[Windows Host Hardware Check] ATTENTION

- Confirmed: There were 3 abnormal shutdown events in the past 7 days; no abnormal PnP devices were found; C drive has 8.4% remaining.
- More likely: Insufficient system disk space may exacerbate the lag, but Event 41 itself cannot prove that it is the root cause of the freeze.
- Possible causes: graphics card driver reset, memory instability, or storage timeout. There is currently insufficient evidence.
- Impact: There is a risk of system instability and update failure; no directly verifiable data corruption has been found so far.
- Take immediate action: save important work first and avoid running multiple stress tests at the same time.
- Next diagnostic: Check the Display, WHEA, disk/stornvme, and BugCheck events for 10 minutes before and after the freeze.
- No write operations performed.

Example 2: Yellow exclamation mark in Device Manager

Example Input

There was a yellow exclamation mark in Device Manager. Help me find the device and fix the driver.

Example Output

An abnormal device has been identified: USB controller, PnP problem code 28, indicating that no available driver is currently installed.

Current evidence:
- Device Status: Error
- Problem code: 28
- Current driver: No valid version found
- Precise Hardware ID: Already collected locally, not publicly disclosed in messages by default.

It is recommended to match the signed driver from the official support page of the OEM/OEM by the accurate model number, Windows version, and hardware ID.
Installing the driver will change the system. Before proceeding, I will show you the source, version, signature, rollback plan, and potential USB interruption risks, and wait for your approval of the specific operation for this device.

Example 3: Drive D is almost full, back up first and then clean up

Example Input

My D drive is almost full. Please help me find large files, create backups, and then clean it up, but please don't delete them directly.

Example Output

The read-only space analysis for D:\ has been completed, and no files have been deleted.

Main candidates:
1. D:\VMs\dev-machine.vhdx — 82.4 GB — Please confirm whether the virtual machine is still in use.
2. D:\Downloads\archive.iso — 6.1 GB — Can be moved to a backup drive after verifying the source.
3. D:\BuildCache\old-cache.bin — 3.7 GB — It is recommended to clean it up using the corresponding application.

Backup Recommendation: First, copy irreplaceable data to a separate, healthy disk, and verify the number of files, total size, representative hashes, and the openability of critical files. Then, I can generate a precise cleanup list, estimated freed space, and recovery methods, which I will then await your approval item by item.

Example 4: Suspecting the SSD is about to fail

Example Input

My computer freezes when reading files, and the SSD occasionally disappears. Could you try running `chkdsk /f` to fix it?

Example Output

It is not recommended to run chkdsk /f first. Disk disappearance and I/O freeze may indicate media or controller failure, and attempting to repair writes will increase the risk.

Suggested order:
1. Stop cleaning, benchmarking, defragmentation, and full disk scan.
2. Read-only confirmation of physical disks, associated volumes, SMART/reliability counters, and storage events.
3. Prioritize copying irreplaceable data to another healthy device and verify the backup.
4. After ensuring data security, perform repairs or vendor diagnostics on the clone/image.

No write operations have been performed so far.

Example 5: Incomplete results due to restricted permissions

Example Input

Why does the hardware audit show INCOMPLETE? Is my computer broken?

Example Output

No. INCOMPLETE indicates that one or more Windows data providers are unavailable in the current session, for example, due to restricted permissions, inaccessible event logs, or storage interfaces that do not expose data.

It does not equate to health or hardware failure. First, check the MissingSections; if necessary, I will explain what data can be supplemented by elevating privileges and rerun the process after obtaining approval. When the sensor or SMART field is empty, it can only be marked as "unavailable".

6. Recommended Use Cases

• Read-only hardware inventory before new computers, used computers, or repairs;
• Windows randomly freezes, restarts, blue screens, black screens, or experiences a sudden drop in performance;
• Device Manager displays an unknown device, a yellow exclamation mark, or Code 10/28/43/45;
• External hard drive, USB, graphics card or other devices are not recognized;
• SSD/HDD slows down, disconnects, or exhibits I/O errors or unusual sounds;
• Insufficient space on the system disk or data disk; you need to locate the problem and then clean it up.
• Risks and rollback assessments before driver updates, rollbacks, and uninstallations;
• Memory capacity recognition anomaly, suspected memory error, or resource pressure;
• A backup, migration, disk replacement, or recovery verification plan needs to be developed;
  Before disassembling or replacing parts, rule out software, cable, port, and driver issues.

7. Tasks that are unsuitable or cannot be completed alone

• You cannot prove that the hardware is 100% healthy based on just one snapshot;
• The native Windows interface typically cannot fully read PSU voltage, fan speed, DIMM temperature, or all GPU/NVMe sensors;
• You cannot determine whether a driver is expired based solely on its date;
• Power supply failure cannot be determined solely based on Kernel-Power Event 41;
• Cannot replace manufacturer's offline diagnostics, boot disk memory testing, oscilloscope or physical repair;
• BIOS/firmware upgrades, driver changes, disk repair, formatting, partitioning, deletion, restarting, or disassembly should not be performed automatically;
• Not responsible for macOS or Linux hardware diagnostics.

8. Security and Privacy Boundaries

The following operations must be performed with explicit approval after demonstrating the specific target, impact, rollback method, and backup status:

• Install, update, rollback, or uninstall drivers;
• Enable/disable the device, modify services or the registry;
• BIOS/firmware upgrade;
• chkdsk /f, chkdsk /r;
• Partitioning, formatting, cloning and overwriting, secure erasure, BitLocker changes;
• Delete cleanup items and overwrite backups;
• Restart, shut down, perform continuous stress testing, or physically disassemble the device.

Drivers should only be sourced from Windows Update, the official website of the system/OEM, or the official website of the device manufacturer. Third-party driver aggregation sites and "automatic driver update" tools are prohibited.

While the default script hides many hardware identifiers, the JSON may still contain computer names, volume labels, device/model names, and event message fragments; large file results will include the full local path. A second layer of data anonymization is required before sending the report to external systems.

9. Frequently Asked Questions

Q1: Does HEALTHY_NO_OBVIOUS_FAULTS indicate that the hardware is completely normal?

No. It only indicates that no obvious faults were found in the available data. Intermittent problems, unexposed sensors, faults under load, and physical issues may still exist.

Q2: Why are the temperature, wear level, or SMART fields empty?

A common cause is that the Windows driver or hardware is not exposing the data to the native interface. The correct conclusion is "data unavailable," not "normal."

Q3: Is administrator privileges required?

The basic inventory may not be necessary, but some event logs, storage reliability counters, and system interfaces require higher privileges. Skills require you to explain the purpose and impact of the privilege elevation before obtaining approval.

Q4: Can all drivers be updated automatically?

No. First, identify the exact device and the problematic code, record the current driver, then match the specific package from official sources, and establish a rollback path for each individual device.

Q5: Does Code 43 always indicate hardware failure?

Not necessarily. It indicates that the device has reported a fault, and further checks are needed on the power supply, interface, firmware, drivers, cold boot, and test results from another port or another computer.

Q6: The disk SMART shows Healthy, why is it still necessary to check?

SMART status may not include all vendor attributes or expose reliability counters. It also needs to be correlated with disk failures, freezes, I/O errors, controller resets, NTFS events, and vendor diagnostics.

Q7: Will large file scans automatically delete files?

No. The script only lists the files. The agent should categorize the candidates, estimate the space required, describe the recovery method, and seek approval again for the accurate list.

Q8: Why are there no outputs when scanning large files?

The current script may return empty output instead of [] if no file meets the threshold. This usually indicates that no matching file was found, and may also require checking the path, threshold, and access permissions.

Q9: Can I directly run robocopy /MIR to perform a backup?

It cannot be run directly. /MIR may synchronously delete files on the target side. You must first demonstrate the source, target, deletion semantics, and drill results, and obtain explicit approval.

Q10: Should we continue diagnostics if the hardware makes abnormal noises or emits smoke?

Routine testing should not continue. Immediately prioritize personal and data safety, cease use and safely disconnect power; do not turn on the power source, high-voltage areas of the monitor, or bulging batteries.

10. Actual effect and review results of the current version

Verified Performance

Both PowerShell scripts passed syntax parsing with zero parsing errors.

• The hardware audit script can return INCOMPLETE when permissions are insufficient and provide MissingSections to avoid misjudging data collection failure as healthy.
• By default, IdentifiersIncluded=false, the primary serial number and PnP ID are hidden.
• Large file scripts strictly require explicit paths and only perform reading and sorting, without including deletion logic.
• Three built-in test cases cover three core paths: read-only full machine check, driver repair pre-approval, and backup post-cleanup.

In controlled testing, the current sandbox session could not access multiple Windows hardware data providers, and the script returned INCOMPLETE instead of a fictitious hardware conclusion. This verifies its "explicit missing data" design, but also illustrates that actual diagnostic effectiveness depends on a normal Windows session and appropriate permissions.

Design Advantages

1. **Clear security boundaries: Read-only priority, with clear approval thresholds for drivers, disks, restarts, and disassembly.
2. Strong awareness of evidence: Multiple signals are correlated, and repeated reminders are given not to mistake correlation for the root cause.
3. Proper Storage Handling: When a disk is suspected of being faulty, prioritize data protection and explicitly oppose running repair writes first.
4. Reasonable progressive loading: The main process is concise, and the details of components, drivers, and storage are separated into independent reference files.
5. Good privacy defaults: Sensitive hardware identifiers are hidden by default and only enabled as needed for exact matching.
6. Output suitable for automated processing: Audit results are presented in structured JSON format, which facilitates agent aggregation, comparison, and archiving.

11. Summary

The strength of windows-hardware-doctor is not "automatic computer repair," but rather transforming Windows hardware diagnostics into a secure, interpretable, and verifiable agent workflow. It is particularly suitable for scenarios involving system crashes, driver malfunctions, storage risks, and low disk space, effectively preventing common high-risk errors such as blindly updating drivers, running chkdsk /f on a suspected faulty disk, directly deleting large files, or relying solely on Event 41 to diagnose power supply failures.