How to use the BlueBubbles iMessage Actions agent skill

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

An agent skill is a folder containing a SKILL.md file that gives an AI agent instructions for a specific task. When the agent sees a request that matches the skill's description, it follows those instructions. This skill is named bluebubbles and its description says it is for sending or managing iMessages via BlueBubbles, which the source calls the recommended iMessage integration.

Once installed, the agent can send texts and attachments, add or remove tapback reactions, edit or unsend messages it has sent, reply to a specific message, and send messages with iMessage effects. The skill also tells the agent to ask for a recipient and the exact message text when a request is vague, so it does not guess who to text.

• Send text messages and file attachments
• Add or remove tapback reactions
• Edit or unsend a previously sent message
• Reply to a specific message
• Send a message with an iMessage effect

What you need before you install

The skill cannot work on its own. It needs a BlueBubbles server running on a Mac with iMessage, and a Brigade gateway config that includes channels.bluebubbles with serverUrl, password and webhookPath. It also needs the Brigade message tool, which is how the skill's calls are made.

The skill's files are a single SKILL.md. Per its metadata, it does not run scripts, but it does use the network to reach your BlueBubbles server.

• A BlueBubbles server running on a Mac signed in to iMessage
• Gateway config with channels.bluebubbles (serverUrl, password, webhookPath)
• The Brigade message tool

Install the BlueBubbles skill

Download the ZIP for the skill from this page and unzip it. For a personal setup, place the unzipped bluebubbles folder in ~/.claude/skills/. For a single project, place it in that project's .claude/skills/ folder instead.

If you use the Claude apps, you can instead upload the skill under Settings → Capabilities → Skills.

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

Ask the agent for iMessage actions

You do not need special syntax. Describe what you want in plain language, and include the recipient and exact message text. The skill works best when the target is a phone number in E.164 format such as +15551234567, an email address, or a chat GUID. For group chats, the source says chat GUID targets are preferred.

If your request is vague, such as 'text my mom', the agent is instructed to ask you for the recipient handle or chat GUID and the exact message content before sending.

• Good: 'Text +15551234567 and say I am running 10 minutes late.'
• Good: 'Send the photo at /tmp/photo.jpg to +15551234567 with the note here you go.'
• Good: 'React with a heart to the message with ID <message-guid> in my chat with +15551234567.'
• Vague: 'Text my mom' (the agent should ask who and what to say)

Examples of each action

The skill's reference shows the request structure the agent sends through the message tool. Each action uses channel set to bluebubbles. Message IDs are placeholders you would replace with real values.

For removing a tapback, the same react action is used with remove set to true. For attachments, the skill uses a local file path. Use message for the text you want to show, because the source does not treat caption as a separate BlueBubbles feature.

Safety and limits to know

Treat this skill as something that acts on real conversations. The agent may send to the wrong contact if the target is ambiguous, so confirm recipients, especially for anything important. Avoid unattended use for sensitive or irreversible messages.

Some actions depend on macOS version. The source notes that edit may be broken on macOS 26 Tahoe, so test before relying on it. Text sent with media may arrive as a separate message rather than a captioned bubble, so do not promise exact caption layout.

On the security side, the skill runs no scripts but uses the network to talk to your BlueBubbles server. Keep your server password and gateway config private.

• Confirm the recipient before sending
• Test edit and unsend on your macOS version first
• Expect attachments and text to arrive as separate messages
• Do not rely on caption as a guaranteed feature

Tips for reliable results

Prefer chat GUID targets when you have them, especially for group chats. Full message IDs are more durable across restarts than short ones, so use the full form when you can. The source also suggests reacting with a tapback to acknowledge a request, and replying in-thread when a user refers to a specific message.

For developers, the source points to the BlueBubbles plugin package README as the reference for the underlying plugin.

• Use chat_guid targets for group chats
• Use full message IDs for durability
• Acknowledge requests with a tapback
• Reply in-thread when a message is referenced