How to use the SSH Doctor agent skill

What is an agent skill, and what does SSH Doctor make the agent do?

An agent skill is a folder containing a SKILL.md file with instructions the AI agent loads when a task matches the skill's description. SSH Doctor's description is "SSH triage: Remote Login, launchd sshd, pre-auth closes, stale sessions."

The skill is for macOS machines where SSH connects but then closes before authentication, or where Remote Login appears enabled but does not work. Once loaded, the agent follows a fixed order: it validates locally first, using loopback (127.0.0.1) to tell server-side problems from network problems. It then reads the sshd configuration and system logs, looks for stuck sshd-session processes, and only checks the firewall and packet filter if loopback works but remote login fails.

The skill can also restart the SSH service and, when stranded sessions clearly block new logins, terminate them. It includes a procedure for copying a 1Password service account token line into a user's ~/.profile on a Mac.

Install SSH Doctor: download the ZIP and unzip it into a skills folder

Download the ssh-doctor ZIP from this page and unzip it. The package contains SKILL.md. For a personal setup, place the ssh-doctor folder in ~/.claude/skills/. For a single project, place it in that project's .claude/skills/ folder instead, so it applies only there.

If you use the Claude apps rather than a local folder, you can upload the skill under Settings → Capabilities → Skills.

• Personal install: ~/.claude/skills/ssh-doctor/
• Project install: .claude/skills/ssh-doctor/ inside your project
• Claude apps: Settings → Capabilities → Skills

Check that the skill is ready before you rely on it

Confirm the requirements first. You need macOS with sudo access and an OpenSSH server (sshd) running on the target Mac. The commands use standard macOS tools: launchctl, systemsetup, lsof, socketfilterfw, pfctl and log.

The skill runs scripts and uses the network, so review what it will execute before you approve it. Its baseline checks begin with a non-interactive SSH test that you can also run yourself, which uses RequestTTY=no and RemoteCommand=none so no shell or command is started on the remote side beyond the test.

Trigger the skill with a natural request

You do not need to type the skill name. The agent matches your request against the skill's description, so describe the symptom. The source says the skill applies when SSH connects then closes before auth, when Remote Login seems advertised but unusable, or when local or remote Mac SSH needs diagnosis.

Give the agent the context it needs: which Mac, whether you are working locally or remotely, and what you already tried. Naming the symptom in the client's words helps, such as "connection closed by remote host" during key exchange.

• "My Mac's SSH server accepts connections but drops them before login. Use SSH Doctor to diagnose it."
• "Remote Login shows as on in System Settings but I can't connect from my laptop. Check it."
• "Diagnose SSH on this Mac: is it a server problem or a firewall problem?"

What the agent checks and in what order

The skill's rules tell the agent to report suspicious configuration lines before changing /etc/ssh/sshd_config, and not to print secrets, tokens or full environment output. A loopback failure points to sshd, launchd or config on the server. Loopback success with remote failure points to the network, firewall, filter or listen path.

A key symptom the skill describes is a client message of kex_exchange_identification: Connection closed by remote host, paired with a server log line reading "Could not create new instance of inetd service: 67: Too many processes", a high copy count in launchctl output, and many sshd-session: USER processes parented by PID 1. The skill reads this as launchd accepting TCP connections but refusing to spawn more sshd copies.

• Baseline: system info, Remote Login status, launchd state of com.openssh.sshd, listening port 22, and a loopback login test
• Config: effective sshd settings and any AllowUsers, DenyUsers, Match, MaxStartups or LoginGraceTime lines
• Logs: sshd and launchd entries from the last 30 minutes
• Stale sessions: inspect sshd-session processes before terminating anything
• Firewall: socketfilterfw, pfctl and listening interface, only after loopback works

Example: clearing stale sshd-session processes

When the launchd copy count is high and many sshd-session processes are parented by PID 1, the skill first inspects them and lists their state and elapsed time without changing anything. Only if the sessions are clearly stranded and blocking new SSH does it send a TERM signal to matching processes, wait two seconds, and list again. If TERM leaves blockers, the skill says to re-check ownership and active shells before using KILL.

Read the inspection output yourself before approving the termination step. Ending a session someone is actively using is the main risk here.

Safety notes: sudo, scripts, network and secrets

SSH Doctor uses sudo, can kill processes, can restart the SSH service, and can edit system files. Read every command before it runs, especially anything touching /etc/ssh/sshd_config, launchd, or running sessions. The skill itself does not say it will make a backup before editing configuration, so do not assume one exists.

The token section moves a secret between hosts. It asks the agent to verify markers without printing the value, copy only the matching line through a chmod 600 temporary file, and never echo the token. Do not use that section with shared or production credentials unless someone has reviewed the exact commands. Remove the temporary file if a step fails.

• Read each command before approving it
• Avoid the token-copy section for shared or production credentials without review
• Expect the skill to use sudo and the network

Tips for getting useful results

Ask the agent to report its findings before it makes changes. The skill's closeout asks for the root cause, the exact commands changed, validation output (redacted as needed), and whether the remote should retry. Keep that report; it is your record of what changed.

Run the checks on the machine that has the problem, and compare loopback with remote results. That comparison is what separates a server fault from a network or firewall fault.

• Ask for a root-cause report before any change is made
• Keep the closeout report for your records
• If you manage several Macs, run the same baseline on each so the results are comparable