How to use the WhatsApp Router agent skill (wacrawl and wacli)

What the WhatsApp skill makes the agent do

The skill is described as the first stop for WhatsApp work. It separates two sources. wacrawl handles the primary WhatsApp Desktop archive: it is read-only, works from local history, and does not use the network or send messages. wacli handles linked-device accounts, which is where alternate accounts, live sync, authentication, sending, and chat or group changes happen.

When you ask about WhatsApp, the agent is expected to pick the right tool for the job, check data freshness, and tell you which account and source an answer came from.

• Searching, reading, and reviewing history from the Desktop archive uses wacrawl.
• Alternate accounts and named stores use wacli with an account name.
• Sending, reactions, and group or chat changes use wacli, and only after you explicitly ask.

How do you install the WhatsApp skill?

Download the skill ZIP from the page where you found this guide. Then choose one of two install locations.

For a personal setup, unzip the file into ~/.claude/skills/. For a single project, unzip it into that project's .claude/skills/ folder. You can also upload the ZIP in the Claude apps under Settings, then Capabilities, then Skills.

The skill package contains one file, SKILL.md. The command-line tools wacrawl and wacli are separate and are not included in the skill, so install them before you rely on the skill.

Install the wacrawl and wacli tools

The skill only routes requests to these tools. It does not provide them. The source does not include installation steps for either tool, so follow each tool's own documentation.

You also need access to WhatsApp Desktop local data for wacrawl, and to your linked-device accounts for wacli. tmux is recommended if you want wacli follow-mode live sync to keep running in the background.

• wacrawl: WhatsApp Desktop archive importer and search tool.
• wacli: linked-device WhatsApp client for sync, sending, and auth.
• tmux: recommended for follow-mode live sync.

How to trigger the skill with natural requests

You do not need special syntax. Ask for what you want in plain language, and the agent should load the skill when the request is about WhatsApp. Name an account if you have more than one, so the agent uses the right store.

Good requests state the source, the scope, and the action. For example, ask for unread chats, a search for a phrase after a certain date, or a comparison between the Desktop archive and a linked account.

• Show my unread WhatsApp chats from the last day.
• Search my WhatsApp history for messages about the lease, from them only.
• Check whether my alt account has messages from this week that the Desktop archive is missing.
• Send a reply to this chat, but only after you confirm the exact text.

Example commands the skill uses

The skill lists the commands the agent is likely to run. Read-only commands come first. Check freshness before you rely on primary archive results.

Use these as a reference for what the agent does. You do not need to type them yourself.

• Freshness: wacrawl status, then wacrawl sync only when asked or when current data matters.
• Unread triage: wacrawl unread --limit 20.
• Search: wacrawl --json search "query".
• Alternate account, read-only: wacli --account me chats list --read-only --json.
• Live sync in the background, only when requested: wacli --account me sync --follow --events.

What safety rules does the skill enforce?

The skill sets firm limits. The agent should never send messages or change WhatsApp state unless you explicitly ask. It should prefer read-only modes for wacli, using the --read-only flag or the WACLI_READONLY=1 setting. It should not write into the WhatsApp Desktop app container or edit wacli's session.db directly, and it should keep named accounts separate instead of merging their stores.

The skill also requires the agent to report source freshness, the account name, and known gaps in local data. Be aware that the skill runs scripts and uses the network, and that the commands expose full message content, so the agent will read whatever chats it is asked to search.

• Sending, reactions, presence, archive, pin, mute, mark-read, and group changes need explicit intent.
• Read-only mode is the default posture for inspection.
• Reading personal chat history is exposed to the agent, so limit its use to chats you want it to see.

Tips for better results

Name the account when you have several, and say whether you want the Desktop archive or a linked-device store. When you compare sources, ask for counts, date spans, newest timestamps, and overlap, since the skill is set up to report those.

If an answer looks incomplete, ask the agent about known gaps. Linked-device history limits and Desktop archive coverage can differ, and the skill treats those differences as expected.

• Ask for the newest message timestamp to judge how fresh the data is.
• Ask for overlap by message ID when comparing wacrawl and wacli.
• Keep sending requests specific, including the recipient and exact text.