Guide · Agent skill
How to use the iMessage Setup Check agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The iMessage Setup Check skill is an agent skill for Claude that checks whether your assistant can read iMessage on a Mac and shows who is allowed to message it. It is meant for Mac users who have connected iMessage to Claude and want to confirm it works, or who want to know why texts are not getting through. By the end of this guide you will know how to install the skill, how to ask for it in plain language, and how to read its results.
iMessage Setup Checkanthropics/claude-plugins-official · Apache-2.0 Download the skill Quick start
- 1Download and unzip the skill. Download the ZIP from this page and unzip it, which gives you a folder containing SKILL.md.
- 2Place the folder. Move the folder into ~/.claude/skills/ for all projects, or into a project's .claude/skills/ folder. In the Claude apps, upload it under Settings → Capabilities → Skills instead.
- 3Check Full Disk Access. Make sure your terminal or IDE has Full Disk Access under System Settings → Privacy & Security.
- 4Ask for a setup check. Ask Claude something like "how do I set this up" or "who can reach me" to trigger the skill.
- 5Review the access report. Read the Full Disk Access status, DM policy, and allowed senders the skill reports.
- 6Add trusted contacts. If you want others to reach the assistant, use /imessage:access allow with each handle they use.
- 7Send a self-chat test. Text yourself from a device signed into your Apple ID to confirm messages reach the assistant.
What is an agent skill and what does this one do?
An agent skill is a folder containing a SKILL.md file with instructions that Claude can load when a request matches the skill's description. This one is named configure and belongs to the iMessage channel plugin.
When it runs, it checks whether macOS Full Disk Access is granted by listing the Messages database file (~/Library/Messages/chat.db). It then reads the access settings file at ~/.claude/channels/imessage/access.json, reports the current policy and allowed senders, and ends with a concrete next step.
- Full Disk Access: confirms whether the assistant can read chat.db, and gives the System Settings path to fix it if not.
- Access policy: shows the DM policy, the list of allowed senders, and any pending pairings.
- Next step: tells you what to do based on what it found.
Install the iMessage Setup Check skill
Download the ZIP for this skill from this page and unzip it. Then put the resulting skill folder in one of two places: ~/.claude/skills/ to make it available everywhere, or a project's .claude/skills/ folder to limit it to that project.
If you use the Claude apps instead, open Settings, go to Capabilities, and upload the skill under Skills.
- Personal install: ~/.claude/skills/
- Project install: .claude/skills/ inside your project folder
- Claude apps: Settings → Capabilities → Skills, then upload
Grant Full Disk Access on your Mac
The skill can only read your messages if the terminal or IDE running Claude Code has Full Disk Access. If the check fails with "Operation not permitted", this is the missing piece.
Open System Settings → Privacy & Security → Full Disk Access and turn on your terminal app, or your IDE if that is where Claude Code runs. Granting this access gives the assistant broad read access to all messages in your personal database, so read the safety section below before you do it.
Trigger the skill with natural requests
You do not need to type a command to start the skill. Ask in plain language. The skill's description matches requests such as asking to configure iMessage, asking "how do I set this up", asking "who can reach me", or asking why texts are not reaching the assistant.
To change the allowlist, the skill points you to the /imessage:access command, for example /imessage:access allow +15551234567 to let one number through.
- "How do I set up iMessage with you?"
- "Who can reach me through iMessage right now?"
- "My texts aren't reaching the assistant. Why?"
- "Configure iMessage."
Build your allowlist instead of pairing
The skill recommends an allowlist of trusted contacts rather than pairing. Pairing auto-replies a code to every contact who texts the Mac, so the skill will flag a pairing policy and offer to switch back to allowlist. Handles are phone numbers like +15551234567 or email addresses like someone@icloud.com.
Self-chat always works, meaning messages you send to yourself from a device signed into your Apple ID. The disabled policy drops everything except self-chat. Changes to access.json take effect on the next inbound message without restarting.
- allowlist (default): only listed handles plus self-chat get through
- pairing: auto-replies a code to every new sender; use only for a dedicated line with few contacts
- disabled: drops everything except self-chat
/imessage:access allow +15551234567What people use it for
- Confirming that a newly connected Mac can read iMessage before relying on it.
- Adding a partner or friend to the allowlist with a single phone number or email address.
- Finding out why texts from a contact are not reaching the assistant, such as a missing Full Disk Access grant.
- Switching a pairing policy back to allowlist after realising unknown contacts were getting auto-replies.
Frequently asked questions
How do I install the iMessage Setup Check skill?
Download the ZIP from this page and unzip it. Put the folder in ~/.claude/skills/ for personal use or in a project's .claude/skills/ folder, or upload it in the Claude apps under Settings → Capabilities → Skills.
What do I need to use this skill?
You need a Mac with Messages signed into an Apple ID, Full Disk Access granted to the terminal or IDE running Claude Code, and the iMessage channel plugin with its /imessage:access command. The skill does not run scripts and does not use the network.
Does this skill work on Windows or Linux?
No. It depends on macOS paths such as ~/Library/Messages/chat.db and on macOS Full Disk Access, so it will not work on Windows or Linux.
Is the iMessage Setup Check skill free?
The source is licensed under Apache-2.0. Check the license file in the skill's repository for the full terms.
Why won't my texts reach the assistant?
The most common cause the skill checks for is missing Full Disk Access, which shows as "Operation not permitted" when it lists chat.db. The skill also shows your DM policy and allowed senders, since a sender not on the allowlist will not get through unless it is self-chat.
Is it safe to give Claude Full Disk Access for iMessage?
Full Disk Access lets the assistant read the full personal message database, so anyone who shares the Mac could have their messages exposed. Use it only on a Mac you personally control, and avoid shared or work Macs.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use this skill if you are on a Mac, have connected iMessage to Claude, and want a clear check of Full Disk Access and who can message your assistant. Skip it if you use Windows or Linux, or if you share the Mac with others whose personal messages you would not want the assistant to read.
Download the skill