rasp-pi-janitor
Skill4 starsChanged 5 months agoMITView on GitHub
Remotely maintains and upgrades Raspberry Pi systems running Pi-hole via SSH. Handles apt updates, upgrades, Pi-hole software updates, kernel patches, and safe reboots. Use when you need to synchronize OS versions or apply updates to a fleet of Raspberry Pi systems running Pi-hole.
In this repository9 other files it gives its agents.
- agent-cprSkill
- anti-sycophancySkill
- cve-remediationSkill
- discord-coordinationSkill
- gui-test-leaseSkill
- infisical-proSkill
- microk8s-janitorSkill
- nats-coordinationSkill
- ubuntu-janitorSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
14 rules. About 0 are common, 5 are distinctive, and 9 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈5
Distinctive · estimate
This author's own choices. Worth a look.
9
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 21
Verification: Verify SSH connectivity and sudo privileges on all nodes.
- Very specific: line 25
Update Check: Run sudo apt-get update to refresh package lists.
- Distinctive: line 27
Pi-hole Update Check: Check if Pi-hole updates are available.
- Very specific: line 28
Reboot Status: Check if a reboot is pending — both /var/run/reboot-required AND a staged kernel update (compare running vs newest installed …
- Very specific: line 29
Disk Space: Verify sufficient disk space in / and the boot directory (/boot or /boot/firmware on Bookworm+).
- Very specific: line 44
If /var/run/reboot-required exists or a kernel was updated, initiate sudo reboot.
- Very specific: line 45
Wait for the node to become reachable again via SSH, comparing boot ID (/proc/sys/kernel/random/boot_id) to confirm a successful restart.
- Distinctive: line 46
Mandatory Health Check: Verify system health (uptime, Pi-hole service status, and disk space).
- Distinctive: line 51
Verify Pi-hole is functioning correctly after updates.
- Distinctive: line 55
Run the maintenance script using:
- Very specific: line 68
Kernel Checks: Always check for a staged kernel update after a dist-upgrade (compare uname -r to newest /lib/modules entry).
- Very specific: line 69
Pi-hole Service: Ensure pihole-FTL service is active after reboot.
- Very specific: line 79
When checking for Pi-hole availability via SSH, ensure the check result is passed into the update step.
- Distinctive: line 82
Run post-flight health checks even when no reboot was triggered.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Raspberry Pi Janitor
This skill is a fork of ubuntu-janitor adapted for Raspberry Pi systems running Pi-hole. It preserves the Ubuntu update workflow and adds Pi-hole-specific update steps.
Prerequisites
- SSH access to the target Pi(s).
- Passwordless
sudoor SSH key-based authentication for the user. - Target systems must be Raspberry Pi OS (Debian-based).
- Pi-hole must be installed and the
piholeCLI must be available.
Core Workflows
1. Host Discovery & Connectivity
- Input: Accept a list of hostnames, IPs, or a CIDR range.
- Verification: Verify SSH connectivity and
sudoprivileges on all nodes. - OS Check: Confirm the OS is Raspberry Pi OS / Debian-based.
2. Audit & Pre-flight
- Update Check: Run
sudo apt-get updateto refresh package lists. - Pending Updates: Identify packages that will be upgraded or installed.
- Pi-hole Update Check: Check if Pi-hole updates are available.
- Reboot Status: Check if a reboot is pending — both
/var/run/reboot-requiredAND a staged kernel update (compare running vs newest installed kernel; see Pitfalls). - Disk Space: Verify sufficient disk space in
/and the boot directory (/bootor/boot/firmwareon Bookworm+).
3. Execution (The Maintenance Window)
For each node (or in parallel if requested):
- System Package Upgrade:
sudo apt-get updatesudo apt-get upgrade -ysudo apt-get dist-upgrade -y(optional, for kernel/major updates)
- Pi-hole Update:
sudo pihole -up
- Cleanup:
sudo apt-get autoremove -ysudo apt-get clean
- Reboot Management:
- If
/var/run/reboot-requiredexists or a kernel was updated, initiatesudo reboot. - Wait for the node to become reachable again via SSH, comparing boot ID (
/proc/sys/kernel/random/boot_id) to confirm a successful restart. - Mandatory Health Check: Verify system health (uptime, Pi-hole service status, and disk space).
- If
4. Verification
- Confirm all nodes are on the latest available versions.
- Report any nodes that failed to update or reboot.
- Verify Pi-hole is functioning correctly after updates.
Usage
Run the maintenance script using:
python3 scripts/pi_maintenance.py [nodes ...] [options]Arguments and Options:
nodes: Space-separated list of hostnames or IP addresses of the target Raspberry Pi systems.--dry-run: Show what would be done without making any changes.--parallel: Process target nodes in parallel (useful for large sets of nodes, but sequential updates are recommended for primary/secondary DNS clusters to prevent downtime).--dist-upgrade: Perform a full distribution upgrade (sudo apt-get dist-upgrade -y) to apply kernel and firmware updates.
Best Practices
- Sequential Updates: For clusters, update nodes one at a time to maintain service availability.
- Kernel Checks: Always check for a staged kernel update after a
dist-upgrade(compareuname -rto newest/lib/modulesentry); RPi OS does not set/var/run/reboot-requiredon kernel updates. - Pi-hole Service: Ensure
pihole-FTLservice is active after reboot. - Locking: Be aware of
flockoraptlocks; wait or report if the frontend is locked.
Session References
references/pihole-2026-07-20.md— no-op run notes: SSH/disk/preflight checks,apt listinterpretation,/bootlayout on this host.references/pihole-2026-09-01.md— full maintenance run: kernel update, Pi-hole Core/Web/FTL update, reboot, and the RPi OS kernel-reboot detection lesson.
Pitfalls
Pi-hole CLI availability check
When checking for Pi-hole availability via SSH, ensure the check result is passed into the update step. Don't re-check availability inside run_updates() from a separate local result object; use the preflight result passed into the update function.
Post-flight checks even without reboot
Run post-flight health checks even when no reboot was triggered. If updates and Pi-hole upgrade succeeded, the node may still need service-level verification. Only skip post-flight checks when the update or reboot step itself failed.
Kernel update reboot detection (Raspberry Pi OS)
Raspberry Pi OS does NOT create /var/run/reboot-required when a kernel update is installed. Relying on that file alone misses pending kernel reboots — the system keeps running the old kernel while the new one sits staged in /boot/firmware. Always also compare the running kernel (uname -r) against the newest installed kernel in /lib/modules (matching flavor). The script's kernel_reboot_needed() helper does this. Do not rely on /var/run/reboot-required alone.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

