Guide · Agent skill
How to use the fleet-maintenance Mac agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
fleet-maintenance is an agent skill that teaches an AI agent to keep a small fleet of Macs in a defined state. It compares installed apps and packages against a desired inventory, audits related settings, and can apply Homebrew and global package updates or fast-forward repo syncs. This guide explains what the skill does, how to install it, how to ask for it in plain language, and what it needs before it will work well.
Mac Fleet Maintenancesteipete/agent-scripts · MIT Download the skill Quick start
- 1Install the skill. Download the ZIP from the directory page and unzip it into ~/.claude/skills/ or a project's .claude/skills/ folder, or upload it under Settings → Capabilities → Skills in the Claude apps.
- 2Prepare the inventory and host list. Create ~/Projects/manager/fleet/inventory.json and ~/Projects/manager/computers.yaml, since the skill assumes both exist.
- 3Validate the inventory. Run the validate subcommand of fleet-profile.mjs against your inventory file before any changes.
- 4Collect and plan one host. Collect observed inventory from a Mac, then run plan for that host to see missing and extra software.
- 5Run the audits and read the report. Ask the agent to run the relevant audit scripts and review results. Treat pending items as open work, not as success.
What is an agent skill and what does this one do?
An agent skill is a folder of instructions and scripts that an AI agent loads when a task matches the skill's description. This one, named fleet-maintenance, is written for Macs managed as a fleet, with two profiles: full for daily-driver Macs and worker for lean remote Macs that mainly run agent tools.
The skill's main jobs are to collect observed inventory, compare desired versus observed state, audit local-account escrow references, update Homebrew and global packages, safely sync repos and Xcode, and report disk, service, backup, update and security health.
- Compares installed software against a desired inventory with a minimum policy: required entries must exist, and extras are reported, not removed.
- Audits SSH access, the 1Password CLI, the Octopool GitHub cache, agent CLIs, a shared global Git ignore file and Claude attribution settings.
- Updates Homebrew and global npm packages and performs fast-forward repo syncs, under the safety rules described below.
Install the fleet-maintenance skill
Download the skill ZIP from the directory page and unzip it into one of two places. For a personal setup, use ~/.claude/skills/. For a single project, use the .claude/skills/ folder inside that project.
If you use the Claude apps instead, upload the skill under Settings → Capabilities → Skills.
- Personal: unzip into ~/.claude/skills/
- Project only: unzip into .claude/skills/ in the project root
- Claude apps: Settings → Capabilities → Skills, then upload
Set up the files the skill expects
The skill assumes a specific layout. It reads a desired-state inventory and a host list that you must create yourself. Without them it will fail or guess, so do not run it on an empty setup.
The skill's own docs name these paths: an inventory at ~/Projects/manager/fleet/inventory.json, a host topology file at ~/Projects/manager/computers.yaml, and fleet setup docs under ~/Projects/manager. The inventory stores opaque 1Password item IDs only, not secrets.
- ~/Projects/manager/fleet/inventory.json (desired software and credential references)
- ~/Projects/manager/computers.yaml (identity, SSH routing and handed-off hosts)
- Reviewed snapshots are stored at ~/Projects/manager/fleet/snapshots/<host-id>.json
Run the fleet tools directly
The skill ships a deterministic profile tool, fleet-profile.mjs, with subcommands for collecting evidence, planning a host, diffing two snapshots, generating a Brewfile and validating the inventory. Run these from the repository root, using the paths as the skill documents them.
The audit scripts in the same folder check specific areas. Collector snapshots are observed evidence, not configuration: diff reports candidates, and you decide what enters the full profile.
- collect: gather observed inventory from a Mac
- plan: show what a host needs compared with its snapshot
- diff: list packages found on a source host but not on a target
- brewfile: generate a Brewfile for a host
- validate: check the inventory file
node skills/fleet-maintenance/scripts/fleet-profile.mjs collect
node skills/fleet-maintenance/scripts/fleet-profile.mjs plan --fleet ~/Projects/manager/fleet/inventory.json --host mac-studio-sf --snapshot /path/to/mac-studio-sf.json
node skills/fleet-maintenance/scripts/fleet-profile.mjs diff --source /path/to/macbook-pro.json --target /path/to/mac-studio-sf.json
node skills/fleet-maintenance/scripts/fleet-profile.mjs brewfile --fleet ~/Projects/manager/fleet/inventory.json --host mac-studio-sf
node skills/fleet-maintenance/scripts/fleet-profile.mjs validate --fleet ~/Projects/manager/fleet/inventory.jsonAsk the agent for maintenance in plain language
You do not need to type script names. Describe the outcome you want and the agent should load the skill when your request matches its description. Be specific about the host and the kind of check, so the agent knows which audit to run.
Good requests name the goal, such as checking one Mac against its profile, auditing the agent tooling, or updating packages on eligible hosts. Ask for a report first if you are not yet sure what will change.
- Check mac-studio-sf against its fleet profile and list anything missing or extra.
- Audit the 1Password CLI and the GitHub cache on every Mac in the fleet.
- Compare macbook-pro's installed packages with the desired inventory and report the diff.
- Run the health report on all reachable hosts and tell me what is pending.
Safety notes before you run it
This skill runs scripts and uses the network. It reads Tailscale and SSH state, runs Homebrew and global npm updates, and can fast-forward repos. Some checks may need the 1Password CLI and a service-account token file with mode 0600.
Package updates are allowed while agents and services are running. That can disrupt the software being upgraded, mix old in-memory code with replaced files, and let Homebrew close and reopen cask GUI apps. The skill is written to never manually terminate or restart services, and never reset, clean, stash, rebase, push, install macOS updates or reboot during routine maintenance.
- Skip repos with a process running inside them or a Git lock.
- Dirty worktrees are only touched through the conflict-free fast-forward procedure.
- Keep a per-host action log; an unreachable host is pending, never current.
- Do not run unattended on production machines where interrupted upgrades would matter.
What people use it for
- Checking that a remote Mac has the required packages for the worker profile.
- Auditing whether the Codex and Claude Code CLIs are installed and can authenticate non-interactively.
- Confirming that GitHub commands resolve through the Octopool shim on each host.
- Generating a Brewfile for one host from the reviewed inventory.
- Reviewing which packages on a daily-driver Mac are missing from another host's snapshot.
Frequently asked questions
Is the fleet-maintenance skill free to use?
The source lists the skill under the MIT licence. Check the licence file in the repository for the exact terms before reuse, and note that the skill has no separate price in the source.
What do I need to install fleet-maintenance?
You need macOS with Homebrew, Node.js for the profile tool and its tests, and Bash with /usr/bin/perl. The skill also assumes the inventory and computers.yaml files exist, plus Tailscale and OpenSSH between hosts if you use the SSH checks.
Can I use fleet-maintenance on a single Mac?
The source says it is not designed for single-machine use. Most of its value comes from managing multiple hosts, and on one machine it would add risk without much benefit.
Where do I put the skill folder?
Unzip it into ~/.claude/skills/ for personal use or into .claude/skills/ in a project. In the Claude apps, upload it under Settings → Capabilities → Skills.
Why does the agent say a 1Password item is pending?
The skill treats a pending reference as acceptable during package maintenance rather than as an error. It only uses 1Password commands after the $one-password skill is loaded, and repairs need the token file to be provisioned.
How is this different from Homebrew Bundle or a simple update script?
Homebrew updates are only one part. This skill also compares observed state with a desired inventory, audits agent CLIs, the GitHub cache, Git ignore settings and Claude attribution, and reports pending hosts. It is a template for one owner's setup, so you would need to adapt its paths and inventory.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use fleet-maintenance if you run several Macs, already keep a similar inventory file, and want repeatable audits you can review before changes happen. Pick something simpler if you have one Mac, lack the referenced inventory and host files, or need unattended updates on machines where interrupted upgrades would cause real harm.
Download the skill