Skip to content

netresearch/matrix-skill / skills/matrix-announcement

matrix-announcement

Verified

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.

references/html-subset.md

View on GitHub
<!-- SPDX-License-Identifier: CC-BY-SA-4.0 -->
<!-- SPDX-FileCopyrightText: Netresearch DTT GmbH -->

# The HTML subset Matrix clients render

The Matrix spec defines an explicit allow-list. Element, Cinny, FluffyChat all converge on roughly the same set. Treat this as the floor — if it's not on the allow-list, assume the client strips it silently.

## Allowed

**Inline:** `<a>`, `<b>`, `<i>`, `<u>`, `<strong>`, `<em>`, `<code>`, `<del>`, `<strike>`, `<sub>`, `<sup>`, `<br>`, `<span>`

**Block:** `<p>`, `<div>`, `<blockquote>`, `<pre>`, `<hr>`, `<h3>`–`<h6>`

**Lists:** `<ul>`, `<ol>`, `<li>`

**Tables:** `<table>`, `<thead>`, `<tbody>`, `<tr>`, `<th>`, `<td>`, `<caption>`

**Collapsible:** `<details>`, `<summary>` — on the spec's suggested list and kept by Element web's sanitizer, which renders a collapsible block. Put the first line in `<summary>` and never hide the verdict inside it.

**Matrix-specific:**

- `<span data-mx-color="#…">` and `data-mx-bg-color` for color
- `<span data-mx-spoiler="reason">` for spoilers
- `<a href="https://matrix.to/#/@user:server">@user</a>` for mentions
- `<mx-reply>` — client-injected on rich replies; never write it yourself
- `<pre><code class="language-bash">` — Element renders syntax highlighting; common classes: `language-bash`, `language-python`, `language-json`, `language-diff`, `language-yaml`

## Banned (silently stripped)

- `<script>`, `<iframe>`, `<form>`, `<style>` — entire elements removed
- `style="…"` attributes — beyond `data-mx-*`, all inline CSS is stripped
- `<img src="https://…">` from arbitrary URLs — images go in via `m.image` events with `mxc://` URIs
- `<video>`, `<audio>` — same; use `m.video` / `m.audio` events
- `class="…"` — mostly stripped (Element keeps `language-…` on `<code>`)
- `<h1>`, `<h2>` — technically allowed but render as system-banner-loud in Element. Start at `<h3>` in practice.

## Markdown vs HTML — pick one and convert

If your skill composes in Markdown internally, run it through a real converter (markdown-it, commonmark) to produce `formatted_body`. **Do not** send raw Markdown in `formatted_body` and hope the client renders it — most do not.

`body` may keep the Markdown-ish look (backticks, `-` bullets) — that is fine and even helpful for plaintext readers.

## `body` is not optional

Notifications, push alerts, screen readers, search indexes, IRC/XMPP bridges, and CLI Matrix clients all read `body`, not `formatted_body`. Write it as a real readable message, not stripped HTML. Two good patterns:

- **Strip-and-keep** — drop tags, keep newlines, keep punctuation. Bullet glyphs (`•`, `-`) stay in. Code stays unfenced but with backticks.
- **Short summary** — when the HTML is dense (tables, cards), set `body` to a one- or two-line summary plus a link.

## A minimal rich event

```json
{
  "msgtype": "m.text",
  "format":  "org.matrix.custom.html",
  "body":    "Release: github-release-skill v0.2.0\nRepo: https://github.com/netresearch/github-release-skill",
  "formatted_body": "<p><strong>Release:</strong> <code>github-release-skill</code> v0.2.0<br/>Repo: <a href=\"https://github.com/netresearch/github-release-skill\">netresearch/github-release-skill</a></p>"
}
```

Two fields decide rendering: `body` (plaintext fallback — required) and `formatted_body` (HTML, only when `format` is set).

## Name the thing, not a category for it

Wrapping code is half the rule; the other half is *what* goes inside the tags.
Prefer the concrete identifier over an abstract noun standing in for it:

- ✅ `<code>b13/container</code> auf <code>^4.0.2</code> gehoben`
- ❌ `Constraint auf 4.x angehoben`

The abstraction drops the searchable name — nobody greps for "Constraint" — and
in German prose it smuggles in an anglicism at the same time.
writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deploymentStars: 322kUpdated Claude CodeCodexVerifiedInstall
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: 198kUpdated Claude CodeCodexVerifiedInstall
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: 119kUpdated Claude CodeCodexVerifiedInstall
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: 118kUpdated Claude CodeCodexVerifiedInstall