How do I install the Yabai Skhd Doctor skill?

Run npx skillmds@latest add lkshrk/yabai-skhd-doctor in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Yabai Skhd Doctor safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Yabai Skhd Doctor?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Yabai Skhd Doctor free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Yabai Skhd Doctor?

lkshrk (@lkshrk) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Yabai Skhd Doctor by lkshrk — Agent Skill

Name: Yabai Skhd Doctor
Author: lkshrk

Yabai Skhd Doctor

Health-check the macOS yabai (tiling window manager) and skhd (hotkey daemon) services — verify they are installed, their launchd services are running, they hold Accessibility permission, configs exist, and yabai's scripting-addition prereqs (SIP, sudoers) are met. When anything is wrong it prints a concrete fix path. Use when yabai or skhd stopped working, hotkeys/window management aren't responding, after a macOS update, or when the user asks to check/verify/diagnose/fix their yabai or skhd setup.

lkshrk Updated Sep 17, 2026

File contents

yabai + skhd doctor

Read-only diagnostic for a macOS yabai + skhd setup. It changes nothing — it inspects the system and proposes a fix path the user (or you) can act on.

Run it

bash scripts/diagnose.sh

macOS only (uses launchctl, csrutil, sw_vers). Run as the logged-in user, not sudo — the Accessibility checks must see that user's session.

What it checks

Per service (yabai, skhd):

Binary installed + version.
launchd service registered and running (with last exit code).
Config present (~/.config/<svc>/<svc>rc, falling back to ~/.<svc>rc).
Accessibility permission: yabai is probed with yabai -m query (a response proves running + AX); skhd is inferred from /tmp/skhd_$USER.err.log.

yabai scripting addition (optional, advanced):

SIP status (csrutil status) — SA needs it partially disabled.
Passwordless --load-sa sudoers entry.

Reading the output

✓ healthy · ✗ broken, has a fix · ? unknown/advisory. Findings print per section; a numbered Proposed fix path collects every remediation at the end.

Acting on the fix path

Present the fix path to the user. Most fixes are safe to run for them (brew install ..., yabai --start-service, --restart-service). Two cannot be done from the CLI and must be handed to the user:

Accessibility permission — only grantable in System Settings ▸ Privacy & Security ▸ Accessibility (toggle yabai / skhd on). After granting, restart the service; macOS does not apply a new permission to a running process.
SIP / scripting addition — disabling SIP needs a Recovery-mode reboot; only pursue if the user actually wants SA features. Link the yabai wiki, don't attempt it.

Never sudo the script or auto-disable SIP. Confirm with the user before any change beyond starting/restarting a service.

---name: yabai-skhd-doctordescription: Health-check the macOS yabai (tiling window manager) and skhd (hotkey daemon) services — verify they are installed, their launchd services are running, they hold Accessibility permission, configs exist, and yabai's scripting-addition prereqs (SIP, sudoers) are met. When anything is wrong it prints a concrete fix path. Use when yabai or skhd stopped working, hotkeys/window management aren't responding, after a macOS update, or when the user asks to check/verify/diagnose/fix their yabai or skhd setup.---# yabai + skhd doctorRead-only diagnostic for a macOS yabai + skhd setup. It changes nothing — itinspects the system and proposes a fix path the user (or you) can act on.## Run it```bashbash scripts/diagnose.sh```macOS only (uses `launchctl`, `csrutil`, `sw_vers`). Run as the logged-in user,**not** sudo — the Accessibility checks must see that user's session.## What it checksPer service (yabai, skhd):- Binary installed + version.- launchd service registered and running (with last exit code).- Config present (`~/.config/<svc>/<svc>rc`, falling back to `~/.<svc>rc`).- Accessibility permission: yabai is probed with `yabai -m query` (a response proves running + AX); skhd is inferred from `/tmp/skhd_$USER.err.log`.yabai scripting addition (optional, advanced):- SIP status (`csrutil status`) — SA needs it partially disabled.- Passwordless `--load-sa` sudoers entry.## Reading the output`✓` healthy · `✗` broken, has a fix · `?` unknown/advisory. Findings print persection; a numbered **Proposed fix path** collects every remediation at the end.## Acting on the fix pathPresent the fix path to the user. Most fixes are safe to run for them(`brew install ...`, `yabai --start-service`, `--restart-service`). Two cannotbe done from the CLI and must be handed to the user:- **Accessibility permission** — only grantable in System Settings ▸ Privacy & Security ▸ Accessibility (toggle yabai / skhd on). After granting, restart the service; macOS does not apply a new permission to a running process.- **SIP / scripting addition** — disabling SIP needs a Recovery-mode reboot; only pursue if the user actually wants SA features. Link the yabai wiki, don't attempt it.Never `sudo` the script or auto-disable SIP. Confirm with the user before anychange beyond starting/restarting a service.

Frequently asked questions