Skip to content
Get packs

Guide · Agent skill

How to use the add-whatsapp agent skill for WhatsApp channels

Updated · written with AI from the project's own documentation and checked against our catalogue data

The add-whatsapp skill is a set of instructions that lets an AI agent add WhatsApp as a messaging channel for NanoClaw, an agent framework. It is for developers who already run NanoClaw and want the agent reachable over WhatsApp. By the end of this guide you will know what the skill does, how to install it, how to start it with a plain request, and what to check before you link a number.

WhatsApp Channel Setupnanocoai/nanoclaw · MIT

Quick start

  1. 1Decide on the number type. Choose a dedicated number, which is recommended. If you choose a shared number, read the warning and confirm before continuing.
  2. 2Install the skill. Download the ZIP, then unzip it into ~/.claude/skills/ or your project's .claude/skills/ folder, or upload it under Settings, Capabilities, Skills in the Claude apps.
  3. 3Ask the agent to add WhatsApp. Make a plain request such as adding WhatsApp as a channel to your NanoClaw agent. The agent follows the skill steps.
  4. 4Link the device. Choose QR or pairing code, then follow the on-screen instructions in WhatsApp under Linked Devices.
  5. 5Run the build and test. Let the agent run the build and the registration test, and confirm they pass before using the channel.

What the add-whatsapp skill makes the agent do

Agent skills are folders of instructions that an AI agent reads and follows for a specific task. This skill covers one task: connecting WhatsApp to NanoClaw. NanoClaw does not include channels in its main code, so the skill copies a WhatsApp adapter in from the channels branch of the nanocoai/nanoclaw repository.

The adapter connects directly to WhatsApp Web using the Baileys library. The skill does not use a Chat SDK bridge. After copying the adapter, the agent registers it, installs the WhatsApp client packages at pinned versions, builds the project, and runs a registration test.

  • Asks whether you will use a dedicated or shared WhatsApp number before installing anything
  • Copies the adapter, its registration test and a WhatsApp formatting skill for agents
  • Links your WhatsApp account by QR code or pairing code
  • Runs a build and one integration test

Install the add-whatsapp skill

Download the skill ZIP from the directory page. Then choose one of two locations. For a skill available to all your projects, unzip it into ~/.claude/skills/. For a skill available only to one project, unzip it into that project's .claude/skills/ folder.

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

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

Trigger the skill with a natural request

You do not need a special command. Describe what you want in plain language and the agent should match the request to the skill's description, which says it adds a WhatsApp channel through a native Baileys adapter. Requests such as the ones below are reasonable starting points.

The first thing the skill does is ask which kind of number NanoClaw will use. Answer that question before expecting installation to start.

  • Add WhatsApp as a channel to my NanoClaw agent.
  • Set up WhatsApp so people can message my NanoClaw agent.
  • Link a WhatsApp number to NanoClaw using a QR code.

Choose a dedicated number or accept the shared-number risk

Use a dedicated number when you can. The skill recommends a separate number used only for NanoClaw, such as a spare SIM, an eSIM or an old phone. If you say you want to use your shared, personal, main, existing or everyday number, the skill shows a warning first.

On a personal number, the agent only lives in your self-chat. Messages from other people are ignored, so nobody else can reach the agent. The warning also says connecting a shared number could lead WhatsApp to suspend or permanently ban it. You will lose access to the chats and groups you rely on if that happens.

  • Dedicated (recommended): a separate number used only for the agent
  • Shared: your everyday number; the skill asks you to confirm the risk before continuing
  • Other options named by the skill: Telegram, or the official Meta Business API skill (/add-whatsapp-cloud)

Link your phone with a QR code or pairing code

The skill asks you to pick a linking method. With QR, a rotating code appears in your terminal. On your phone, open WhatsApp, go to Settings, then Linked Devices, then Link a Device, and scan the code with your camera.

With a pairing code, you enter your phone number with the country code first and no plus sign, spaces or dashes, for example 14155551234 for a US number. An 8-character code then appears in the terminal. On your phone, choose Link with phone number instead and enter the code quickly, because it expires after about 60 seconds. The skill then reports the linked number.

  • QR: scan the rotating code shown in this terminal
  • Pairing code: type the 8-character code on your phone before it expires
  • Credentials are stored in store/auth/creds.json once linking succeeds
pnpm exec tsx setup/index.ts --step whatsapp-auth -- --method qr

Build, test and confirm the channel works

After the packages are installed, the skill runs a build. The build checks the adapter against the core code and confirms the dependencies are present. Then it runs one integration test, which checks that the WhatsApp channel is registered.

The test does not confirm message delivery. The skill says end-to-end delivery against a real WhatsApp number is checked manually once the service runs.

  • Build check: confirms the adapter typechecks and dependencies install
  • Registration test: fails if the import line is removed or the Baileys package is missing
pnpm run build pnpm exec vitest run src/channels/whatsapp-registration.test.ts

Safety notes: scripts, network and removal

This skill runs scripts and uses the network. It installs pinned npm packages, including Baileys, which is the WhatsApp Web client, and it connects to WhatsApp to link your account. The package versions are fixed so that ranges and latest tags are not used. Review the files before you run it if your project has its own policy.

The package includes an optional helper, scripts/wa-qr-browser.ts, which shows the QR code on a local browser page. The package also includes REMOVE.md, which lists how to take out the adapter, its tests, the formatting skill and the setup step. Those removal steps are designed to be safe to repeat.

  • Runs scripts: yes
  • Uses network: yes
  • Optional local QR page: scripts/wa-qr-browser.ts
  • Removal instructions: REMOVE.md

What people use it for

  • Letting users message a NanoClaw agent through a WhatsApp number you have dedicated to it
  • Testing a NanoClaw agent over WhatsApp before deciding whether to use a business messaging API
  • Giving a developer a working WhatsApp channel in a local NanoClaw install without a phone camera, using the pairing code method

Frequently asked questions

What do I need before installing the add-whatsapp skill?

You need a NanoClaw repository with pnpm and Node tooling, access to the channels branch of nanocoai/nanoclaw, and a phone with WhatsApp to link as a companion device. The steps assume you are comfortable with a terminal.

Is the add-whatsapp skill free?

The skill is published under the MIT licence. The source does not state any cost for WhatsApp itself, so check WhatsApp's own terms for any charges that apply to your account.

Can I use my personal WhatsApp number with this skill?

The skill allows it but warns against it. WhatsApp may suspend or ban a shared or personal number, and on that number the agent only works in your self-chat. A dedicated spare number is the recommended choice.

What should I use instead if I want a business WhatsApp integration?

The skill itself points to the official Meta Business API skill, invoked as /add-whatsapp-cloud, for production business messaging. Telegram is also suggested as a way to make the agent reachable as its own contact.

What if the pairing code expires or linking fails?

The skill says a failed handshake, shown as logged_out or a timeout, usually means the code expired. Run the linking step again and enter the new code on your phone within about 60 seconds.

Does the skill work without a NanoClaw install?

No. The skill adds WhatsApp to an existing NanoClaw project and depends on its build tooling. It is not meant for non-technical users without a working NanoClaw setup.

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 run NanoClaw as a developer and want your agent reachable over WhatsApp from a dedicated number you can afford to lose. Skip it if you want to connect your everyday number, if you lack a working NanoClaw install, or if you need production business messaging, where the official Meta Business API skill is the better fit.

Download the skill