matrix-communication
npx machina-cli add skill netresearch/matrix-skill/matrix-communication --openclawMatrix Communication
Send messages to Matrix chat rooms on behalf of users.
When to Use
Automatically activate when you encounter:
- Room references:
#room:server,!roomid:server - Chat requests: "send to matrix", "post in chat", "notify the team"
- Matrix URLs:
https://matrix.*/,https://element.*/ - Setup requests: "configure matrix", "set up matrix skill"
Quick Reference
# Send message (E2EE preferred)
uv run skills/matrix-communication/scripts/matrix-send-e2ee.py room-name "Hello!"
# Send by room alias
uv run skills/matrix-communication/scripts/matrix-send-e2ee.py "#room:server" "Hello!"
# List joined rooms
uv run skills/matrix-communication/scripts/matrix-rooms.py
# Read recent messages (E2EE)
uv run skills/matrix-communication/scripts/matrix-read-e2ee.py room-name --limit 10
# React to a message
uv run skills/matrix-communication/scripts/matrix-react.py room-name '$eventId' "✅"
# Thread reply
uv run skills/matrix-communication/scripts/matrix-send-e2ee.py room-name "Update" --thread '$rootEventId'
# Emote message (like /me)
uv run skills/matrix-communication/scripts/matrix-send-e2ee.py room-name "is deploying" --emote
# Health check / auto-install deps
python3 skills/matrix-communication/scripts/matrix-doctor.py --install
Scripts Overview
Always prefer E2EE scripts (*-e2ee.py) -- most Matrix rooms are encrypted.
| Operation | E2EE Script (preferred) | Non-E2EE Fallback |
|---|---|---|
| Send message | matrix-send-e2ee.py | matrix-send.py |
| Read messages | matrix-read-e2ee.py | matrix-read.py |
| Edit message | matrix-edit-e2ee.py | matrix-edit.py |
| React | matrix-react.py | (same) |
| Redact | matrix-redact.py | (same) |
Other scripts: matrix-rooms.py (list rooms), matrix-resolve.py (alias lookup), matrix-e2ee-setup.py (one-time device setup), matrix-e2ee-verify.py (device verification), matrix-fetch-keys.py / matrix-key-backup.py (key recovery).
Room Identification
| Format | Example | Description |
|---|---|---|
| Room name | agent-work | Easiest -- matched from joined rooms |
| Room ID | !sZBo...Q22E | Direct, from matrix-rooms.py output |
| Room alias | #room:server | Resolved via Matrix directory |
Config
File: ~/.config/matrix/config.json
| Field | Required | Description |
|---|---|---|
homeserver | Yes | Matrix server URL |
user_id | Yes | Full Matrix user ID (@user:server) |
bot_prefix | No | Prefix for messages (e.g., bot emoji) |
access_token | No | Auto-created by E2EE setup |
Error Handling
| Error | Solution |
|---|---|
M_FORBIDDEN | Join room first in Element |
M_UNKNOWN_TOKEN | Get new token from Element |
Could not find room | Use matrix-rooms.py to list available rooms |
Multiple matches | Use more specific name or room ID |
Source & Contributing
- Source repository: netresearch/matrix-skill
- Distributed via: netresearch/claude-code-marketplace
- Issues & PRs: File at the source repository, not the marketplace
References
references/setup-guide.md-- Full setup walkthrough (homeserver discovery, E2EE device creation, verification)references/e2ee-guide.md-- E2EE details, key recovery, device verification workflowreferences/messaging-guide.md-- Formatting, reactions, visual effects, common patternsreferences/api-reference.md-- Matrix API endpoints
Source
git clone https://github.com/netresearch/matrix-skill/blob/main/skills/matrix-communication/SKILL.mdView on GitHub Overview
Matrix Communication lets you send messages to Matrix chat rooms on behalf of users and automate team notifications via Matrix protocol. It supports actions like sending, reading, reacting, and threading using E2EE-enabled scripts, with config stored at ~/.config/matrix/config.json.
How This Skill Works
This skill uses dedicated Python scripts to perform Matrix actions from your environment. The recommended E2EE-enabled scripts (matrix-send-e2ee.py, matrix-read-e2ee.py, matrix-react.py, etc.) are preferred for encrypted rooms, with non-E2EE fallbacks available if needed. Rooms can be identified by name, ID, or alias, and credentials are read from a local config file at ~/.config/matrix/config.json (homeserver, user_id, bot_prefix, access_token).
When to Use It
- Post to a Matrix room by name or alias (e.g., #room:server or !roomid:server).
- Handle chat requests like 'send to matrix', 'notify the team', or automation triggers.
- Open or follow Matrix URLs or Element domains to trigger messages or actions.
- Configure or set up Matrix integration for your workspace using the matrix setup tools.
- Read recent messages, react to a message, or send threaded replies to maintain context.
Quick Start
- Step 1: Run health check and install deps: python3 skills/matrix-communication/scripts/matrix-doctor.py --install
- Step 2: List your joined rooms: uv run skills/matrix-communication/scripts/matrix-rooms.py
- Step 3: Send a message (E2EE preferred): uv run skills/matrix-communication/scripts/matrix-send-e2ee.py room-name "Hello!"
Best Practices
- Prefer E2EE scripts (matrix-send-e2ee.py, matrix-read-e2ee.py, etc.) whenever possible.
- Use explicit room identifiers (name, alias, or room ID) and verify with matrix-rooms.py.
- List joined rooms before sending to confirm availability and permissions.
- Use thread replies (via --thread) and emotes (via --emote) to preserve context and tone.
- Run matrix-doctor.py --install to ensure dependencies and a healthy environment.
Example Use Cases
- Send a daily standup summary to #team:server.
- Notify a channel about a successful or failed deployment (e.g., #dev-notifications).
- React with a checkmark to confirm a task completion message.
- Post a threaded update to an existing event using a root event ID.
- Read the last 10 messages in a room to extract context before replying.
