Skip to content

netresearch/matrix-skill / skills/matrix-announcement

matrix-announcement

Unverified

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/image-cards.md

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

# When to render an HTML card to PNG

`formatted_body` is fine for prose, lists and short tables. It is **bad** at:

- Comparisons (matrix client X vs Y, before/after, plan tiers)
- Dashboards (test counts, coverage deltas, dependency health)
- Timelines (release calendar, incident timeline)
- Anything with column alignment beyond ~3 columns
- Anything that needs color-coded status pills, badges, or icons
- Hero / announce cards for major releases where visual identity helps the message survive scrolling

For these: **design an HTML card → render to PNG headlessly → upload to the homeserver → post as `m.image`**. The plaintext `body` becomes the searchable fallback.

## The recipe

`--window-size` must match the chosen template's design dimensions and the `info.w`/`info.h` you send in the `m.image` event below — otherwise the screenshot is cropped or letterboxed and the metadata lies. The shipped templates are:

- `release-card.html` → `1200,630`
- `weekly-digest.html` → `1200,1500`
- `comparison.html` → `1200,900`

```bash
# 1. Render — substitute the template's WIDTH,HEIGHT for the --window-size
W=1200; H=630   # release-card.html dimensions
chromium --headless=new \
  --disable-gpu \
  --hide-scrollbars \
  --window-size=$W,$H \
  --screenshot=card.png \
  --default-background-color=00000000 \
  "file://$(pwd)/card.html"

# 2. Upload to homeserver → mxc:// URI
MXC=$(curl -s -X POST \
  -H "Authorization: Bearer $MATRIX_TOKEN" \
  -H "Content-Type: image/png" \
  --data-binary @card.png \
  "$HOMESERVER/_matrix/media/v3/upload?filename=card.png" \
  | jq -r .content_uri)

# 3. Send m.image (file size via wc -c so it works on both Linux and macOS;
#    `stat -c%s` is GNU-only, `stat -f%z` is BSD-only — wc -c < FILE is portable).
#    The transaction ID has to be unique per device and endpoint; date plus
#    8 bytes from /dev/urandom need no package (uuidgen is not on every host).
SIZE=$(wc -c < card.png | tr -d ' ')
curl -s -X PUT \
  -H "Authorization: Bearer $MATRIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{
    \"msgtype\": \"m.image\",
    \"body\": \"github-release-skill v0.2.0 — release card\",
    \"url\": \"$MXC\",
    \"info\": {
      \"mimetype\": \"image/png\",
      \"w\": $W,
      \"h\": $H,
      \"size\": $SIZE
    }
  }" \
  "$HOMESERVER/_matrix/client/v3/rooms/$ROOM/send/m.room.message/$(date +%s)-$(od -An -N8 -tx1 /dev/urandom | tr -d ' \n')"

# 4. Follow with the text/links nobody can copy from an image.
#    ${CLAUDE_SKILL_DIR} is substituted by Claude Code to the active skill's
#    directory; the matrix-communication scripts live one directory up.
#    Do NOT quote it — it is a literal substitution, not a shell variable.
uv run ${CLAUDE_SKILL_DIR}/../matrix-communication/scripts/matrix-send-e2ee.py "$ROOM" \
  '**Install:** `/install-plugin https://github.com/netresearch/github-release-skill`'
```

> **Note:** `m.notice` is a *text* msgtype — there is no notice-flavoured `m.image`. For text-only announcements that should be unreplyable by other bots, pass `--notice` to `matrix-send-e2ee.py`. For an image announcement that should still be skipped by auto-replying bots, send the card as `m.image` (the recipe above) and then a follow-up `m.text` via `matrix-send-e2ee.py … --notice` carrying the install command and links — bots that respect `m.notice` will then ignore the whole announcement, since they ignore the text and the image is wordless.

## Why "design HTML, render to PNG" beats "have the LLM make an image"

- HTML/CSS gives pixel-precise control over typography, spacing, color
- The same template renders deterministically every week — diffs are obvious, regressions catchable
- Coding agents are excellent at writing HTML and bad at generating rasters; lean into the strength
- Templates are reviewable code (`templates/release-card.html`), not disposable prompts

## Three templates

| Template | Use for | Size |
| --- | --- | --- |
| `templates/release-card.html` | single-skill release announcements | 1200×630 |
| `templates/weekly-digest.html` | multi-skill weekly roundups | 1200×1500 |
| `templates/comparison.html` | before/after, vs-tables, migration deltas | 1200×900 |

Each is a self-contained HTML file with `{{PLACEHOLDER}}` substitutions the calling skill replaces before rendering. Open `gallery.html` for a live preview.

## Always pair the image with text

An `m.image` event alone is hostile to:

- screen-reader users
- mobile users on metered connections
- anyone scrolling search results
- anyone trying to copy the install command

Either set the image's `body` to the full plaintext fallback the announcement would have been, **or** send the card and immediately follow with a short `m.text` containing the links and commands.

```json
{
  "msgtype": "m.image",
  "body": "Release: github-release-skill v0.2.0\n\nWhat's new:\n- detects ecosystem & bumps versions\n- signed annotated tags only\n- rewrites release notes into narrative\n\nInstall: /install-plugin https://github.com/netresearch/github-release-skill\nRepo: https://github.com/netresearch/github-release-skill",
  "url": "mxc://example.com/abc123…",
  "info": { "w": 1200, "h": 630, "mimetype": "image/png", "size": 184223 }
}
```
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