Matrix Announcement
Content guidance for Matrix announcements; matrix-communication does the sending.
The five rules
- One headline, one purpose. A Matrix message is a tweet, not a blog post.
- Send
formatted_body with the HTML subset. body stays as plaintext fallback. Never send only Markdown — clients are not required to parse it.
- Lists beat paragraphs. If you're tempted to write "and also …", start a
<ul>.
- Wrap code. Inline
<code> for commands, paths, version strings, IDs, env vars — every one of them. Multi-line snippets in <pre><code class="language-…">.
- Layout > words → render an HTML card to PNG. Comparisons, dashboards, multi-row tables die in
formatted_body.
Type tags (pick one — never stack)
| Tag |
Meaning |
Title example |
New skill |
first public release |
New skill: github-release-skill v0.2.0 |
Release |
feature version |
Release: jira-skill v3.12.0 |
Patch |
bugfix-only |
Patch: docker-development-skill v1.7.0 |
Digest |
weekly / multi-skill roundup |
Digest: skill ecosystem — week of 2026-04-22 |
Heads-up |
breaking change, deprecation |
Heads-up: matrix-skill v2 drops Python 3.8 |
Postmortem |
incident summary |
Postmortem: CI cache wipe 2026-04-25 |
RFC |
proposal seeking feedback |
RFC: unified checkpoint schema |
Glyphs
One leading glyph at most. Never trailing decoration, multi-emoji ladders, 🚀, or 🎉. Approved: 🤖 bot · 📦 release · 🔧 tooling · 🛡 security · ⚠️ heads-up · 📋 digest · 🔬 RFC · 🚑 hotfix · 🔥 postmortem · ✨ new capability (sparingly).
Pre-send checklist
References
- html-subset.md — allowed/banned tags, Markdown↔HTML,
data-mx-* attributes
- structure.md — skeleton, section patterns, element-when-to-use, length budget,
m.text vs m.notice
- glyphs.md — full glyph table with banned set
- image-cards.md — chromium → upload →
m.image recipe; image-pairing rules
- threading.md — threads, mentions, edits, redactions
- anti-patterns.md — wall-of-text, emoji ladder, mention storm, inline URLs (with fixes)
- text-templates.md — drop-in
formatted_body skeletons per type tag
- templates/ —
release-card.html (1200×630), weekly-digest.html (1200×1500), comparison.html (1200×900)
- gallery.html — visual preview of every rule, the five worked examples, and the three templates
Sending: pass the composed message to matrix-communication (matrix-send-e2ee.py "$ROOM" "$MARKDOWN" [--notice]). The transport converts markdown to HTML using the rules in html-subset.md; pass --notice for unattended automation so other bots can't auto-reply (mutually exclusive with --emote). For hand-crafted formatted_body or m.image cards, call the homeserver API directly — recipe in image-cards.md.
1---2name: matrix-announcement3description: Use 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. Defines the HTML subset clients render, the type-tag system, glyph rules (no rockets, no party emoji), the m.text vs m.notice choice, and when to render an HTML card to PNG instead of cramming layout into formatted_body. Trigger before any matrix-send call that produces structured content. Companion to matrix-communication.4license: (MIT AND CC-BY-SA-4.0). See LICENSE-MIT and LICENSE-CC-BY-SA-4.05---6
7# Matrix Announcement
8
9Content guidance for Matrix announcements; `matrix-communication` does the sending.
10
11## The five rules
12
131. **One headline, one purpose.** A Matrix message is a tweet, not a blog post.
142. **Send `formatted_body` with the HTML subset.** `body` stays as plaintext fallback. Never send only Markdown — clients are not required to parse it.
153. **Lists beat paragraphs.** If you're tempted to write "and also …", start a `<ul>`.
164. **Wrap code.** Inline `<code>` for commands, paths, version strings, IDs, env vars — every one of them. Multi-line snippets in `<pre><code class="language-…">`.
175. **Layout > words → render an HTML card to PNG.** Comparisons, dashboards, multi-row tables die in `formatted_body`.
18
19## Type tags (pick one — never stack)
20
21| Tag | Meaning | Title example |
22| --- | --- | --- |
23| `New skill` | first public release | `New skill: github-release-skill v0.2.0` |
24| `Release` | feature version | `Release: jira-skill v3.12.0` |
25| `Patch` | bugfix-only | `Patch: docker-development-skill v1.7.0` |
26| `Digest` | weekly / multi-skill roundup | `Digest: skill ecosystem — week of 2026-04-22` |
27| `Heads-up` | breaking change, deprecation | `Heads-up: matrix-skill v2 drops Python 3.8` |
28| `Postmortem` | incident summary | `Postmortem: CI cache wipe 2026-04-25` |
29| `RFC` | proposal seeking feedback | `RFC: unified checkpoint schema` |
30
31## Glyphs
32
33One leading glyph at most. **Never** trailing decoration, multi-emoji ladders, 🚀, or 🎉. Approved: 🤖 bot · 📦 release · 🔧 tooling · 🛡 security · ⚠️ heads-up · 📋 digest · 🔬 RFC · 🚑 hotfix · 🔥 postmortem · ✨ new capability (sparingly).
34
35## Pre-send checklist
36
37- [ ] Title fits on one line in Element on a 1280-wide screen.
38- [ ] First sentence states the change. No "we're excited to".
39- [ ] Every URL wrapped in `<a>` with destination-as-text.
40- [ ] Every command, path, version is in `<code>`.
41- [ ] Multi-line code in `<pre><code class="language-…">`.
42- [ ] At most one prefix glyph; no trailing emoji; no celebration.
43- [ ] `body` is a real readable plaintext fallback, not stripped HTML.
44- [ ] `msgtype` = `m.notice` for unattended automation, `m.text` otherwise.
45- [ ] No `@room` unless it is an outage.
46- [ ] Layout-heavy → card image with text fallback, not `<table>` in `formatted_body`.
47- [ ] Length under 3000 chars or split into a thread.
48
49## References
50
51- [html-subset.md](references/html-subset.md) — allowed/banned tags, Markdown↔HTML, `data-mx-*` attributes
52- [structure.md](references/structure.md) — skeleton, section patterns, element-when-to-use, length budget, `m.text` vs `m.notice`
53- [glyphs.md](references/glyphs.md) — full glyph table with banned set
54- [image-cards.md](references/image-cards.md) — chromium → upload → `m.image` recipe; image-pairing rules
55- [threading.md](references/threading.md) — threads, mentions, edits, redactions
56- [anti-patterns.md](references/anti-patterns.md) — wall-of-text, emoji ladder, mention storm, inline URLs (with fixes)
57- [text-templates.md](references/text-templates.md) — drop-in `formatted_body` skeletons per type tag
58- [templates/](references/templates/) — `release-card.html` (1200×630), `weekly-digest.html` (1200×1500), `comparison.html` (1200×900)
59- [gallery.html](references/gallery.html) — visual preview of every rule, the five worked examples, and the three templates
60
61Sending: pass the composed message to `matrix-communication` (`matrix-send-e2ee.py "$ROOM" "$MARKDOWN" [--notice]`). The transport converts markdown to HTML using the rules in `html-subset.md`; pass `--notice` for unattended automation so other bots can't auto-reply (mutually exclusive with `--emote`). For hand-crafted `formatted_body` or `m.image` cards, call the homeserver API directly — recipe in `image-cards.md`.
aibot88