Guide · Agent skill

How to use the Add Matrix Channel agent skill

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

The add-matrix skill connects a NanoClaw assistant to Matrix, the open chat network, so people can message the bot in rooms or direct messages from clients such as Element. This guide explains what the skill changes in your project, how to install the skill, how to ask for it in plain language, and what you need before you start. By the end you will know how to set up a separate Matrix bot account and what to check if it does not respond.

Add Matrix Channelnanocoai/nanoclaw · MIT Download the skill

Quick start

1Download and unzip the skill. Download the ZIP from this page and unzip it into ~/.claude/skills/ or a project's .claude/skills/ folder, or upload it under Settings → Capabilities → Skills.
2Ask the agent to add Matrix. Describe the goal in plain language, such as connecting NanoClaw to Matrix. The agent applies the skill's steps: copy the adapter, register it, install the pinned package, then build and test.
3Create a bot account. Register a separate Matrix account for the bot in Element using a private window, and note its full user ID such as @andybot:matrix.org.
4Choose a login method. Use either a username and password (Option A) or an access token from Element or the login API (Option B).
5Save credentials. Answer the prompts for the homeserver URL, user ID, display name and your chosen login values so they are written to .env.
6Wire the channel. Run /manage-channels to connect the Matrix channel to an agent group.
7Test in Element. Invite the bot to a room from your own account, watch the service log for the join, then send a message to check the reply.

What the add-matrix skill does

Agent skills are folders of instructions that an AI agent can read and follow to carry out a specific task. This skill adds Matrix chat as a way to talk to a NanoClaw assistant. NanoClaw does not ship channels in its main code, so the skill copies the Matrix adapter in from the channels branch of the repository.

The skill applies its changes in order: it copies the adapter and a registration test into src/channels/, adds one import line to the channel barrel src/channels/index.ts, registers a pnpm patch, installs the pinned @beeper/chat-adapter-matrix package at version 0.2.0, and then builds and tests the project. After that, it walks you through creating a separate Matrix bot account and saving its login details to the configuration.

Copies src/channels/matrix.ts and src/channels/matrix-registration.test.ts
Adds the import './matrix.js'; line to src/channels/index.ts
Installs @beeper/chat-adapter-matrix@0.2.0 with an exact pin
Runs the build and tests, then guides credential setup

Install the add-matrix skill

Download the skill ZIP from this page and unzip it into one of these locations. Use ~/.claude/skills/ to make the skill available for all your projects, or use the .claude/skills/ folder inside a single project to limit it to that project.

If you use the Claude apps instead, open Settings, go to Capabilities, then Skills, and upload the ZIP there.

Personal: ~/.claude/skills/
Single project: .claude/skills/ inside your NanoClaw project
Claude apps: Settings → Capabilities → Skills, then upload the ZIP

Check what you need before you start

The skill assumes a working NanoClaw project that uses pnpm and Node 22 or a compatible version. You also need a Matrix account for the bot on a homeserver such as matrix.org, and either a username and password or an access token for that account.

The skill runs scripts and uses the network: it runs pnpm and node commands and fetches the adapter package and the channels branch. Read SKILL.md and the files in the skill folder if you want to see every command before the agent runs it.

NanoClaw project with pnpm and Node 22 or compatible
A dedicated Matrix account for the bot
Username and password, or an access token
Network access to fetch the package and branch

Trigger the skill with a natural request

You do not need a special command to use the skill. Once it is installed, ask your agent in plain language to add Matrix as a channel, and it should pick up the skill from its description. If you are inside the NanoClaw setup flow, the skill's Next Steps section tells the agent to return to setup when it finishes.

After the bot is running, use the NanoClaw command the skill names to wire the channel to an agent group.

"Add Matrix as a channel for my NanoClaw assistant."
"Connect NanoClaw to Matrix so I can message it from Element."
"Set up the Matrix channel using a bot account on matrix.org."

/manage-channels

The bot needs its own Matrix account, separate from yours, because Matrix cannot send direct messages to yourself. Register the account in Element in a private window, note its full user ID such as @andybot:matrix.org, and then pick one login method.

Option A uses the bot's username and password, which the adapter uses to log in automatically. Option B uses an access token, which the skill describes as recommended for production. You can get a token from Element under Settings, Help & About, Access Token, or from the login API.

Option A: MATRIX_USERNAME and MATRIX_PASSWORD (the username is the bare localpart)
Option B: MATRIX_ACCESS_TOKEN, taken from Element or the login API
Both options also need MATRIX_BASE_URL, MATRIX_USER_ID and MATRIX_BOT_USERNAME

MATRIX_BASE_URL=https://matrix.org
MATRIX_ACCESS_TOKEN=your-access-token
MATRIX_USER_ID=@andybot:matrix.org
MATRIX_BOT_USERNAME=Andy

Store the credentials and optional settings

The skill asks you for the homeserver URL, the bot's user ID, a display name, and then the login values for the method you chose. It writes them to the project's .env file. Only fill in the block that matches your chosen method.

Optional settings control invite handling and encryption. By default the bot auto-accepts room invites. An allowlist limits which users can invite it. A recovery key enables end-to-end encryption cross-signing, and a device ID keeps the same device identity across restarts.

MATRIX_INVITE_AUTOJOIN=true (default true)
MATRIX_INVITE_AUTOJOIN_ALLOWLIST to accept invites only from listed users
MATRIX_RECOVERY_KEY to enable E2EE cross-signing
MATRIX_DEVICE_ID for a stable device ID across restarts

MATRIX_INVITE_AUTOJOIN=true
MATRIX_INVITE_AUTOJOIN_ALLOWLIST=@you:matrix.org
MATRIX_DEVICE_ID=NANOCLAW01

Fix common problems

If the build fails with ERR_MODULE_NOT_FOUND for matrix-js-sdk, the ESM patch is missing, often because a later pnpm install removed it. Re-run the patch and then pnpm run build; the skill notes that re-running the patch is safe.

If login fails with M_FORBIDDEN, check that MATRIX_USERNAME is the bare localpart and MATRIX_USER_ID is the full ID. An access token stops working when its Element session signs out, so get a new one. If the bot never joins your room, check the allowlist, because an allowlist that leaves out your user ID causes the bot to ignore your invites.

What people use it for

Messaging a NanoClaw assistant from Element on a phone or desktop
Talking to the bot in a private direct message on a matrix.org account
Using one Matrix room for a shared group chat with the assistant
Keeping a separate agent group for rooms tied to different communities or sensitive topics

Frequently asked questions

Is the add-matrix skill free?

The skill is published under the MIT licence, as stated on this page. Check the licence file in the repository for the full terms before you reuse or redistribute it.

What do I need to install the add-matrix skill?

You need a NanoClaw project that uses pnpm and Node 22 or compatible, a Matrix account for the bot, and either a username and password or an access token. The skill also needs network access to fetch the adapter package and the channels branch.

Can I use any Matrix server with this skill?

The skill description says it works with any Matrix homeserver. The examples use matrix.org, so change MATRIX_BASE_URL to your server's address when you use another homeserver.

Why does the bot need its own account?

Matrix cannot send direct messages to yourself, and the channel's typical use requires a separate bot account because the agent cannot DM users from their own account.

Do threads work with the Matrix channel?

Thread support is partial. Some clients support threads but not all, so the skill treats threads as unsupported for reliability. Do not rely on threaded conversations for critical work.

How do I remove the skill and its changes?

The REMOVE.md file in the skill describes the removal steps: delete the import line from src/channels/index.ts, delete the copied adapter and test files, remove the Matrix variables from .env, uninstall the package and remove the patch, then rebuild and restart the service.

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 and want your assistant reachable from Matrix or Element, and you are comfortable creating a separate bot account and storing its password or access token locally. Pick another channel if you need reliable threaded conversations or do not want to keep bot credentials on your machine.

Download the skill