How to use the macOS Shortcuts Bridge agent skill

What is an agent skill, and what does this one do?

An agent skill is a folder of instructions and optional scripts that an AI agent loads when a request matches the skill's description. This one, named Shortcuts, bridges the Shortcuts app on macOS into the LifeOS project.

The skill works in two stages. First, a shortcut is built once through on-screen computer use, because the shortcuts command line can run and list shortcuts but cannot create them. Second, the agent calls the finished shortcut through a small TypeScript wrapper around the macOS shortcuts command, which is faster and repeatable compared with clicking through the screen each time.

• Build a shortcut once, for example a thermostat status check.
• Run it later from the terminal with no screen interaction.
• List shortcuts on the machine or check whether a named one exists.

What do you need before installing?

The skill depends on several things on your machine. Check these first so you do not hit an error midway through setup.

• macOS with the built-in shortcuts command at /usr/bin/shortcuts. It does not run on other systems, where the script exits with an error.
• The Bun runtime, which executes Tools/Shortcuts.ts.
• Computer use capability, needed only for the one-time step where a shortcut is built on screen.
• Apple Home or other devices, only if the shortcuts you build control them.

How do you install the Shortcuts skill?

Download the ZIP for this skill from this page and unzip it. You have two places to put the folder, depending on how you use your agent.

For Claude Code, place the skill folder in ~/.claude/skills/ so it applies to all your projects, or in a project's .claude/skills/ folder so it applies only to that project.

In the Claude apps, you can instead upload the ZIP under Settings → Capabilities → Skills.

• Personal install: ~/.claude/skills/
• Project install: .claude/skills/ inside your project folder
• Claude apps: Settings → Capabilities → Skills, then upload the ZIP

How do you check the skill is working?

The skill's own read-only check lists your shortcuts. If it prints a JSON array of shortcut names, the wrapper and the macOS shortcuts command are working. The path below assumes the personal install location.

How do you trigger the skill with natural requests?

You do not need to type commands. Ask in plain language and the agent picks the matching intent from the skill's routing table. Requests that mention building, running, or listing shortcuts are the most reliable triggers.

Building is the only step that uses computer use. Running and listing use the command line only.

• Build: "build a shortcut", "create a shortcut", "set up the X shortcut"
• Run: "run the X shortcut", "invoke X"
• List: "list shortcuts", "what shortcuts exist", "does X exist"

What does a real example look like?

Suppose you ask the agent to build a thermostat status shortcut. The agent builds it once in the Shortcuts app under an exact name. It then reads each thermostat through Home actions and checks the result by running the shortcut, not by looking at the editor.

Later, a script such as a home-control skill can call the same shortcut by its name, passing input on stdin, with no computer use involved. The skill's documentation gives this pattern as the example output: a status line such as "Zone 1 21 heating, Zone 2 20 idle".

• Build the status shortcut once (computer use, one time).
• Run it from the terminal to confirm the output matches what you specified.
• Call it from other scripts by exact name for routine use.

What safety points should you know?

Shortcuts can run real device actions, and the skill's own notes say their effects depend on the shortcut selected. Wrapping an action in a shortcut adds a layer that can control devices with whatever permissions it was granted, so review each shortcut's actions before you run it.

The skill runs scripts (Tools/Shortcuts.ts) but, according to its metadata, does not use the network. It also keeps no per-user data of its own. Shortcut names belong to the tool that calls them, so the calling skill holds its own configuration.

Name matching is exact. A shortcut called "casa set zone 1 temp" will not match a run request for "Casa Set Zone 1 Temp", and a trailing space also breaks the match. Confirm names after building.

• Review each shortcut's actions before running it against real devices.
• Do not use this skill for web pages; the skill directs browser work to a different skill named Interceptor.
• Do not use it for tasks a shell script or device API already handles.

What tips help the skill run reliably?

Most failures come from naming. Register the exact string that consumers expect, and check it with the existence command after building. If a run fails with no clear error, compare the target name against the list output before rebuilding anything.

• Use the exists check to confirm a specific name: Tools/Shortcuts.ts exists "<name>" exits 0 when present and 1 when absent.
• Make sure a shortcut that should return text ends with an output action, otherwise its output comes back empty.
• Shortcut input arrives on stdin, so a shortcut that takes input should read it from Shortcut Input.