CachyOS Skill

Manage a running CachyOS install. CachyOS is a performance-first rolling Arch derivative with its own kernels, ISA-optimized repos, settings, hardware profiles, and a separate handheld ISO.

This skill covers end-user and admin work on an installed system. It is not a substitute for the CachyOS wiki. Deep PKGBUILD authoring lives only in packaging.md.

When This Skill MUST Be Used

ALWAYS invoke this skill before ANY of these on a CachyOS machine:

• Installing, removing, or switching linux-cachyos* kernels or their *-nvidia / *-zfs modules
• Editing /etc/pacman.conf or any cachyos*-mirrorlist
• Loading or configuring scx_* schedulers, scx_loader, ananicy-cpp, gamemode, or game-performance
• Overriding sysctl, udev, ZRAM, or I/O scheduler behavior
• Running chwd or changing GPU / handheld / T2 profiles
• Changing bootloader, snapper, or recovery procedure
• Editing desktop / compositor config that a cachyos-*-settings package owns
• Working on a handheld (Steam Deck, ROG Ally, Legion Go, MSI Claw, …)
• Adding Cachy repos to an existing Arch box

If you are about to treat this machine as vanilla Arch, STOP.

Do NOT use this skill as the required path for writing CachyOS PKGBUILDs. Read packaging.md for that.

Topic Guides

Read the matching guide before starting:

• kernel.md — linux-cachyos* variants, Kernel Manager, matching modules
• repos.md — ISA repos, pacman.conf order, cachyos-repo.sh
• performance.md — scx, ananicy-cpp, gamemode, ZRAM, overrides
• hardware.md — chwd profiles, GPU migration, NVIDIA modules
• boot.md — Limine, snapper, cachy-chroot recovery
• desktop.md — settings packages, /etc/skel, Hyprland Noctalia+UWSM
• install.md — desktop vs handheld ISO, installer, Arch overlay
• packaging.md — CachyOS-PKGBUILDS, march/LTO/PGO
• handheld.md — Handheld Edition, linux-cachyos-deckify, scx_lavd

Critical Safety Rules

NEVER treat CachyOS as vanilla Arch. Arch Wiki is background. Cachy tools and this skill are the procedure.

NEVER edit shipped files under /usr/lib. They belong to CachyOS packages and will be overwritten.

# READ-ONLY examples — NEVER EDIT
/usr/lib/sysctl.d/70-cachyos-settings.conf
/usr/lib/udev/rules.d/          # shipped I/O and zram rules
/usr/share/scx_loader/config.toml

ALWAYS override here instead:

• /etc/sysctl.d/*.conf
• /etc/udev/rules.d/
• /etc/scx_loader/config.toml (copy from /usr/share/scx_loader/config.toml first)
• /etc/default/limine

NEVER put [core] above Cachy ISA repos in /etc/pacman.conf. Cachy v3 / v4 / znver4 entries MUST sit above [core]. See repos.md.

Do not disable ananicy-cpp merely because scx_loader is active. Current CachyOS guidance says they are usually compatible; disable Ananicy as a troubleshooting step if sched-ext stalls or becomes unstable. gamemode still overlaps with Ananicy's process-priority changes. See performance.md.

NEVER put a handheld on a desktop kernel. Handheld MUST use linux-cachyos-deckify. See handheld.md.

When wiki, README, and old articles disagree, do not pick a side. Verify live:

pacman -Si linux-cachyos linux-cachyos-lts linux-cachyos-server
kerver

Known unresolved conflicts (sources 2026-08-24, ISO 260809):

Privilege Escalation

Use sudo in a visible terminal for privileged work. NEVER start interactive sudo or pacman prompts that hang a headless agent unless the user is present. Use pacman --noconfirm only after the user approved the package set.

System Architecture

Decision Framework

1. Is this a handheld? Read handheld.md first. Stop if you were about to use desktop ISO/kernel/scheduler advice.
2. Is it a kernel or module change? kernel.md. Install the matching *-nvidia / *-zfs package. Use Kernel Manager.
3. Is it pacman / repos / -bin packages? repos.md. Check ISA with /lib/ld-linux-x86-64.so.2 --help.
4. Is it scheduling, gamemode, or sysctl/udev? performance.md. Inspect the active services and change only the layer involved; Ananicy does not need to be disabled solely for scx.
5. Is it GPU or other hardware? hardware.md. chwd -r then chwd -a. Do not fight nvidia-dkms with Cachy module packages.
6. Is it boot, snapshots, or an unbootable system? boot.md. cachy-chroot + Btrfs preset from a live ISO.
7. Is it a desktop / compositor tweak? desktop.md. /etc/skel does not update existing users.
8. Is it install media or converting Arch? install.md. Existing Arch is a repo overlay, not a conversion.
9. Is it a PKGBUILD? packaging.md only.

Out of Scope

• Vanilla Arch advice as if Cachy packages and repos were absent
• Another distro's agent skill text
• Inventing a default-agent CLI, mise stubs, or hotkeys (CachyOS has none)
• ISO engineering (image build, Calamares branding, first-login hooks). install.md covers using the published ISO only.
• Deep PKGBUILD authoring except via packaging.md

Example Requests

• "Switch me to the LTS kernel" → kernel.md, Kernel Manager, matching modules, then kerver
• "Enable scx_lavd on boot" → performance.md, inspect the current scheduler stack, then edit /etc/scx_loader/config.toml
• "I swapped my NVIDIA card for AMD" → hardware.md, chwd --list-installed, chwd -r <profile>, reboot, chwd -a
• "System will not boot after a kernel update" → boot.md, live ISO, cachy-chroot, Btrfs preset, Limine snapshot
• "Tune Hyprland gaps" → desktop.md. Do not follow the stock Hyprland wiki as if this were a stock install. Do not install archived cachyos-hyprland-settings.
• "Add Cachy repos to this Arch box" → repos.md + install.md. Overlay, not a conversion.