agent-desktop-macos — скилл для Claude Code: что делает и установка
Скилл agent-desktop-macos для Claude Code настраивает правила автоматизации графического интерфейса macOS через CLI agent-desktop. Управляет разрешениями TCC и координирует работу с системными меню.
Apache-2.0 1 100 установок ★ 25 974 обновлён 2026-11-15
npx skills add vercel-labs/agent-desktop --skill agent-desktop-macos -a claude-codeЧто делает agent-desktop-macos
Скилл задаёт инструкции для управления программами в macOS через утилиту agent-desktop. Включает клики, ввод текста и скролл через физические координаты или семантические вызовы AXPress. Направляет агента при взаимодействии с меню приложений, строкой состояния через --surface menu-bar-extras, панелью Dock и Центром уведомлений.
Помогает обойти ограничения системной защиты TCC. Если команда возвращает ошибку доступа, скилл запускает сценарий agent-desktop permissions --guide для настройки прав в параметрах системы. Для кликов с зажатыми клавишами, перетаскивания и наведения курсора требует флаг --headed.
Для работы нужен установленный CLI agent-desktop и macOS 13 или новее на процессорах Intel либо Apple Silicon. Без прав доступа Accessibility в настройках системы агент не сможет считывать дерево интерфейса.
Какие задачи решает
- настроить права Accessibility и Screen Recording через системный гид
- прочитать меню приложений и системные значки в строке состояния
- нажимать на элементы окон без потери фокуса через Accessibility API
- управлять уведомлениями macOS с проверкой заголовка и имени программы
Примеры запросов агенту
- Проверь системные разрешения через agent-desktop permissions
- Сделай снимок строки меню приложения через
agent-desktop snapshot --surface menubar - Открой Центр уведомлений и закрой последнее сообщение от Calendar
Как установить agent-desktop-macos
1Через Skills CLI (Vercel)
npx skills add vercel-labs/agent-desktop --skill agent-desktop-macos -a claude-code2Вручную: положить файлы
~/.claude/skills/agent-desktop-macos/SKILL.mdПапка скилла целиком; для одного проекта — .claude/skills/agent-desktop-macos/
1Через Skills CLI (Vercel)
npx skills add vercel-labs/agent-desktop --skill agent-desktop-macos -a codex2Вручную: положить файлы
.agents/skills/agent-desktop-macos/SKILL.mdДля всех проектов — ~/.agents/skills/
1Через Skills CLI (Vercel)
npx skills add vercel-labs/agent-desktop --skill agent-desktop-macos -a cursor2Вручную: положить файлы
.cursor/skills/agent-desktop-macos/SKILL.mdCursor читает и .agents/skills/, и .claude/skills/
1GitHub CLI
gh skill install vercel-labs/agent-desktop skills/agent-desktop-macos2Вручную: положить файлы
.github/skills/agent-desktop-macos/SKILL.md1Через Skills CLI (Vercel)
npx skills add vercel-labs/agent-desktop --skill agent-desktop-macos -a gemini-cli2Командой платформы
gemini skills install https://github.com/vercel-labs/agent-desktop --path skills/agent-desktop-macosВручную: положить файлы
.devin/skills/agent-desktop-macos/SKILL.mdСтарый путь .windsurf/skills/ тоже читается
Через Skills CLI (Vercel)
npx skills add vercel-labs/agent-desktop --skill agent-desktop-macos -a opencodeClaude.ai
Упакуйте папку в zip и загрузите в Settings → Capabilities → Skills
По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов
Вопросы об agent-desktop-macos
Как установить agent-desktop-macos в Claude Code?
Выполните команду npx skills add vercel-labs/agent-desktop --skill agent-desktop-macos -a claude-code. Файл настроек сохранится в ~/.claude/skills/agent-desktop-macos/SKILL.md.
Что делает agent-desktop-macos?
Объясняет агенту специфику управления macOS в CLI agent-desktop: работу с TCC, меню, Electron-приложениями и обработку ошибок недоступности окон.
Что нужно для работы agent-desktop-macos?
Требуются установленный CLI agent-desktop, macOS 13 или новее, а также права Accessibility для запускающего терминала. Запись экрана нужна только для скриншотов.
Исходный текст
SKILL.md · Apache-2.0
--- name: agent-desktop-macos tags: macos-automation, accessibility, ax, tcc, ai-agent, gui-automation, cli requirements: - agent-desktop description: > macOS platform guide for the agent-desktop CLI. Use for desktop automation on macOS: granting Accessibility and Screen Recording permission (TCC), what headed mode does on macOS (physical-first click, type and scroll), surfaces (menu, menubar, sheet, popover, alert, dock, menu-bar-extras), menu bar apps and system panels with no window, Notification Center, Chromium and Electron apps including launch --cdp, and fixing PERM_DENIED, empty accessibility trees, ACTION_FAILED and APP_UNRESPONSIVE. --- # agent-desktop on macOS Read the core skill first (`agent-desktop skills get desktop`) for the observe, act, verify loop. This skill covers only what is different on macOS. When a command fails, find the symptom in [references/troubleshooting.md](references/troubleshooting.md). ## Requirements The sandbox provider on macOS is `macos`: a macOS VM that needs an Apple Silicon Mac, macOS 13 or later on the host and in the guest, and Xcode Command Line Tools. The first setup needs a person in the guest window; clones need none. See `agent-browser.dev/desktop/sandboxes/macos`. - macOS 13 or later, Intel or Apple Silicon. - Accessibility permission for the app that launches agent-desktop (Terminal, iTerm2, Warp, VS Code, Codex). macOS 27 and later name this list Device Control and Data Access. If System Settings lists the `agent-desktop` binary separately, grant it too. - Screen Recording permission, only for `screenshot` and for `session start --screenshots` artifacts. - Automation permission for System Events, only where a command reports it missing. ## First contact 1. Run `agent-desktop permissions`. 2. If a permission is denied, run `agent-desktop permissions --guide`. It opens the right System Settings page with a panel that shows the user which app to drag into the list. The user confirms with Touch ID or a password, and the panel moves to the next missing permission by itself. The command returns at once with `"guide": "started"`, `"already_running"` or `"not_needed"`. `agent-desktop permissions --request` shows the system prompts instead. 3. If the guide cannot run, open System Settings > Privacy & Security > Accessibility (Device Control and Data Access on macOS 27 and later). Add the launching app and turn it on. 4. Run `agent-desktop permissions` to confirm `granted`. The next agent-desktop call sees a new grant, so the launching app does not need a restart. Each command reads permissions in its own process, so a permission granted during a `batch` applies from the next CLI call, not to later items in that batch. 5. Run `agent-desktop snapshot -i` to confirm. It reads the focused app. `snapshot --app Finder -i` returns `WINDOW_NOT_FOUND` when Finder has no open window. `permissions` does not prompt. `permissions --request` can prompt, including for Automation. `permissions --guide` does not prompt and covers Accessibility and Screen Recording only. Automation reports `unknown` when macOS would need to prompt. ## What differs on macOS **Headed actions.** `click`, `right-click`, `type`, `clear` and `scroll` use physical paths first, except a click on an item in the application's native menu bar hierarchy, which calls `AXPress` without moving the pointer. A headless click on these menu items also calls `AXPress`. Process-owned refs have no window to focus; other ref-target pointer actions focus the exact owning window and verify the hit target before delivery. A headless `right-click` can use `AXShowMenu` when the target provides it. `expand`, `collapse`, `set-value`, `select`, `toggle`, `check`, `uncheck`, `focus` and `scroll-to` stay semantic under `--headed`. `double-click`, `triple-click`, `hover` and `drag` need `--headed`. Raw `--xy` input never changes focus. **Judge delivery by observation.** AX return codes do not prove an effect. Finder returns success from an `AXConfirm` that does nothing. Snapshot again or use `get` and `is` to check the result. **Surfaces.** Use `--surface menubar` for an app's File, Edit, and View menus. Use `--surface menu-bar-extras` for status items: with no `--app` it reads system items such as Wi-Fi, Battery, and Clock; with `--app` it reads that app's own item. Use `--surface dock` for the Dock. These shell surfaces are available headless through `open-system-surface`. A background app with no ordinary window, such as a menu-bar app or Control Center, can be observed through its process with `snapshot --app "Control Center"`. This applies to `window`, `menubar`, and `menu-bar-extras`, not `focused`; a regular app that has not shown its window returns `WINDOW_NOT_FOUND`. While a menu, sheet, alert, or popover is open, refs from the window tree behind it are the wrong target. **Menus.** `right-click` headless uses `AXShowMenu`. If the menu opened but the app returned `APP_UNRESPONSIVE` with `retry: unsafe`, do not retry. Inspect the menu with `--surface menu`. `menu` requires an open menu: if `snapshot --surface menu` returns `surface_absent` with `complete: true`, snapshot `menubar` when it exists, click its item without `--headed`, then snapshot `--surface menu`. An absent `menubar` can mean the app exposes no menu bar. A missing `complete`, `complete: false`, timeout or incomplete read is unknown, not absent. For combo boxes and menu buttons, use `select @ref "Option"`. `select` needs a closed-to-open menu transition, so dismiss any open menu first. **Notification Center.** The notification commands drive Notification Center through accessibility, with the rules in the core `commands-system` reference. When agent-desktop opens the center, it closes it afterwards and restores the previous app focus. Pass both `--expected-app` and `--expected-title` on a single dismiss or action, because the stack shifts. Use `wait --notification --app "App"` for banners that vanish before you list them. **Chromium and Electron.** agent-desktop switches on the web accessibility of a Chromium renderer automatically when it needs it. For a dense running app, use `snapshot --skeleton -i --compact`, then drill with `--root @ref`. **Identity.** `launch` accepts a display name (`"System Settings"`) or a bundle ID (`com.apple.systempreferences`). Other commands take the display name through `--app`, or the bundle ID or executable name (`ControlCenter`) when no running app has that display name. Window IDs such as `w-4521` stay valid for the life of the window. Find them with `list-windows`. **Refs use native addresses when available.** A ref turns back into the exact element it was captured from, so identical twins, such as several identical `Delete` buttons, each act on their own row. If the element was removed or the app restarted, the ref is `STALE_REF`, `details.kind: retained_object_stale`, and it never falls back to a search for a look-alike. When an app yields no address for an element, that ref follows the cross-platform rule instead and must have been the only element in its window with its role, native id, name and description. Take a fresh snapshot after a list changes. **Keys.** The primary modifier is `cmd`: `press cmd+c`, `press cmd+s`. Quit shortcuts such as `cmd+q`, `cmd+shift+q`, `cmd+alt+esc`, `ctrl+cmd+q` and `cmd+shift+delete` return `POLICY_DENIED` unless you pass `--force`. To quit an app, use `close-app`. Punctuation keys work in combos, as the symbol (`,` `.` `/` `;` `'` `[` `]` `\` `-` `=` `` ` ``) or by name (`comma`, `period`, `slash`, `semicolon`, `quote`, `leftbracket`, `rightbracket`, `backslash`, `minus`, `equal`, `grave`). Each one is sent with the key that types it in the active keyboard layout, so `press cmd+,` opens Settings on ANSI and JIS keyboards alike. **Cursor overlay.** `cursor-overlay enable` draws the agent cursor in a click-through window. It never moves the OS pointer or activates an app. The macOS motion and image limits are in the core `commands-system` reference.
© vercel-labs · Apache-2.0 · vercel-labs/agent-desktop