Skip to content

netresearch/matrix-skill / skills/matrix-communication

matrix-communication

Flagged

Use when communicating via Matrix chat, notifying teams, or managing E2EE. Triggers on #room:server references, Matrix URLs, and chat requests.

FileKindSize
README.mdmarkdown2.9 KB
SKILL.mdskill md6.7 KB
evals/evals.jsonconfig12.6 KB
references/agent-governance.mdmarkdown2.0 KB
references/api-reference.mdmarkdown7.3 KB
references/command-reference.mdmarkdown8.9 KB
references/e2ee-guide.mdmarkdown17.2 KB
references/hookshot-integration.mdmarkdown10.7 KB
references/messaging-guide.mdmarkdown13.8 KB
references/no-editorializing.mdmarkdown331 B
references/setup-guide.mdmarkdown11.1 KB
references/troubleshooting.mdmarkdown7.8 KB
scripts/_lib/__init__.pyscript3.6 KB
scripts/_lib/backup_mac.pyscript1.2 KB
scripts/_lib/config.pyscript4.6 KB
scripts/_lib/daemon_client.pyscript3.0 KB
scripts/_lib/deps.pyscript1.9 KB
scripts/_lib/downloads.pyscript1.1 KB
scripts/_lib/e2ee.pyscript13.2 KB
scripts/_lib/formatting.pyscript14.4 KB
scripts/_lib/http.pyscript4.8 KB
scripts/_lib/reactions.pyscript2.9 KB
scripts/_lib/roomlog.pyscript13.7 KB
scripts/_lib/rooms.pyscript15.5 KB
scripts/_lib/secret_input.pyscript2.0 KB
scripts/_lib/test_backup_mac.pyscript1.5 KB
scripts/_lib/test_config.pyscript7.1 KB
scripts/_lib/test_daemon_client.pyscript5.9 KB
scripts/_lib/test_downloads.pyscript2.3 KB
scripts/_lib/test_e2ee.pyscript14.3 KB
scripts/_lib/test_formatting.pyscript15.5 KB
scripts/_lib/test_http.pyscript4.1 KB
scripts/_lib/test_reactions.pyscript15.2 KB
scripts/_lib/test_roomlog.pyscript20.2 KB
scripts/_lib/test_rooms.pyscript13.7 KB
scripts/_lib/test_secret_input.pyscript2.2 KB
scripts/_lib/test_trust.pyscript8.3 KB
scripts/_lib/trust.pyscript5.3 KB
scripts/_lib/utils.pyscript1.7 KB
scripts/matrix-create-room.pyexecutablescript4.7 KB
scripts/matrix-doctor.pyexecutablescript22.2 KB
scripts/matrix-download-e2ee.pyexecutablescript7.7 KB
scripts/matrix-e2ee-setup.pyexecutablescript9.2 KB
scripts/matrix-e2ee-verify.pyexecutablescript29.2 KB
scripts/matrix-edit-e2ee.pyexecutablescript7.9 KB
scripts/matrix-edit.pyexecutablescript5.3 KB
scripts/matrix-fetch-keys.pyexecutablescript9.1 KB
scripts/matrix-invite.pyexecutablescript3.0 KB
scripts/matrix-key-backup.pyexecutablescript21.3 KB
scripts/matrix-power-level.pyexecutablescript7.0 KB
scripts/matrix-react.pyexecutablescript14.1 KB
scripts/matrix-read-e2ee.pyexecutablescript12.8 KB
scripts/matrix-read.pyexecutablescript4.7 KB
scripts/matrix-redact.pyexecutablescript5.0 KB
scripts/matrix-resolve.pyexecutablescript1.7 KB
scripts/matrix-rooms.pyexecutablescript3.8 KB
scripts/matrix-send-e2ee.pyexecutablescript19.4 KB
scripts/matrix-send.pyexecutablescript9.4 KB
scripts/matrix-watch.pyexecutablescript5.3 KB
scripts/matrix-watchd.pyexecutablescript23.5 KB
scripts/test_matrix_doctor.pyscript14.2 KB
scripts/test_matrix_read_e2ee.pyscript2.7 KB

references/api-reference.md

View on GitHub
<!-- SPDX-License-Identifier: CC-BY-SA-4.0 -->
<!-- SPDX-FileCopyrightText: Netresearch DTT GmbH -->

# Matrix Client-Server API Reference

Quick reference for Matrix API endpoints used by this skill.

## Authentication

All requests require Bearer token authentication:

```bash
curl -H "Authorization: Bearer $MATRIX_TOKEN" ...
```

## Base URL

```
https://matrix.org/_matrix/client/v3
```

## Endpoints

### Account

```bash
# Who am I?
GET /account/whoami

# Response:
{
  "user_id": "@user:matrix.org",
  "device_id": "ABCDEF",
  "is_guest": false
}
```

### Rooms

```bash
# List joined rooms
GET /joined_rooms

# Response:
{
  "joined_rooms": ["!room1:server", "!room2:server"]
}

# Resolve room alias to ID
GET /directory/room/%23alias:server

# Response:
{
  "room_id": "!abc:server",
  "servers": ["server"]
}

# Get room name
GET /rooms/{roomId}/state/m.room.name

# Response:
{
  "name": "Room Name"
}
```

### Room Management

```bash
# Create a room
POST /createRoom

# Body:
{
  "name": "Room Name",
  "preset": "private_chat",
  "room_alias_name": "localpart",
  "topic": "Optional topic",
  "invite": ["@user:server"]
}

# preset: private_chat (default) | public_chat | trusted_private_chat

# Response:
{
  "room_id": "!abc:server"
}

# Invite a user
POST /rooms/{roomId}/invite

# Body:
{
  "user_id": "@user:server"
}

# Response: {} on success

# Get power levels (state key is the empty string, hence the trailing slash)
GET /rooms/{roomId}/state/m.room.power_levels/

# Response (abridged):
{
  "users": {"@admin:server": 100},
  "users_default": 0,
  "events": {...},
  "state_default": 50,
  "ban": 50, "kick": 50, "redact": 50, "invite": 0
}

# Set power levels — PUT replaces the ENTIRE state event, no server-side
# merge. Always GET first, mutate the "users" dict, then PUT the whole
# object back, or every other key (state_default, ban/kick/redact/invite,
# other users' levels) gets wiped.
PUT /rooms/{roomId}/state/m.room.power_levels/

# The acting user's own power level must be >= the level being granted
# and >= the target's current level, or the homeserver returns M_FORBIDDEN.

# On newer room versions the creator has implicit, permanent authority and
# must NOT appear in "users" — setting the creator's own level is rejected:
# {"error": "Creator user must not appear in content.users", ...}
```

### Messages

```bash
# Send message
PUT /rooms/{roomId}/send/m.room.message/{txnId}

# Body (plain text):
{
  "msgtype": "m.text",
  "body": "Hello!"
}

# Body (formatted):
{
  "msgtype": "m.text",
  "body": "**Hello!**",
  "format": "org.matrix.custom.html",
  "formatted_body": "<strong>Hello!</strong>"
}

# Response:
{
  "event_id": "$abc123"
}

# Read messages (via sync)
GET /sync?timeout=0&full_state=true&filter={...}

# Filter for specific room:
{
  "room": {
    "rooms": ["!roomId:server"],
    "timeline": {"limit": 10}
  }
}
```

## Message Types

| msgtype | Description |
|---------|-------------|
| `m.text` | Plain text message |
| `m.notice` | Bot/notification message |
| `m.emote` | Action message (/me) |
| `m.image` | Image attachment |
| `m.file` | File attachment |

### Reactions

```bash
# Send reaction
PUT /rooms/{roomId}/send/m.reaction/{txnId}

# Body:
{
  "m.relates_to": {
    "rel_type": "m.annotation",
    "event_id": "$target_event_id",
    "key": "👍"
  }
}
```

### Account Data

```bash
# Get account data (e.g., key backup passphrase info)
GET /user/{userId}/account_data/{type}

# Types: m.megolm_backup.v1, m.secret_storage.default_key, m.secret_storage.key.{keyId}
```

### Key Backup

```bash
# Get current backup version
GET /room_keys/version

# Response:
{
  "algorithm": "m.megolm_backup.v1.curve25519-aes-sha2",
  "auth_data": { ... },
  "count": 1234,
  "etag": "...",
  "version": "5"
}

# Get backed-up keys
GET /room_keys/keys?version={version}
```

### Reading history without the E2EE store

`matrix-read-e2ee.py` opens the encryption store, so it refuses while `matrix-watchd.py`
holds it (`Error: the E2EE store is held by pid …`) — the documented fallback to the
direct path applies to sending, not to this. When the messages you are after are
*unencrypted* — everything a webhook, a bridge or an RSS feed posts is — the plain
`/messages` endpoint answers with the config's own `access_token` and needs no store at
all. It performs no `/sync` and touches no key endpoint, so it changes no device state —
which is why it does not fall under the rule against reusing a client's token: **that
rule still stands**, take the token from `~/.config/matrix/config.json`, never from
Element or another running client. Where the config carries no `access_token` (E2EE set
up by password only), this path is not available; the store holds device credentials, not
a bearer token.

```bash
HS=$(python3 -c 'import json;print(json.load(open("'$HOME'/.config/matrix/config.json"))["homeserver"])')
TOKEN=$(python3 -c 'import json;print(json.load(open("'$HOME'/.config/matrix/config.json"))["access_token"])')
ROOM=$(curl -s -H "Authorization: Bearer $TOKEN" \
  "$HS/_matrix/client/v3/directory/room/%23room%3Aserver" | python3 -c 'import json,sys;print(json.load(sys.stdin)["room_id"])')

# newest first; page with the returned `end` token until `origin_server_ts` is old enough
curl -s -H "Authorization: Bearer $TOKEN" --get \
  --data-urlencode 'dir=b' --data-urlencode 'limit=100' \
  --data-urlencode 'filter={"types":["m.room.message","m.room.encrypted"]}' \
  "$HS/_matrix/client/v3/rooms/$(python3 -c 'import urllib.parse,sys;print(urllib.parse.quote(sys.argv[1],safe=""))' "$ROOM")/messages"
```

The response holds `chunk` (the events, newest first) and `end` (pass it back as `from`).

**Keep `m.room.encrypted` in the filter even though you cannot read those events.** With
`m.room.message` alone the encrypted traffic is not merely unreadable, it is invisible,
and an encrypted room comes back looking empty. Measured on one project room: the same
50-event window returns 50 plaintext messages under the narrow filter and 24 plaintext
plus 26 encrypted under this one — more than half the room. An `m.room.encrypted` entry
carries no readable content on this path; it is the proof that something was said, and
the reason a count from here is a count of *plaintext* events, never of messages.

Thirty days of ten project rooms were read this way for an event-store backfill while the
daemon kept running.

## Event Types

| type | Description |
|------|-------------|
| `m.room.message` | Regular message |
| `m.room.encrypted` | E2EE encrypted message |
| `m.room.name` | Room name state |
| `m.room.topic` | Room topic state |
| `m.room.member` | Membership event |
| `m.reaction` | Reaction annotation (relates_to another event) |

## Error Codes

| errcode | Description |
|---------|-------------|
| `M_FORBIDDEN` | Access denied (not in room, no permission) |
| `M_UNKNOWN_TOKEN` | Invalid or expired access token |
| `M_NOT_FOUND` | Room/resource not found |
| `M_LIMIT_EXCEEDED` | Rate limited |
| `M_GUEST_ACCESS_FORBIDDEN` | Guest access not allowed |

## Rate Limits

Matrix homeservers typically enforce rate limits:
- ~10 messages per second per room
- ~100 requests per second per user

The skill scripts include basic error handling for rate limits.

## References

- [Matrix Client-Server API Spec](https://spec.matrix.org/latest/client-server-api/)
- [Matrix Room Versions](https://spec.matrix.org/latest/rooms/)
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 197kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall