netresearch/matrix-skill / skills/matrix-administration
matrix-administration
UnverifiedUse 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.
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
uv run ${CLAUDE_SKILL_DIR}/scripts/synapse-fetch-rooms.py [--server :example.com]
uv run ${CLAUDE_SKILL_DIR}/scripts/synapse-rate-rooms.py --space '!home:srv' [--language de]
uv run ${CLAUDE_SKILL_DIR}/scripts/synapse-graph.py --space '!home:srv'
uv run ${CLAUDE_SKILL_DIR}/scripts/synapse-biggest-rooms.py [-n 10]
uv run ${CLAUDE_SKILL_DIR}/scripts/synapse-join-room.py '!room:srv' '@user:srv'
uv run ${CLAUDE_SKILL_DIR}/scripts/synapse-make-admin.py '!room:srv' '@user:srv'
uv run ${CLAUDE_SKILL_DIR}/scripts/synapse-add-to-space.py '!room:srv' '!space:srv'
uv run ${CLAUDE_SKILL_DIR}/scripts/synapse-migrate-room.py '!room:srv' '@admin:srv' '!space:srv' # DESTRUCTIVE, asks first
uv run ${CLAUDE_SKILL_DIR}/scripts/synapse-deactivate-user.py '@user:srv' # DESTRUCTIVE
uv run ${CLAUDE_SKILL_DIR}/scripts/synapse-user-rooms.py '@user:srv'
uv run ${CLAUDE_SKILL_DIR}/scripts/synapse-user-admin-rooms.py '@user:srv'
uv run ${CLAUDE_SKILL_DIR}/scripts/synapse-room-member-flow.py '!room:srv'
uv run ${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. To keep the token out of this file, set admin_token_file to a file holding it (relative paths resolve against the config directory) or export MATRIX_ADMIN_TOKEN; the environment wins over the file, the file over the inline value. 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.pyis irreversible.synapse-migrate-room.pyenables encryption (one-way) and restricts joins; it prints the plan and asks before the first write (--yesskips, and is required without a terminal). Power-level changes restored on exit including Ctrl-C.synapse-make-admin.pyraises PL 100 permanently.synapse-search.pycannot read E2EE — empty ≠ no messages.rooms.jsonexposes user IDs; never commit it.
References
references/synapse-admin-api.md— endpoints + upstream docsreferences/room-health-checks.md— rules + remediationreferences/room-graph-pipeline.md— Docker dashboard recipereferences/safety-guide.md— destructive-op checklist- Source: netresearch/matrix-skill
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 467k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 467k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 467k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 193k | Updated | Claude CodeCodex | Verified | Install |