BC-250 Ultimate Setup

An Agent Skill that takes an AMD BC-250 board from a fresh Linux install to a stable, tuned system — and explains why every step exists.

The BC-250 (AMD "Cyan Skillfish", a cut-down PS5 APU) is cheap, has 16 GB of unified GDDR6, and is famously fiddly. It ships without a GPU governor, without CPU power states, and with an IOMMU that crashes it if left enabled. This skill automates the community's fixes and cites its sources.

What it does

Stage	Result
detect.sh	read-only report: distro, bootloader, kernel, real GPU card index, VRAM split, C/P-states, swap, governor — plus what to do next
stage1-core.sh	monitoring tools, nct6683 board sensors, and cyan-skillfish-governor-smu (unpins the GPU from 1500 MHz)
stage2-boot.sh	ACPI override (CPU C-states + 800–3200 MHz P-states), ttm.pages_limit VRAM cap, ZRAM → zswap + swapfile
verify.sh	asserts every change actually took effect; exits non-zero on failure

Typical outcome on stock cooling:

GPU idle   1500 MHz pinned  →  1000 MHz @ 799 mV, ~40 W
GPU load   1500 MHz         →  1850 MHz, 80–86 W, 61–64 °C
CPU        no cpufreq       →  0.93 GHz idle ↔ 3.49 GHz load
swap       ZRAM             →  zswap(lz4) + 16 GB swapfile

Use it as a skill

Copy or symlink the directory into a skills location an agent scans:

git clone https://github.com/<you>/bc250-ultimate-setup
# Command Code
ln -s "$PWD/bc250-ultimate-setup" ~/.commandcode/skills/bc250-ultimate-setup
# other Agent-Skills-compatible tools
ln -s "$PWD/bc250-ultimate-setup" ~/.agents/skills/bc250-ultimate-setup

Then ask your agent something like "set up my BC-250 on CachyOS", or invoke the skill directly.

Or just run the scripts

They work standalone — the skill is the packaging, not a dependency.

bash scripts/detect.sh                       # always first, read-only

sudo bash scripts/stage1-core.sh --dry-run   # preview
sudo bash scripts/stage1-core.sh             # apply (no reboot)

bash scripts/verify.sh

sudo bash scripts/stage2-boot.sh             # preview (default is safe)
sudo bash scripts/stage2-boot.sh --yes       # apply, then reboot
bash scripts/verify.sh

Both stages honour --dry-run, stage 2 is preview-first, and every file it touches is backed up to /root/bc250-backup-<timestamp>/ with printed rollback steps.

Tested on

CachyOS / Arch · kernel 7.2.4 · limine · mkinitcpio · btrfs

That path is validated end to end. Fedora (dracut + GRUB / rpm-ostree) and Debian (initramfs-tools + GRUB) paths follow the documented community method but are untested — stage2-boot.sh says so explicitly when it takes one. See references/distro-notes.md.

Requirements

• An AMD BC-250 board, Linux, root, and one reboot
• Mesa ≥ 25.1, and a kernel that is not on the known-bad list
• A fallback boot entry, because stage 2 edits the bootloader

What it deliberately does not do

• No BIOS flashing and no VRAM-split change from BIOS menus
• No 40 CU / 8-core unlock, no CPU overclock (documented, not automated)
• No SmokeLess_UMAF, ever

Layout

SKILL.md                     agent-facing runbook
scripts/  lib.sh · detect.sh · stage1-core.sh · stage2-boot.sh · verify.sh
references/  kernel-matrix · bios-and-vram · governor-tuning ·
             cooling-and-power · troubleshooting · distro-notes · credits
assets/   governor-smu-config.toml   (annotated starting config)

Credits and license

Everything here builds on the work of the BC-250 community — see references/credits.md and please contribute upstream to elektricM/amd-bc250-docs.

Documentation and references are CC BY-SA 4.0 (adapted from the community documentation, which is itself CC BY-SA 4.0); the shell scripts are MIT. See LICENSE.

Because skills are instructions plus executable code, review the scripts before running them — and read stage2-boot.sh --dry-run output before letting it touch your bootloader.