matrix-communication

Category: Tools & Productivity | Uploader: netresearch | Downloads: 0 | Version: v1.0（Latest）

Use when sending messages to Matrix rooms, interacting with Matrix chat, or automating team notifications via Matrix protocol.

Changelog: Source: GitHub https://github.com/netresearch/matrix-skill

Directory Structure

Current level: skills/matrix-communication/

📁 references/
- 📄 api-reference.md 3.3 KB
- 📄 e2ee-guide.md 8.1 KB
- 📄 messaging-guide.md 6.5 KB
- 📄 setup-guide.md 5.3 KB
📁 scripts/
- 📁 _lib/
  - 📄 __init__.py 1.6 KB
  - 📄 config.py 1.5 KB
  - 📄 e2ee.py 2.0 KB
  - 📄 formatting.py 8.8 KB
  - 📄 http.py 2.7 KB
  - 📄 rooms.py 4.6 KB
  - 📄 utils.py 1.5 KB
- 📄 matrix-doctor.py 9.0 KB
- 📄 matrix-e2ee-setup.py 8.2 KB
- 📄 matrix-e2ee-verify.py 21.3 KB
- 📄 matrix-edit-e2ee.py 8.6 KB
- 📄 matrix-edit.py 5.0 KB
- 📄 matrix-fetch-keys.py 8.4 KB
- 📄 matrix-key-backup.py 14.7 KB
- 📄 matrix-react.py 4.2 KB
- 📄 matrix-read-e2ee.py 13.2 KB
- 📄 matrix-read.py 4.5 KB
- 📄 matrix-redact.py 4.2 KB
- 📄 matrix-resolve.py 1.4 KB
- 📄 matrix-rooms.py 3.3 KB
- 📄 matrix-send-e2ee.py 15.9 KB
- 📄 matrix-send.py 8.2 KB
📄 LICENSE 13 B
📄 README.md 2.1 KB
📄 SKILL.md 3.9 KB

SKILL.md

---
name: matrix-communication
description: "Use when sending messages to Matrix rooms, interacting with Matrix chat, or automating team notifications via Matrix protocol."
---

# Matrix 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

```bash
# 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

# Fetch missing keys from other devices
uv run skills/matrix-communication/scripts/matrix-fetch-keys.py room-name --sync-time 60

# Restore keys from server backup (decrypt old messages)
uv run skills/matrix-communication/scripts/matrix-key-backup.py --recovery-key "EsTj ..." --import-keys

# 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: `matrix-rooms.py`, `matrix-resolve.py`, `matrix-e2ee-setup.py`, `matrix-e2ee-verify.py`, `matrix-fetch-keys.py`, `matrix-key-backup.py`.

## 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 |

## E2EE Notes

- First run slow (~5-10s) due to key sync. `[Unable to decrypt]` = missing keys, recoverable via key backup
- Use `--json` for programmatic analysis; reactions are `m.reaction` events (see `references/messaging-guide.md`)
- Verify with Element Desktop/Android (not Element X). Use `--timeout 180` for verification

## 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 |

## References

- `references/setup-guide.md` -- Setup walkthrough
- `references/e2ee-guide.md` -- E2EE details, key recovery, verification
- `references/messaging-guide.md` -- Formatting, reactions, common patterns
- `references/api-reference.md` -- Matrix API endpoints
- Source: [netresearch/matrix-skill](https://github.com/netresearch/matrix-skill)

Comments 0

Latest | Hot

Please login before commenting.

No comments yet. Be the first one!

matrix-communication

Directory Structure

SKILL.md

Report

Notice