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. Trigger before any matrix-send call that produces structured content. Companion to matrix-communication.
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. Trigger before any matrix-send call that produces structured content. Companion to matrix-communication.
license
(MIT AND CC-BY-SA-4.0). See LICENSE-MIT and LICENSE-CC-BY-SA-4.0
compatibility
Pairs with matrix-communication for sending. Optional: Chromium for HTML-card rendering.
Content rules for Matrix announcements: HTML subset, type tags, glyphs, m.text/m.notice, PNG-card threshold. matrix-communication does the sending.
The five rules
One headline, one purpose.
formatted_body in the HTML subset, not Markdown.body is the plaintext fallback — clients aren't required to parse Markdown.
Lists beat paragraphs. Enumerable items — findings, projects, failures, tickets — are a <ul>, however long each item runs. A paragraph opening with a bold word is emphasis, not structure.
Wrap code — and name the thing itself. Commands, paths, versions, IDs, env vars in <code>; multi-line in <pre><code class="language-…">. Prefer the concrete identifier over an abstract noun standing in for it: "b13/container auf ^4.0.2 gehoben", not "Constraint auf 4.x angehoben" — the abstraction drops the searchable name AND (in German prose) smuggles in an anglicism.
Layout > words → render an HTML card to PNG. Comparisons, dashboards, multi-row tables die in formatted_body.
Type tags (pick one — never stack)
New skill — first public release
Release — feature version
Patch — bugfix-only
Digest — weekly / multi-skill roundup
Heads-up — breaking change, deprecation
Postmortem — incident summary
Findings — result of an investigation or audit
RFC — proposal seeking feedback
Findings reports group by category of finding (Errors found, No error, expected behavior), never by who was wrong (Real errors, Corrections).
Glyphs
One leading glyph at most. Never trailing decoration, multi-emoji ladders, 🚀, or 🎉. Approved: 🤖 bot · 📦 release · 🔧 tooling · 🛡 security · ⚠️ heads-up · 📋 digest · 🔬 RFC · 🚑 hotfix · 🔥 postmortem · 🔎 findings · ✨ new capability (sparingly).
Pre-send checklist
One-line title, Element at 1280px.
Opens with the change, not "we're excited to".
URLs wrapped in <a>, destination as text.
Every entity is a link: issue keys (even mid-sentence), versions → release page, MRs/PRs (project/path!N / org/repo#N), pipelines, commits. Status updates: one item per line, linked key first, blank lines between.
Enumerable items in a <ul>, not bold-led paragraphs (rule 3).
Findings headings name the category, not the person.
Code wrapped (rule 4).
Glyph OK (rules above).
body reads standalone, not stripped HTML.
msgtype = m.notice for unattended automation, m.text otherwise.
gallery.html — visual preview of rules and templates
Sending: matrix-communication ships it (${CLAUDE_SKILL_DIR}/../matrix-communication/scripts/matrix-send-e2ee.py "$ROOM" "$MARKDOWN" [--notice]), converting markdown to HTML per html-subset.md. --notice marks automation, exclusive of --emote. Hand-crafted formatted_body/m.image: call the homeserver API — recipe in image-cards.md.
