netresearch/matrix-skill / skills/matrix-announcement
matrix-announcement
VerifiedUse when composing a Matrix announcement — skill release, version bump, weekly digest, breaking-change heads-up, postmortem, RFC, multi-skill pipeline summary, or any agent-authored room post longer than a single line. Trigger before any matrix-send call that produces structured content. Companion to matrix-communication.
| File | Kind | Size |
|---|---|---|
| README.md | markdown | 4.0 KB |
| SKILL.md | skill md | 3.5 KB |
| evals/evals.json | config | 8.2 KB |
| references/anti-patterns.md | markdown | 6.6 KB |
| references/gallery.html | other | 45.6 KB |
| references/glyphs.md | markdown | 2.0 KB |
| references/html-subset.md | markdown | 3.7 KB |
| references/image-cards.md | markdown | 5.0 KB |
| references/structure.md | markdown | 7.6 KB |
| references/templates/comparison.html | other | 3.7 KB |
| references/templates/release-card.html | other | 4.4 KB |
| references/templates/weekly-digest.html | other | 5.1 KB |
| references/text-templates.md | markdown | 6.5 KB |
| references/threading.md | markdown | 5.2 KB |
references/threading.md
View on GitHub<!-- SPDX-License-Identifier: CC-BY-SA-4.0 -->
<!-- SPDX-FileCopyrightText: Netresearch DTT GmbH -->
# Threads, mentions, edits, redactions
## Threading
A long announcement should not become a long message. Post the headline + summary as the parent; put extended notes, screenshots, and Q&A follow-ups in a thread.
A spec-compliant threaded reply has three relation fields — `rel_type`, the thread root `event_id`, an `is_falling_back` flag, and an `m.in_reply_to` pointing at the parent (root or last reply) so non-thread-aware clients still render the message as a normal reply:
```json
"m.relates_to": {
"rel_type": "m.thread",
"event_id": "$thread_root_event_id",
"is_falling_back": true,
"m.in_reply_to": {
"event_id": "$parent_event_id"
}
}
```
`event_id` is always the thread root. `m.in_reply_to.event_id` is the previous message in the thread (or the root for the first reply). `is_falling_back: true` tells thread-aware clients to suppress the reply UI — the `m.in_reply_to` is purely a fallback for older clients.
When in doubt, thread it. Rooms scroll fast.
**Except an ask.** A question or request someone has to act on goes to the main
timeline with a mention, not only into a thread: thread replies are easy to miss
in Element, and the person asked may not find the message even after the
notification. Status follow-ups on your own question can go into its thread.
Before posting, check that the room is the one the team uses (recent messages
from other people), not one whose name merely matches.
**A maintenance window gets one thread per ticket.** A window room carrying three
tickets in one flat timeline interleaves them, and a reader who cares about one
of them has to reconstruct which line belongs to which — at the moment they are
least able to. One thread per ticket, rooted on the message that claims it, and
the room's flat level carries only what is true of the whole window: it opened,
it closed, an incident started, an incident ended. The closing note for each
ticket goes in that ticket's thread *and* nowhere else, so the thread reads as a
complete story on its own.
## Timestamps
**An absolute time carries the zone it was measured in.** Not the zone you
assume, and not UTC unless that is what you actually read: a window spans a DST
boundary about twice a year, its operators sit in more than one offset, and the
logs quoted into the room are frequently in a third. "21:20" in a room whose
readers are working from a UTC log is a number that has to be guessed at, and it
is guessed at wrongly in exactly the situation the message exists for.
Write `21:20 CEST`, or `19:20 UTC`, and where a message quotes a log line, say
which zone the line itself used — for example *21:06:40 CEST, from the host's
own `date`*.
Relative times (*in ~10 minutes*, *for the last half hour*) need no zone and are
usually the kinder form for a heads-up; they just cannot be reconstructed
afterwards, so anything meant for the record gets the absolute form as well.
## Mentions
Tag people only when they actually need to see it. Use proper Matrix mentions, not plaintext `@name`:
```html
cc <a href="https://matrix.to/#/@sebastian:example.com">@sebastian</a>
```
Include the mentions block (MSC3952, now spec) so notifications fire correctly:
```json
"m.mentions": {
"user_ids": ["@sebastian:example.com"]
}
```
With `matrix-send-e2ee.py` from the matrix-communication skill,
`--mention '@alex:example.com'` sets `m.mentions`, and the pill is drawn only
where the localpart `alex` (with or without `@`) appears in the message text.
A display name such as "Alex Example" does not match, so the reader sees no
mention. Write `@alex` in the text and pass `--mention` as well.
For room-wide pings (`@room`), set `"room": true` in `m.mentions`. **Reserve them for outages** — every misuse trains people to mute the room.
## Edits
If you need to fix a typo within ~5 minutes, edit:
```json
{
"msgtype": "m.text",
"body": "* corrected text",
"format": "org.matrix.custom.html",
"formatted_body": "* <p>corrected text</p>",
"m.new_content": {
"msgtype": "m.text",
"body": "corrected text",
"format": "org.matrix.custom.html",
"formatted_body": "<p>corrected text</p>"
},
"m.relates_to": {
"rel_type": "m.replace",
"event_id": "$original_event_id"
}
}
```
The outer `body` / `formatted_body` is the fallback text shown by clients that don't render edits — prefix it with `*` so the asterisk indicates "this is an edit". `m.new_content` is the replacement content; if you set `format: org.matrix.custom.html`, `formatted_body` must be valid HTML.
If the message is already an hour old, **post a follow-up reply instead** — edits to old messages are easy to miss and notification-silent.
## Redactions
Redact only when the content is **wrong-and-harmful**:
- Leaked secret (token, password, API key)
- Mistargeted ping that woke up the wrong on-call rotation
- Personal data published to a public room
**Never redact "to clean up"** — the audit trail is more valuable than tidiness, and redactions are themselves visible events that draw attention.
```json
{
"type": "m.room.redaction",
"redacts": "$event_id_to_redact",
"content": {
"reason": "leaked secret"
}
}
```
Always include a `reason`. Redactions without context look like coverups.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |