# Matrix Server Management

> Use for standalone Matrix admin requests (register users, create rooms, manage membership, upload files). Also use when you need to send a file to the admin via Matrix media upload. Do NOT use for Worker/project creation — those handle Matrix operations internally.

- Skill: `agentscope-ai/matrix-server-management` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add agentscope-ai/matrix-server-management`
- Raw SKILL.md: https://api.skillmd.com/api/skills/agentscope-ai/matrix-server-management/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: agentscope-ai (https://skillmd.com/u/agentscope-ai)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/agentscope-ai/matrix-server-management

---


# Matrix Server Management

Manage the Tuwunel Matrix Homeserver at `${AGENTTEAMS_MATRIX_URL}`. User ID format: `@<username>:${AGENTTEAMS_MATRIX_DOMAIN}`.

## Gotchas

- **Workers IGNORE messages without `m.mentions`** — they have `requireMention: true`. You MUST include `m.mentions.user_ids` with the full Matrix user ID for Workers to process the message (MSC3952)
- **User IDs in body text and `m.mentions.user_ids` must match exactly** — partial or mismatched IDs cause silent failures
- **`trusted_private_chat` only invites members** — you must ensure each invited user accepts with `POST /join`; Controller-managed Worker and Team flows do this on the user's behalf
- **Matrix accounts cannot be deleted via API** — reuse the same username on reset
- **Do NOT use this skill for Worker/project creation** — `create-worker.sh` and `create-project.sh` handle Matrix operations internally

## Operation Reference

| Situation | Read |
|---|---|
| Any Matrix API call (register, login, rooms, messages, mentions, file upload) | `references/api-reference.md` |