New advertisers: 50% off your first month with code FIRSTMONTHSee slots

BIOS/UEFI firmware workflows that work from Linux, including vendor updates, hidden options, and SPI flash writes.

version
1.2.0
GitHub stars
60
View on GitHub

What it does

  • Adds 7 skills: bios-firmware-fetch, bios-capsule-install, bios-setup-variables, bios-flash-protection-audit, bios-external-programmer, ec-firmware-analysis, and bios-update-diff
  • Covers fetching firmware from a vendor's update service, installing UEFI capsules through fwupd, and editing hidden setup options via efivarfs
  • Audits Intel PCH SPI flash protection and Boot Guard read-only, with a verified full flash backup via flashrom before any write
  • Designed for owners of older laptops whose vendors no longer list their BIOS downloads or publish to the LVFS

BIOS/UEFI firmware workflows - fetch vendor firmware from the vendor's own update service, install UEFI capsules from Linux via fwupd, change hidden setup options, audit and back up the SPI flash, write it with an external programmer, and analyse EC firmware

Add marketplace

/plugin marketplace add laurigates/claude-plugins

Run it inside Claude Code once, then install the plugin below.

Install

/plugin install bios-plugin@laurigates-claude-plugins

Run it inside Claude Code after adding the marketplace.

Files

Discovered from source

BIOS Capsule Install (Linux, fwupd)

fwupd can apply any UEFI capsule the firmware advertises through its ESRT (EFI System Resource Table), not only packages from the LVFS. A vendor that ships BIOS updates only as a Windows installer usually wraps a capsule image inside it; packaged into a fwupd cabinet, it installs from Linux.

Prior art: derjohn's gist for the Huawei MateBook X Pro 2018/2019, which this skill generalises.

Verified once, end to end: a Huawei MateBook X Pro 2020 went from BIOS 1.07 to 1.26 through this route on 2026-11-16 (fwupd 1.9.32, Secure Boot off, systemd-boot). For any other model, treat the flash as unverified until a result is recorded in REFERENCE.md; the firmware there may encode versions differently or behave differently on reboot.

When to Use This Skill

Use this skill when...Use something else when...
You have a vendor capsule image and want to install it from LinuxThe vendor is on the LVFS: fwupdmgr update
Checking whether a machine can take a capsule update at allFinding the firmware file first: bios-plugin:bios-firmware-fetch

Step 1: Check the machine

bash "${CLAUDE_SKILL_DIR}/scripts/capsule-preflight.sh" --min-battery 30

It reads, and changes nothing: DMI model and BIOS version, UEFI and Secure Boot state, the ESRT system-firmware entry (class GUID, current and lowest supported version), whether fwupd lists System Firmware as Updatable and with which Problems, whether the packager and gcab exist, the OnlyTrusted setting, charger and battery, ESP free space, the boot order, and whether the removable-media fallback loader \EFI\BOOT\BOOTX64.EFI exists. Some reads need root; it tries sudo -n and reports what it could not read.

ResultMeaning
no_esrtThe firmware offers no capsule interface; this route is closed
not_updatablefwupd will not update the device; read its Problems
FWUPD_PROBLEMS=Device requires AC power…Only the charger is missing; plug it in before installing
secure_boot_onfwupd's EFI helper must be the signed build
no_fallback_loaderDo not flash: if the update wipes the boot entries, nothing boots the OS. Install a fallback loader first

Step 2: Work out the target version number

fwupd compares the cabinet's release version with the ESRT fw_version integer, so the cab should carry the integer the firmware will report after the update. Read the current one from the preflight (ESRT_FW_VERSION, ESRT_VERSION_HEX).

On the Huawei Insyde firmware this was verified on, BIOS x.yy is stored with the decimal digits written as hex digits: 1.07 reads 65543 (0x00010007) and 1.26 reads 65574 (0x00010026). Compute the target the same way:

printf '%d\n' $(( (0x1 << 16) | 0x26 ))   # BIOS 1.26 -> 65574

That encoding is an observation on one vendor's firmware, not a standard. Before relying on it, check that the preflight's ESRT_VERSION_AS_HEX_DIGITS equals BIOS_VERSION for the current version. A single sample cannot tell the encodings apart when every digit is below ten (1.07 fits both 0x0007 and decimal 7), so a version with an 8 or 9 in the minor, or a second sample, is what confirms it.

A wrong target does not stop the flash: the firmware applies its own image and reports its own version. It does make fwupd's post-reboot comparison fail.

Step 3: Build the cabinet on the target machine

Needs fwupd's /usr/share/fwupd/firmware_packager.py (fwupd 1.9 names it that, not firmware-packager) and gcab.

bash "${CLAUDE_SKILL_DIR}/scripts/build-capsule-cab.sh" \
  --bin UEFI_FW.bin --sha256 <image sha256> \
  --guid <ESRT_FW_CLASS> --version <target integer> \
  --name "<Model> BIOS" --vendor <Vendor> --out firmware.cab
sudo fwupdtool get-details firmware.cab

get-details must show the cab attached to the System Firmware device with New version equal to the target. If it lists no matching device, the GUID is wrong; stop.

Step 4: Install, by the person at the machine

Hand over scripts/install-capsule.sh for the user to run in their own terminal. It asks for confirmation and the sudo password, so it does not run from an agent session:

./install-capsule.sh --cab firmware.cab --sha256 <cab sha256> --model <DMI product_name> \
  --guid <ESRT_FW_CLASS> --target-version <target integer> --min-battery 30

What it does, in order:

  1. Refuses unless the DMI model matches, the charger is connected, the battery is at or above the minimum, the cab checksum matches, and the current ESRT version is below the target.
  2. Refuses unless \EFI\BOOT\BOOTX64.EFI exists on the ESP, and saves efibootmgr -v to ~/efibootmgr-before-update-<timestamp>.txt.
  3. Asks the user to type flash.
  4. Turns fwupd's OnlyTrusted off, because a locally built cab is not signed by the LVFS, then asserts the file holds exactly one OnlyTrusted=false and one [fwupd] section.
  5. Runs fwupdmgr install --no-reboot-check, restores the config file from a backup on exit, and tells the user to reboot.

fwupd ≥ 1.9 reads /etc/fwupd/fwupd.conf; older releases read daemon.conf, which the script falls back to. The file is usually mode 0640 root, so every read goes through sudo. A plain grep fails silently there and sends a naive script into its append branch, which writes a second [fwupd] section.

Before handing it over, confirm with AskUserQuestion that the user accepts the risk: a firmware update cannot be rolled back, and a failed flash can make the machine unbootable. Remind them to keep the charger connected through the reboot.

Step 5: Verify after the reboot

cat /sys/class/dmi/id/bios_version /sys/class/dmi/id/bios_date
bash "${CLAUDE_SKILL_DIR}/scripts/capsule-preflight.sh"
sudo efibootmgr -v

Judge the result from the firmware, not from fwupd. Success is bios_version showing the new version, and the ESRT entry reporting fw_version and last_attempt_version at the new value with last_attempt_status 0.

fwupd's history can say "Failed" after a successful flash. On the verified machine it reported boot entry missing: no 'Linux Firmware Updater' entry found, because the firmware update had wiped the NVRAM boot entries, including fwupd's own. fwupdmgr clear-results <device-id> then failed with failed to clear_result using uefi_capsule: unspecified error, so the stale "Failed" stays in the history. It is not evidence that the flash failed.

Check the boot entries. Compare efibootmgr -v with the file saved before flashing. On the verified machine BootOrder came back as only the generic "EFI Hard Drive" entry: the distribution's entry and fwupd's were gone, and the machine booted only through the fallback \EFI\BOOT\BOOTX64.EFI. Recreate the OS entry from the saved record, with the disk and partition of the ESP and the loader path the old entry pointed at:

sudo efibootmgr -c -d /dev/nvme0n1 -p 1 -L "<distribution name>" -l '\EFI\systemd\systemd-bootx64.efi'

Record the outcome in REFERENCE.md.

Readme

BIOS Plugin

Workflows for BIOS/UEFI firmware on laptops and desktops: getting the vendor's firmware when its support site no longer lists it, installing it from Linux when the vendor does not publish to the LVFS, changing hidden setup options, auditing and backing up the SPI flash, writing it with an external programmer, and analysing the embedded controller firmware.

Vendors stop listing BIOS downloads for older models long before they stop serving them: the update service behind the vendor's own Windows tool often still answers. These skills query that service directly, tie the file to a vendor-hosted manifest by hash, and package the capsule for fwupd, so neither the vendor's website nor its proprietary app is needed.

Related skills elsewhere:

  • tools-plugin:binary-analysis identifies unknown files and lists PE sections.
  • kernel-plugin covers reporting a kernel problem upstream once firmware is ruled out.

Skills

SkillDescription
bios-firmware-fetchFind and download a vendor BIOS/UEFI update from the vendor's own update service, verify it against the vendor-hosted manifest, and extract the capsule image without running anything
bios-capsule-installInstall a vendor UEFI capsule from Linux through fwupd: ESRT and device checks, building the cabinet, relaxing OnlyTrusted for one install, pre-flight checks, and post-reboot verification
bios-setup-variablesRead or change hidden UEFI setup options from Linux through efivarfs, with offsets from the setup form (IFR), backups and a no-op write test
bios-flash-protection-auditRead-only audit of Intel PCH SPI flash protection and Boot Guard, plus a verified full flash backup with flashrom
bios-external-programmerRead or write the SPI flash in-circuit with flashrom and an ESP32-S3 serprog board (or Pico/CH341A): firmware build, wiring, safety, verify procedure
ec-firmware-analysisLocate, verify and statically reverse-engineer the embedded controller firmware; check whether a patched Microchip MEC image would be accepted
bios-update-diffWork out what a BIOS update changed (microcode, EC, ACPI tables, ME) from boot logs and the new image when the old image is gone

The skills grew out of a 2026-11 investigation on a Huawei MateBook X Pro 2020 whose support page had lost its BIOS downloads; the worked examples come from it.

Installation

claude plugin install bios-plugin@laurigates-claude-plugins

License

MIT

Details

Marketplace
laurigates/claude-plugins
Source
bios-plugin
Author
Lauri Gates
Category
Development
License
MIT
Keywords
bios, uefi, firmware, capsule, fwupd, esrt, huawei, linux, efivarfs, ifr, spi-flash, flashrom, serprog, embedded-controller, boot-guard

More from laurigates/claude-plugins

All 52

Similar to bios-plugin

More Development Tools