Guide · Agent skill

How to use the Mac Maintenance agent skill (mac-maintenance)

Updated 2026-11-02 · written with AI from the project's own documentation and checked against our catalogue data

The Mac Maintenance skill (skill name mac-maintenance) teaches an AI agent a fixed cleanup routine for a Mac: upgrade Homebrew packages, pull the latest changes into your git repositories under ~/Projects, and empty the Finder Trash. It is useful for Mac developers who keep many repositories and use Homebrew. After this guide you will know what the skill does, how to install it, how to ask for it in plain language, and what to check before running it.

Mac Maintenancesteipete/agent-scripts · MIT Download the skill

Quick start

1Check your requirements. Confirm you are on macOS, that brew and git work in Terminal, and that your repositories are under ~/Projects.
2Download and unzip the skill. Download the mac-maintenance ZIP from this page and unzip it to get the folder containing SKILL.md.
3Place the folder. Move it into ~/.claude/skills/ for personal use, or into a project's .claude/skills/ folder, or upload it under Settings → Capabilities → Skills in the Claude apps.
4Ask for a Mac cleanup. Make a plain request such as asking for Mac cleanup or a Homebrew and repo refresh.
5Review skipped and failed items. Check the summary for skipped repositories and failures, and handle dirty repositories yourself.
6Confirm the Trash before emptying. Make sure nothing you still need is in the Trash, since the skill empties it permanently.

What an agent skill is and what this one does

An agent skill is a folder with a SKILL.md file that gives an AI agent instructions for a specific task. When the agent sees a request that matches the skill, it follows those instructions instead of working everything out from scratch.

The mac-maintenance skill covers Mac cleanup and refresh requests. The agent runs the same steps each time: it updates and upgrades Homebrew, goes through each git repository in ~/Projects and runs a fast-forward pull, and then empties the Finder Trash. It ends with a short count of what was upgraded, pulled, skipped, or failed.

Homebrew: runs brew update and then brew upgrade
Repositories: checks each repo under ~/Projects and runs git pull --ff-only
Trash: empties the Finder Trash through osascript
Summary: reports brew upgraded or already current, repos pulled, skipped or failed, and trash emptied or failed

brew update && brew upgrade

What you need before installing

The skill is written for macOS and assumes the tools it calls are already set up. If one is missing, the matching step will fail or do nothing useful.

macOS
Homebrew installed, so the brew command works
Git installed
Your repositories stored under ~/Projects
Permission for Terminal or the agent to control Finder through osascript

Install the mac-maintenance skill

Download the ZIP for the skill from this page and unzip it. The skill is a single file, SKILL.md, inside a folder named for the skill. You can install it in one of two places, depending on how you use your agent.

For a personal setup, place the unzipped folder in ~/.claude/skills/. For a single project, place it in that project's .claude/skills/ folder. If you use the Claude apps, you can instead upload the skill under Settings → Capabilities → Skills.

Personal use: unzip into ~/.claude/skills/
Single project: unzip into the project's .claude/skills/ folder
Claude apps: upload under Settings → Capabilities → Skills

Trigger the skill with a natural request

You do not need a special command. The skill is meant to be used when you ask for Mac cleanup, maintenance, or a package and repository refresh. Describe what you want in ordinary words and the agent should pick up the skill.

Good requests name the parts you care about, such as Homebrew, your repos, or the Trash. Asking for everything gives you the full routine.

Do a Mac cleanup.
Refresh my Homebrew packages and pull my repos.
Update brew and pull my clean repositories, then empty the Trash.
Run Mac maintenance and tell me what was skipped.

Understand how repositories are handled

For each folder under ~/Projects that contains a .git directory, the skill prints the branch and status, then runs git pull --ff-only. The fast-forward option means the pull only succeeds when it can move forward cleanly. It does not create merge commits.

The skill tells the agent to skip repositories with uncommitted changes unless you explicitly ask it to handle them, and to report the skipped paths. Dirty repositories therefore need your attention.

Clean repositories are pulled with --ff-only
Repositories with uncommitted changes are skipped by default and listed in the report
You can ask the agent to handle a specific dirty repository if you want it to act on it

for repo in ~/Projects/*/.git; do
  dir=${repo:h}
  git -C "$dir" status --short --branch
  git -C "$dir" pull --ff-only
done

Read the summary and check the results

At the end, the agent reports terse counts. Read them to confirm what changed. A repository listed as failed or skipped needs a manual look, and an emptied Trash cannot be undone by the skill.

brew: upgraded or already current
repos: pulled, skipped, or failed
trash: emptied or failed

What people use it for

Refreshing a set of client and side-project repositories in ~/Projects before starting work for the day
Upgrading Homebrew packages on a schedule you trigger by asking the agent
Getting a short written record of which repositories were pulled and which were skipped
Clearing the Trash as the last step of a routine Mac cleanup

Frequently asked questions

How do I install the mac-maintenance agent skill?

Download the ZIP from this page and unzip it. Put the folder in ~/.claude/skills/ for personal use, in a project's .claude/skills/ folder, or upload it in the Claude apps under Settings → Capabilities → Skills.

What do I need to run the mac-maintenance skill?

You need macOS, Homebrew with the brew command, Git, and repositories under ~/Projects. The skill also needs permission for Terminal or the agent to control Finder through osascript.

Is the mac-maintenance skill free?

The skill is licensed under MIT, as stated for this item. This page does not list a price, so check the licence terms in the source before reuse.

Will the skill delete files from my repositories?

The skill runs git pull --ff-only on clean repositories and skips those with uncommitted changes unless you explicitly ask otherwise. Its only deletion step is emptying the Finder Trash.

Why did the skill skip one of my repositories?

It skips repositories with uncommitted changes so it does not disturb your work. The agent reports the skipped paths, and you can ask it to handle a specific one.

Can I use this skill if I don't use Homebrew?

Not usefully. The first step runs brew update and brew upgrade, so without Homebrew those commands will fail. The repository and Trash steps can still be run by hand, but the skill is designed around all three.

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

This skill suits Mac developers who keep many git repositories in ~/Projects and use Homebrew, and who want one short, repeatable cleanup routine. Skip it if you are not on macOS, do not use Homebrew, or would like dirty repositories cleaned up automatically. Also check the Trash before running it, because emptying it permanently removes files.

Download the skill