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/structure.md

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

# Announcement structure

Every announcement, regardless of topic, has the same skeleton. Readers learn the rhythm and skim faster.

```
[icon] [Type tag]: [Subject] [— optional version]
[one-sentence why-this-matters]

[Section heading 1]
- bullet
- bullet

[Section heading 2]
- bullet

[Footer: links / tracking ticket / install command]
```

The icon and tag work like a subject-line prefix in email (`[SECURITY]`, `[RELEASE]`). They let humans and grep-style filters skim a busy room.

## Type tags

Pick one. Do not stack.

| Tag | Meaning | Title example |
| --- | --- | --- |
| `New skill` | first public release of a skill | `New skill: github-release-skill v0.2.0` |
| `Release` | new feature version of an existing skill | `Release: jira-skill v3.12.0` |
| `Patch` | bugfix-only bump | `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, migration | `Heads-up: matrix-skill v2 drops Python 3.8` |
| `Postmortem` | incident summary | `Postmortem: CI cache wipe 2026-04-25` |
| `Findings` | result of an investigation or audit — what ran, what broke, what is expected behavior | `Findings: Renovate run after TYPO3 14.3.5` |
| `RFC` | proposal looking for feedback | `RFC: unified checkpoint schema` |

`Postmortem` vs `Findings`: a postmortem explains one incident that is already over (symptom → cause → fix). `Findings` reports what a check turned up across several subjects, where some results are failures and some are working-as-designed.

## Section headings

Use **at most three** sections per message. Common patterns:

- **What it does / What it prevents / Install** — for new skill releases
- **New / Changed / Fixed** — for version bumps
- **Highlights / This week's releases / Open questions** — for digests
- **Symptom / Cause / Fix** — for postmortems
- **Errors found / No error, expected behavior / Next steps** — for findings reports
- **Why / How / Try it** — for proposals

Render headings as `<strong>Heading:</strong>` on its own line, or `<h3>` if the message is long enough to warrant TOC-style skimming. Avoid `<h2>`/`<h1>` (too loud).

## Sentence economy

- **First sentence states the change.** "X now does Y." Not "We are excited to announce that …".
- **Second sentence states the consequence.** "Existing tags continue to work; new tags require `-s`."
- **Skip the third sentence.** If you need it, it is a bullet.

## When to use which element

| Element | Use it for | Avoid for |
| --- | --- | --- |
| `<strong>` | the one word in a sentence the reader must not miss | every other word |
| `<code>` | commands, paths, identifiers, version strings, env vars, JSON keys | English nouns |
| `<pre><code>` | multi-line commands, JSON examples, diff snippets | one-liners |
| `<ul>` | 2–7 unordered items | a list of one — write a sentence |
| `<ol>` | numbered steps where order matters | bullets that just happen to have numbers |
| `<blockquote>` | quoting a user, an error, a previous decision | indenting for visual variety |
| `<table>` | tabular data ≥2 cols × ≥3 rows | two-column term/definition pairs |
| `<hr>` | separating an unrelated postscript | between every section (use spacing) |
| `<a>` | every URL — never paste raw URLs in `formatted_body` | "click here" — use the destination as text |
| `<br>` | a forced line break inside a paragraph | between paragraphs (use `<p>`) |

### Links: write what they are

```
✗ More info: <a href="…/issues/4365">here</a>
✓ Tracking: <a href="…/issues/4365">NRS-4365</a>
✓ Repo: <a href="https://github.com/netresearch/github-release-skill">github.com/netresearch/github-release-skill</a>
```

The link text should be the destination's identity (ticket, repo, doc title), not a verb.

### Link every entity, not just "the" link

Readers click the thing they are looking at — every linkable entity in the message body is a link, including incidental mentions:

- **Issue keys** — every occurrence, even mid-sentence context (`blockers from <a href="…/SRVC-99">SRVC-99</a> cleared`), not only the headline ticket.
- **Version numbers** — link to their release page, keeping the version in `<code>` inside the link: `traefik <a href="…/releases/tag/v3.7.1"><code>3.7.1</code></a>→<a href="…/releases/tag/v3.7.4"><code>3.7.4</code></a>`. A version without its release notes makes the reader search for them.
- **MRs / PRs** — use the platform's reference notation as text: GitLab `<a href="…">project/path!30</a>`, GitHub `<a href="…">org/repo#42</a>`. Never bare "MR !30" — it is ambiguous across projects and unclickable when copied.
- **Pipelines, commits, tags, branches** — same rule: identity as text, URL behind it.

### Status updates: one item per line

Multi-item progress posts (maintenance logs, digest-style updates) get one line per ticket/work item, separated by blank lines, each line starting with the linked issue key. Readers scan for *their* item; interleaved prose hides it.

### Findings reports: one finding, one list item

A findings report (investigation result, audit, "did the automation run?") is a list, not prose — `<ul>` with one `<li>` per finding, each opening with the linked subject. This holds when the items are long: a finding that needs three sentences is still one `<li>`. A paragraph that merely starts with a bold word gives the reader no left edge to scan down. See [anti-patterns](anti-patterns.md) ("Bold lead-in paragraphs").

Group findings under headings that name **the category of finding, never the person who was wrong**: `Errors found` / `No error, expected behavior`, not `Real errors` / `Corrections`. Reports that refute someone's assumptions are read by that someone, and the framing decides whether the facts get read at all.

## Length budget

| Metric | Target | Hard limit |
| --- | --- | --- |
| Title line | 6–12 words | 16 words |
| Lede sentence | 12–20 words | 30 words |
| Bullets per section | 3–5 | 7 |
| Sections per message | 2–3 | 4 |
| Total `formatted_body` length | ≤1500 chars | 3000 chars |
| Code blocks per message | ≤1 | 2 |

If you blow past the hard limit, you have a digest, not an announcement. Split it: short headline message in the room, full content in a thread or a linked doc.

## `m.text` vs `m.notice`

| `msgtype` | Use for | Why |
| --- | --- | --- |
| `m.notice` | Unattended automation: release announcements, CI summaries, scheduled digests, alert pings | Clients render it visually distinct (usually muted) and **bots are forbidden from auto-replying** to it — prevents bot-on-bot loops |
| `m.text` | Agent posting on behalf of a human who reviewed it (or a real human typing) | Default; replies welcome |

## Findings reports: group by finding, not by who was wrong

Headings name the category of finding (`Errors found`, `No error, expected
behavior`), never the person or side that held the wrong view (`Real errors`,
`Corrections`). The report is about the system under investigation; a heading
that sorts by who was mistaken turns it into something else, and readers who
were named remember that instead of the finding.

## Sending an announcement

`matrix-communication` ships it and converts markdown to HTML per
`html-subset.md`:

```bash
${CLAUDE_SKILL_DIR}/../matrix-communication/scripts/matrix-send-e2ee.py "$ROOM" "$MARKDOWN" [--notice]
```

`--notice` marks automation and is exclusive of `--emote`. For a hand-crafted
`formatted_body` or an `m.image` event, call the homeserver API directly — the
recipe is in `image-cards.md`.
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