Arch Linux Administration

How to change an Arch based system without leaving it half upgraded, without editing what a package owns, and without losing the way back. Generic Arch knowledge applies everywhere. Derivatives add their own layer, so check which one the machine runs before applying a recipe.

Written for Arch Linux rolling, pacman 7, PipeWire 1 with WirePlumber 0.5. The commands that ran were run on one CachyOS host, and commands that were not executed are marked UNVERIFIED in the topic files.

Machine facts

Machine-specific facts live in MACHINE.md next to the global AGENTS.md: disks and mounts, volumes that must never be touched, the bootloader, the snapshot setup, custom fixes, and the change log. Read it before acting. This skill carries no facts about any single machine. Where a topic file says to discover something, run the command, compare the answer with MACHINE.md, and report a disagreement rather than picking one silently.

When to activate

• Any pacman, paru, yay or makepkg command, including a read-only query
• An upgrade, a downgrade, or a download error from a mirror
• A .pacnew or .pacsave file, or a change under /etc
• Disk space, orphans, caches, snapshots or a rollback
• A failed systemd unit, a journal question, a crash, a coredump
• Any audio problem on PipeWire, WirePlumber or ALSA
• Also covers pacman, the AUR with paru or yay, makepkg and PKGBUILD review, full upgrades and the pre-upgrade news check, partial upgrades and mirror 404s, .pacnew and .pacsave merging, orphans and cache cleanup, snapper snapshots and rollback, systemd units and journal triage, coredump crash diagnosis, PipeWire and WirePlumber audio, and editing configuration without touching packaged files
• The user says "failed retrieving file", "unable to satisfy dependency", "No module named build", "free up disk space", "clean up leftovers", "this service failed", "the program crashed", "no sound" or "where do I override this config"

When not to activate

• CachyOS kernels, the v3 repositories, chwd, the NVIDIA module packages, Limine or cachyos-settings, use cachyos
• Plasma panels, widgets, KWin, shortcuts, themes or konsave, use kde-plasma
• Writing an Ansible role that provisions Arch hosts, use ansible
• A shell script that happens to call pacman, use bash for the script itself

Hard rules

1. Upgrade the whole system, then install. Never pacman -Sy <pkg> and never pacman -Sy alone.
2. The agent does not run sudo. Print the command with what it changes, and the owner runs it. In Claude Code the ! prefix runs a command in the owner's session, where the password prompt works.
3. Snapshot before a risky change, using the snapshot tool MACHINE.md names.
4. Never edit a file a package owns. Override in /etc drop-ins or under ~.
5. Read every PKGBUILD and .install file before building from the AUR.
6. Record every system change in the change log of MACHINE.md, with how to undo it.
7. Measure the live system before answering. Use pacman -Qi, pacman -Ql, man, and the offline Arch Wiki through wiki-search where arch-wiki-lite is installed, rather than memory.

Related skills

• cachyos owns everything a CachyOS host adds on top of Arch
• kde-plasma owns the Plasma desktop configuration
• ansible owns provisioning the same changes reproducibly
• bash owns scripts that wrap these commands
• The security-auditor agent owns judging whether an AUR package or a third party repository is trustworthy enough

Checklist

• MACHINE.md read before the first change
• News checked and pending updates listed before any full upgrade
• No -Sy without u, no --overwrite '*', no -Rdd, no IgnorePkg used to dodge an error
• Every root command handed to the owner, never run by the agent
• Snapshot taken before kernel, bootloader, initramfs, fstab or bulk removal work
• No packaged file edited, every override placed in a drop-in
• Every PKGBUILD read before building
• The change and its undo recorded in the MACHINE.md change log