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/text-templates.md

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

# Text-only `formatted_body` templates

Drop-in skeletons. Substitute `{placeholders}`. Each is paired with a `body` plaintext fallback.

## Single-skill release

```html
<p>πŸ“¦ <strong>Release:</strong> <code>{skill}</code> v{version}</p>
<p>{one-sentence summary of what this version is about}.</p>

<p><strong>What's new:</strong></p>
<ul>
  <li>{change 1}</li>
  <li>{change 2}</li>
  <li>{change 3}</li>
</ul>

<p><strong>Install:</strong> <code>/install-plugin {repo-url}</code><br/>
<strong>Repo:</strong> <a href="{repo-url}">{org}/{repo}</a><br/>
<strong>Tracking:</strong> <a href="{ticket-url}">{ticket-id}</a></p>
```

Plaintext `body`:

```
Release: {skill} v{version}
{one-sentence summary}.

What's new:
- {change 1}
- {change 2}
- {change 3}

Install: /install-plugin {repo-url}
Repo: {repo-url}
Tracking: {ticket-id} {ticket-url}
```

## New skill announcement

```html
<p>πŸ€– <strong>New skill:</strong> <code>{skill}</code> v{version}</p>
<p>{problem this skill solves, in one sentence}.</p>

<p><strong>What it does:</strong></p>
<ul>
  <li>{capability 1}</li>
  <li>{capability 2}</li>
</ul>

<p><strong>What it prevents:</strong></p>
<ul>
  <li><code>{blocked-command}</code> β€” {why}</li>
</ul>

<p><strong>Install:</strong> <code>/install-plugin {repo-url}</code></p>
```

## Weekly digest (text version β€” but consider a card image)

```html
<p>πŸ“‹ <strong>Skill ecosystem update</strong> β€” releases since {date-range}</p>

<p><strong>New skills this week:</strong></p>
<ul>
  <li><code>{skill}</code> v{version} β€” {one-line description}</li>
</ul>

<p><strong>Releases ({n} repos):</strong></p>
<ul>
  <li><code>{skill}</code> v{version} β€” {what changed}</li>
</ul>

<p><strong>Patches:</strong></p>
<ul>
  <li><code>{skill}</code> v{version}</li>
</ul>
```

For more than ~6 lines of releases, render `templates/weekly-digest.html` to PNG and post that instead.

## Heads-up / breaking change

```html
<p>⚠️ <strong>Heads-up:</strong> <code>{skill}</code> v{version} β€” {what breaks}</p>
<p>{one-sentence why}.</p>

<p><strong>What changes:</strong> {concrete behavior diff}.</p>
<p><strong>Migration:</strong> {steps the reader must take}.</p>
<p><strong>Timeline:</strong> {when old behavior goes away}.</p>
<p><strong>Help:</strong> <a href="{thread-or-issue}">{ticket-id}</a></p>
```

## Maintenance progress (one per phase, incident and resolution)

A window room is read by people who are not in your terminal. They need to know,
per message: which ticket, what state, whether it affects them, and what happens
next. In that order, and skimmable in about five seconds.

```html
<p>{πŸ”§|βœ…|β›”|↩️} <a href="{ticket-url}">{TICKET-KEY}</a> β€” <strong>{RUNNING|DONE|BLOCKED|ROLLED BACK}</strong>: {what, in one clause}</p>
<p><strong>Impact:</strong> {who notices what, or "none"}.</p>
<p><strong>Next:</strong> {the next step and roughly when}.</p>
<p><strong>Output:</strong></p>
<pre><code>{gate output, HTML-escaped, trimmed to the lines that carry the verdict}</code></pre>
```

`<details>`/`<summary>` are on the Matrix allow-list (`html-subset.md`) and Element web renders them as a collapsible block, so a long output may go inside `<details>` below the state line. The state, impact and next step stay outside it, and the output is trimmed either way: collapsing does not shorten the `body` fallback or the notification.

**Escape the output before it goes into `formatted_body`.** `<`, `&` and a literal `</pre>` in a log line are parsed as markup and break the block β€” and gate output is exactly where those appear. The plaintext `body` fallback stays unescaped.

Every ticket, MR and tag is a link. A bare key is a lookup you have handed to
the reader; one window produced six messages naming 26 keys with zero links.

Anti-patterns this template exists to prevent, all observed in one window:

- **Opening with a tool tally.** `PLAY RECAP … ok=14 changed=2` as line one tells
  a colleague nothing. The state token does.
- **The 3000-character wall.** If it does not fit the shape above, it is a
  ticket comment, not a room message β€” post the comment and link it.
- **Silence between the announcement and the result.** A phase that starts gets
  a message; the same phase ending gets another. The room was silent through
  56 % of that session, including the riskiest action of the night.
- **Announcing an expected state.** Say what you measured. One announcement
  claimed a service was live on its new path; the measurement that contradicted
  it arrived 1h46m later.
- **Correcting yourself in a new message.** Edit the original
  (`matrix-edit-e2ee.py`) so a reader arriving later sees one true version
  rather than reconstructing which of two stands.

## Postmortem

```html
<p>πŸ”₯ <strong>Postmortem:</strong> {what failed} on {date}</p>
<blockquote>
  <p><strong>Impact:</strong> {who was affected, for how long}.</p>
</blockquote>

<p><strong>Symptom:</strong> {observed behavior}.</p>
<p><strong>Cause:</strong> {root cause in one sentence}.</p>
<p><strong>Fix:</strong> {what was done}.</p>
<p><strong>Follow-up:</strong> <a href="{ticket}">{ticket-id}</a></p>
```

## Findings (investigation / audit result)

Headings name the category of finding, never who was wrong. One `<li>` per finding, however long the item runs.

```html
<p>πŸ”Ž <strong>Findings:</strong> {what was checked}</p>
<p>{one-sentence verdict: what ran, how much of it worked}.</p>

<p><strong>Errors found:</strong></p>
<ul>
  <li><strong>{subject}</strong> β€” {what fails}: <code>{error}</code>. {consequence}.</li>
  <li><strong>{subject}</strong> β€” {what fails}. {cause, with a link to the line}.</li>
</ul>

<p><strong>No error, expected behavior:</strong></p>
<ul>
  <li><strong>{subject}</strong> β€” {why it looked broken but is not}.</li>
</ul>

<p><strong>Next steps:</strong></p>
<ul>
  <li>{action}, tracked in <a href="{ticket}">{ticket-id}</a>.</li>
</ul>
```

## RFC

```html
<p>πŸ”¬ <strong>RFC:</strong> {proposal title}</p>
<p>{one-sentence problem statement}.</p>

<p><strong>Why:</strong> {motivation}.</p>
<p><strong>How:</strong> {sketch of the approach}.</p>
<p><strong>Try it:</strong> <code>{command or branch}</code></p>
<p><strong>Feedback by:</strong> {date}, in <a href="{thread}">this thread</a>.</p>
```

## Patch (bugfix-only)

```html
<p>πŸš‘ <strong>Patch:</strong> <code>{skill}</code> v{version}</p>
<p>{one-sentence bug summary}.</p>
<p><strong>Fixed:</strong> {what was wrong} β†’ {what is now correct}.<br/>
<strong>Affected:</strong> {who needs to upgrade}.</p>
```
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