How do I install the Matrix Administration skill?

Run npx skillmds@latest add netresearch/matrix-administration in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Matrix Administration safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Matrix Administration?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Matrix Administration free to use?

Yes. Installing skills from SkillMD is free. This skill is licensed under (MIT AND CC-BY-SA-4.

Who published Matrix Administration?

netresearch (@netresearch) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Matrix Administration by netresearch

Name: Matrix Administration
Author: netresearch

Matrix Administration

Use when administering a Synapse / Matrix homeserver — list or snapshot all rooms, rate room health (public, unencrypted, orphaned), render a Graphviz map of the room/space tree, force-join users, promote room admins, harden rooms (add-to-space + restrict + encrypt), deactivate Matrix users (with GDPR erase), find biggest rooms by DB size, audit where a user is admin or member, replay join/leave timelines, or search unencrypted history. Trigger on any '/_synapse/admin', server-wide room operation, Matrix user offboarding, or anything requiring a homeserver-admin token — even without 'admin API' in the prompt. Companion to matrix-communication.

netresearch fb3ccca 29 files · 102.9 KB Updated Sep 17, 2026

File contents

Matrix Administration

Stdlib-only Python wrappers around the Synapse Admin API and the Client-Server API. Reads ~/.config/matrix/config.json (the same file matrix-communication uses).

Quick Reference

S=skills/matrix-administration/scripts

python3 ${CLAUDE_SKILL_DIR}/scripts/synapse-fetch-rooms.py [--server :example.com]
python3 ${CLAUDE_SKILL_DIR}/scripts/synapse-rate-rooms.py --space '!home:srv' [--language de]
python3 ${CLAUDE_SKILL_DIR}/scripts/synapse-graph.py --space '!home:srv'
python3 ${CLAUDE_SKILL_DIR}/scripts/synapse-biggest-rooms.py [-n 10]

python3 ${CLAUDE_SKILL_DIR}/scripts/synapse-join-room.py    '!room:srv' '@user:srv'
python3 ${CLAUDE_SKILL_DIR}/scripts/synapse-make-admin.py   '!room:srv' '@user:srv'
python3 ${CLAUDE_SKILL_DIR}/scripts/synapse-add-to-space.py '!room:srv' '!space:srv'
python3 ${CLAUDE_SKILL_DIR}/scripts/synapse-migrate-room.py '!room:srv' '@admin:srv' '!space:srv'   # DESTRUCTIVE, asks first

python3 ${CLAUDE_SKILL_DIR}/scripts/synapse-deactivate-user.py   '@user:srv'   # DESTRUCTIVE
python3 ${CLAUDE_SKILL_DIR}/scripts/synapse-user-rooms.py        '@user:srv'
python3 ${CLAUDE_SKILL_DIR}/scripts/synapse-user-admin-rooms.py  '@user:srv'
python3 ${CLAUDE_SKILL_DIR}/scripts/synapse-room-member-flow.py  '!room:srv'
python3 ${CLAUDE_SKILL_DIR}/scripts/synapse-search.py            '!room:srv' '@bot:srv' deploy

Scripts

Script	Purpose
`synapse-fetch-rooms.py`	Snapshot all rooms + state → `rooms.json`
`synapse-rate-rooms.py`	Health checks (EN/DE) on `rooms.json`
`synapse-graph.py`	Render `rooms.json` → Graphviz `.dot` + `.svg`
`synapse-biggest-rooms.py`	Top-N rooms by DB size
`synapse-join-room.py`	Force-join a user
`synapse-make-admin.py`	Promote to PL 100
`synapse-add-to-space.py`	Send `m.space.child`
`synapse-migrate-room.py`	Add to space + restrict + encrypt
`synapse-deactivate-user.py`	Destructive deactivation (`--erase` for GDPR)
`synapse-user-admin-rooms.py`	Local: rooms where user is PL 100
`synapse-user-rooms.py`	Local: rooms a user belongs to
`synapse-room-member-flow.py`	Join/leave timeline
`synapse-search.py`	Unencrypted history search

Setup

~/.config/matrix/config.json (respects $XDG_CONFIG_HOME):

{
  "homeserver": "https://matrix.example.com",
  "admin_token": "syt_admin_…",
  "room_filter": ":example.com",
  "default_space_id": "!home:example.com",
  "home_space_ids": ["!home:example.com"]
}

homeserver and either admin_token or access_token (server-admin) are required. The other fields are optional. Env fallbacks: MATRIX_USER_ID, MATRIX_SPACE_ID, LANGUAGE=en|de, NO_COLOR.

Safety

The token is server-admin. Read references/safety-guide.md before any destructive op.

synapse-deactivate-user.py is irreversible.
synapse-migrate-room.py enables encryption (one-way) and restricts joins; it prints the plan and asks before the first write (--yes skips, and is required without a terminal). Power-level changes restored on exit including Ctrl-C.
synapse-make-admin.py raises PL 100 permanently.
synapse-search.py cannot read E2EE — empty ≠ no messages.
rooms.json exposes user IDs; never commit it.

References

references/synapse-admin-api.md — endpoints + upstream docs
references/room-health-checks.md — rules + remediation
references/room-graph-pipeline.md — Docker dashboard recipe
references/safety-guide.md — destructive-op checklist
Source: netresearch/matrix-skill

---name: matrix-administrationdescription: Use when administering a Synapse / Matrix homeserver — list or snapshot all rooms, rate room health (public, unencrypted, orphaned), render a Graphviz map of the room/space tree, force-join users, promote room admins, harden rooms (add-to-space + restrict + encrypt), deactivate Matrix users (with GDPR erase), find biggest rooms by DB size, audit where a user is admin or member, replay join/leave timelines, or search unencrypted history. Trigger on any '/_synapse/admin', server-wide room operation, Matrix user offboarding, or anything requiring a homeserver-admin token — even without 'admin API' in the prompt. Companion to matrix-communication.license: (MIT AND CC-BY-SA-4.0). See LICENSE-MIT and LICENSE-CC-BY-SA-4.0---# Matrix AdministrationStdlib-only Python wrappers around the Synapse [Admin API](https://element-hq.github.io/synapse/latest/usage/administration/admin_api/index.html) and the Client-Server API. Reads `~/.config/matrix/config.json` (the same file matrix-communication uses).## Quick Reference```bashS=skills/matrix-administration/scriptspython3 ${CLAUDE_SKILL_DIR}/scripts/synapse-fetch-rooms.py [--server :example.com]python3 ${CLAUDE_SKILL_DIR}/scripts/synapse-rate-rooms.py --space '!home:srv' [--language de]python3 ${CLAUDE_SKILL_DIR}/scripts/synapse-graph.py --space '!home:srv'python3 ${CLAUDE_SKILL_DIR}/scripts/synapse-biggest-rooms.py [-n 10]python3 ${CLAUDE_SKILL_DIR}/scripts/synapse-join-room.py '!room:srv' '@user:srv'python3 ${CLAUDE_SKILL_DIR}/scripts/synapse-make-admin.py '!room:srv' '@user:srv'python3 ${CLAUDE_SKILL_DIR}/scripts/synapse-add-to-space.py '!room:srv' '!space:srv'python3 ${CLAUDE_SKILL_DIR}/scripts/synapse-migrate-room.py '!room:srv' '@admin:srv' '!space:srv' # DESTRUCTIVE, asks firstpython3 ${CLAUDE_SKILL_DIR}/scripts/synapse-deactivate-user.py '@user:srv' # DESTRUCTIVEpython3 ${CLAUDE_SKILL_DIR}/scripts/synapse-user-rooms.py '@user:srv'python3 ${CLAUDE_SKILL_DIR}/scripts/synapse-user-admin-rooms.py '@user:srv'python3 ${CLAUDE_SKILL_DIR}/scripts/synapse-room-member-flow.py '!room:srv'python3 ${CLAUDE_SKILL_DIR}/scripts/synapse-search.py '!room:srv' '@bot:srv' deploy```## Scripts| Script | Purpose ||--------|---------|| `synapse-fetch-rooms.py` | Snapshot all rooms + state → `rooms.json` || `synapse-rate-rooms.py` | Health checks (EN/DE) on `rooms.json` || `synapse-graph.py` | Render `rooms.json` → Graphviz `.dot` + `.svg` || `synapse-biggest-rooms.py` | Top-N rooms by DB size || `synapse-join-room.py` | Force-join a user || `synapse-make-admin.py` | Promote to PL 100 || `synapse-add-to-space.py` | Send `m.space.child` || `synapse-migrate-room.py` | Add to space + restrict + encrypt || `synapse-deactivate-user.py` | **Destructive** deactivation (`--erase` for GDPR) || `synapse-user-admin-rooms.py` | Local: rooms where user is PL 100 || `synapse-user-rooms.py` | Local: rooms a user belongs to || `synapse-room-member-flow.py` | Join/leave timeline || `synapse-search.py` | Unencrypted history search |## Setup`~/.config/matrix/config.json` (respects `$XDG_CONFIG_HOME`):```json{ "homeserver": "https://matrix.example.com", "admin_token": "syt_admin_…", "room_filter": ":example.com", "default_space_id": "!home:example.com", "home_space_ids": ["!home:example.com"]}````homeserver` and either `admin_token` or `access_token` (server-admin) are required. The other fields are optional. Env fallbacks: `MATRIX_USER_ID`, `MATRIX_SPACE_ID`, `LANGUAGE=en|de`, `NO_COLOR`.## SafetyThe token is server-admin. Read [`references/safety-guide.md`](references/safety-guide.md) before any destructive op.- `synapse-deactivate-user.py` is irreversible.- `synapse-migrate-room.py` enables encryption (one-way) and restricts joins; it prints the plan and asks before the first write (`--yes` skips, and is required without a terminal). Power-level changes restored on exit including Ctrl-C.- `synapse-make-admin.py` raises PL 100 permanently.- `synapse-search.py` cannot read E2EE — empty ≠ no messages.- `rooms.json` exposes user IDs; never commit it.## References- [`references/synapse-admin-api.md`](references/synapse-admin-api.md) — endpoints + upstream docs- [`references/room-health-checks.md`](references/room-health-checks.md) — rules + remediation- [`references/room-graph-pipeline.md`](references/room-graph-pipeline.md) — Docker dashboard recipe- [`references/safety-guide.md`](references/safety-guide.md) — destructive-op checklist- Source: [netresearch/matrix-skill](https://github.com/netresearch/matrix-skill)

Frequently asked questions

Matrix Administration

File contents

Matrix Administration

Quick Reference

Scripts

Setup

Safety

References

Related skills

Frequently asked questions

How do I install the Matrix Administration skill?

What does the Matrix Administration skill do?

Is Matrix Administration safe to use?

Which AI agents work with Matrix Administration?

Is Matrix Administration free to use?

Who published Matrix Administration?