agentleFS
bnaylorbnaylor/agent_skills/rasp-pi-janitor/SKILL.md

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.

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
  1. Very specific:

    Verification: Verify SSH connectivity and sudo privileges on all nodes.

    line 21
  2. Very specific:

    Update Check: Run sudo apt-get update to refresh package lists.

    line 25
  3. Distinctive:

    Pi-hole Update Check: Check if Pi-hole updates are available.

    line 27
  4. Very specific:

    Reboot Status: Check if a reboot is pending — both /var/run/reboot-required AND a staged kernel update (compare running vs newest installed …

    line 28
  5. Very specific:

    Disk Space: Verify sufficient disk space in / and the boot directory (/boot or /boot/firmware on Bookworm+).

    line 29
  6. Very specific:

    If /var/run/reboot-required exists or a kernel was updated, initiate sudo reboot.

    line 44
  7. Very specific:

    Wait for the node to become reachable again via SSH, comparing boot ID (/proc/sys/kernel/random/boot_id) to confirm a successful restart.

    line 45
  8. Distinctive:

    Mandatory Health Check: Verify system health (uptime, Pi-hole service status, and disk space).

    line 46
  9. Distinctive:

    Verify Pi-hole is functioning correctly after updates.

    line 51
  10. Distinctive:

    Run the maintenance script using:

    line 55
  11. Very specific:

    Kernel Checks: Always check for a staged kernel update after a dist-upgrade (compare uname -r to newest /lib/modules entry).

    line 68
  12. Very specific:

    Pi-hole Service: Ensure pihole-FTL service is active after reboot.

    line 69
  13. Very specific:

    When checking for Pi-hole availability via SSH, ensure the check result is passed into the update step.

    line 79
  14. Distinctive:

    Run post-flight health checks even when no reboot was triggered.

    line 82

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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 sudo or SSH key-based authentication for the user.
  • Target systems must be Raspberry Pi OS (Debian-based).
  • Pi-hole must be installed and the pihole CLI 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 sudo privileges on all nodes.
  • OS Check: Confirm the OS is Raspberry Pi OS / Debian-based.

2. Audit & Pre-flight

  • Update Check: Run sudo apt-get update to 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-required AND a staged kernel update (compare running vs newest installed kernel; see Pitfalls).
  • Disk Space: Verify sufficient disk space in / and the boot directory (/boot or /boot/firmware on Bookworm+).

3. Execution (The Maintenance Window)

For each node (or in parallel if requested):

  1. System Package Upgrade:
    • sudo apt-get update
    • sudo apt-get upgrade -y
    • sudo apt-get dist-upgrade -y (optional, for kernel/major updates)
  2. Pi-hole Update:
    • sudo pihole -up
  3. Cleanup:
    • sudo apt-get autoremove -y
    • sudo apt-get clean
  4. Reboot Management:
    • If /var/run/reboot-required exists or a kernel was updated, initiate sudo 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).

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 (compare uname -r to newest /lib/modules entry); RPi OS does not set /var/run/reboot-required on kernel updates.
  • Pi-hole Service: Ensure pihole-FTL service is active after reboot.
  • Locking: Be aware of flock or apt locks; 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 list interpretation, /boot layout 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.