Guide · Agent skill
How to use the Remote Mac Operator agent skill (remote-mac)
Updated · written with AI from the project's own documentation and checked against our catalogue data
The remote-mac skill is a set of written operating instructions that tells an AI agent how to find, connect to and work on a specific group of remote Macs, plus a few other machines, using Tailscale and SSH. It is built around one owner's private fleet, so it is most useful as a worked example of a safety-focused machine runbook, or as a template for your own. This guide explains what a skill is, how to install this one, how to trigger it, and what it needs before you rely on it.
Remote Mac Operatorsteipete/agent-scripts · MIT Download the skill Quick start
- 1Read SKILL.md first. Open the file and check which hosts, names and rules it refers to. Confirm they match your own machines before you install it.
- 2Place the skill folder. Unzip the downloaded ZIP into ~/.claude/skills/ for personal use, or into a project's .claude/skills/ folder for a single project.
- 3Or upload it in the Claude apps. In the Claude apps, go to Settings → Capabilities → Skills and upload the ZIP instead.
- 4Prepare Tailscale and SSH. Log into your tailnet on the machine running the agent and make sure SSH keys work for each host you plan to use.
- 5Make a request that names a machine or task. Ask the agent to check or run something on a named Mac, and watch whether it verifies the target before acting.
What is an agent skill and what does remote-mac do?
An agent skill is a folder containing a SKILL.md file with instructions that an AI agent reads when a request matches the skill's description. The agent then follows those instructions instead of guessing how your environment is set up.
The remote-mac skill covers routing and safety for remote Macs. It explains which machine to use for which task, how to find live hosts through Tailscale and local network discovery, how to connect over SSH without interactive prompts, and which machines or actions to leave alone, such as retired nodes, machines handed to someone else, and provider actions that affect data, which need explicit approval.
- Chooses a target machine by task and by verified identity, not just because it appears online.
- Discovers live hosts with tailscale status and, in some environments, LAN discovery.
- Connects with non-interactive SSH and uses tmux for long-running work.
- Stops and asks before reboots, reimages, erases, or credential changes.
Install the remote-mac skill
Download the skill ZIP from the page, then choose one of two install locations. For a personal setup, unzip it into your user skills folder at ~/.claude/skills/. For a single project, unzip it into that project's .claude/skills/ folder so it applies only there.
You can also upload the ZIP in the Claude apps under Settings → Capabilities → Skills. Once installed, the folder should contain SKILL.md, which is the only file in this skill.
- Personal use: ~/.claude/skills/
- Project use: .claude/skills/ inside the project folder
- Claude apps: Settings → Capabilities → Skills, then upload the ZIP
~/.claude/skills/remote-mac/SKILL.mdHow do you trigger the skill with natural requests?
You do not need a special command. The skill's description is about remote Macs, Tailscale and SSH, so the agent will consider it when your request mentions those topics. The SKILL.md also lists specific names that trigger it, such as MacBook, Mac Studio, Tailscale, or a request to run or check something on one of the owner's Macs.
Requests work best when they name the machine or the task. Because the skill's rules are written for one owner's fleet, a request that names a machine the skill does not know about will not be routed correctly.
- Check whether the Mac Studio is reachable over Tailscale and report its status.
- Run a read-only check on the remote Mac and summarize the output.
- Find which Tailscale peers are live before you pick a machine for this task.
- Look for SSH services on the local network if Tailscale is down.
Safe connection and discovery rules the skill applies
The skill tells the agent to start with live Tailscale status and use current IP addresses, because cached addresses can be stale. When one physical Mac shows several Tailscale peers, it requires the agent to verify the machine identity before choosing one, and to keep a fallback path before stopping any backend.
For SSH, the default is non-interactive. The skill uses options that stop the connection from waiting for a terminal, and it recommends tmux on the remote host for long or interactive work.
- Default SSH form: ssh -o RequestTTY=no -o RemoteCommand=none HOST 'COMMAND'
- Verify ComputerName, LocalHostName, hardware UUID and node ID before acting on a peer.
- Do not use LAN discovery from environments where it is not allowed.
- Stop and report if a required Mac is offline; do not guess a replacement.
ssh -o RequestTTY=no -o RemoteCommand=none HOST 'COMMAND'What you need before the skill works
The skill assumes a specific setup. It will not work as written on a different fleet, because it names specific machines, rules and private inventory files that you would need to create yourself. Check these requirements before you install it.
The skill also refers to a private manager repository that is not included in the download. Without those inventory files, the agent cannot resolve the machine names and rules the skill depends on.
- Tailscale installed and logged into your tailnet.
- SSH access with keys to every host you want the agent to reach.
- Command-line tools named in the skill: tailscale, ssh, dns-sd and arp on macOS.
- Access to your own equivalent of the private computers.yaml and agents.yaml inventory, which is not included.
Safety notes: scripts and network use
The skill runs no bundled scripts. It consists of instructions only, so the agent carries out commands using tools already on your machine. It does use the network, because it connects to remote hosts over Tailscale and SSH and, in some cases, runs local network discovery.
Treat the skill's safety rules as guidance to the agent, not as a guarantee. The file asks the agent to stop before data-affecting actions, but an agent that ignores those rules could still cause an outage or data loss, so keep provider and production hosts under close supervision.
- No bundled scripts; the agent uses commands already installed on your system.
- Network use: Tailscale status checks, SSH connections and optional LAN discovery.
- Do not use it unsupervised on production or provider-managed machines.
- Read SKILL.md before installing so you know exactly which hosts and rules it references.
What people use it for
- Checking whether a remote Mac is reachable over Tailscale and reporting its status.
- Running a read-only health check on a remote Mac and summarizing the output.
- Using the skill's identity checks as a model for your own multi-host runbook.
Frequently asked questions
Is the remote-mac skill free to use?
The skill is published under the MIT licence, which permits use, modification and redistribution with the licence notice retained. It is not a paid product, but it is written for one owner's private fleet, so it needs adapting before it works for you.
What do I need to install remote-mac?
You need Tailscale logged into your tailnet, SSH keys for each host, and the command-line tools tailscale, ssh, dns-sd and arp on macOS. You also need your own version of the private inventory files, since the skill references them but does not include them.
How do I install a skill in Claude?
Download the ZIP and unzip it into ~/.claude/skills/ for personal use or into a project's .claude/skills/ folder. You can also upload the ZIP in the Claude apps under Settings → Capabilities → Skills.
Will remote-mac work on my own Macs without changes?
Probably not as written. Its hostnames, IP addresses and routing rules belong to one private fleet, so on your machines it could route commands to the wrong host or refuse valid targets. Use it as a template and replace the topology with your own.
Why does the agent say a Mac is offline when it is powered on?
The skill checks live Tailscale status first. If the Mac is not connected to the tailnet, or SSH times out, the skill tells the agent to stop and report rather than guess. Reconnect Tailscale or wake the machine, then ask again.
How does remote-mac compare with a general SSH helper?
A general SSH helper just runs commands. This skill is mostly policy and topology: it decides which machine to use, checks identity, and blocks data-affecting actions without approval. It contains no bundled scripts of its own.
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 remote-mac if you maintain a similar private Mac fleet and want an agent to follow explicit routing and safety rules, or if you want a detailed example of a machine runbook to adapt. Pick something else if you need a general-purpose SSH tool or an unsupervised automation for production or provider-managed hosts, because the skill's rules are specific to one fleet and depend on the agent honouring them.
Download the skill