amitray007amitray007/headroom/.agents/skills/pr-showcase/SKILL.md

pr-showcase

Skill83 starsChanged 12 days agoMITView on GitHub

Fill the Showcase section of a Headroom pull request so a reviewer sees the change before reading code. Use when opening or updating a pull request that changes web or Mac views, server, connector, package or HeadroomKit behaviour.

Commits and pushes

In this repository6 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- app-api-compatibilitySkill
- pr-ciSkill
- provider-connectorSkill
- verify-webSkill

The file

We split this skill into the rules it gives an agent

3 rules. About 0 are common, 1 is distinctive, and 2 are very specific to this project.

≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.

Common
Distinctive
Very specific

Very specific:
Every pull request that changes the interface or behaviour carries evidence under ## Showcase in its description.
line 8
Distinctive:
Put the pair in a table so before and after sit side by side:
line 27
Very specific:
Every image or video opens from the description, and its alt text names the view and whether it is before or after.
line 53

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.

Files

SKILL.md

PR showcase

Every pull request that changes the interface or behaviour carries evidence under ## Showcase in its description. The rule and its reason are D50; the contributor version is CONTRIBUTING.md.

Evidence uses synthetic data only: Demo Mode, the static demo build, test fixtures. A capture with a real account, token, email address or provider response never leaves the machine.

Visual change: before and after

Build and serve the static demo twice, from the pull request's base in a temporary worktree (before: git merge-base HEAD origin/<base branch>, so a stacked pull request shows only its own layer) and from the branch (after), as the verify web skill describes.
Capture the same view in both builds: desktop width 1280 and phone width 390, in the theme the change touches. Name each file <branch-slug>-<view>-<width>-<theme>-before.png or -after.png, so no capture overwrites another.
For a change in motion or a flow across views, record a short video of the after build instead of the screenshots.
Upload to the pr-media prerelease, which holds description media only:
```
gh release view pr-media >/dev/null 2>&1 || gh release create pr-media --prerelease --latest=false \
  --title "PR media" --notes "Images for pull request descriptions. Not a release."
gh release upload pr-media <files> --clobber
```
Each file is then at https://github.com/amitray007/headroom/releases/download/pr-media/<file>. The release stays a prerelease and never latest: the installer, headroom update and mise read releases/latest.

Put the pair in a table so before and after sit side by side:

| Before | After |
| --- | --- |
| <img alt="Before: card" src="…/pr-media/x-card-before.png"> | <img alt="After: card" src="…/pr-media/x-card-after.png"> |

A Mac view change (apps/macos/Headroom, Widgets, Shared) is captured by the owner, who tests the Mac app. Write Recording: owner to attach under Showcase and say so in the hand-off.

Behaviour change: what was wrong, what happens now

Lead with a figure, then one or two sentences. Choose by what changed:

What changed	Evidence
A flow, an order of calls, a new fallback or state	A `mermaid` flowchart or sequence diagram, old path and new path
A number: time, memory, request count, size	A table with before, after and how it was measured
An API answer or parsed value	The request and the response before and after, from a synthetic fixture, in a fenced block
A bug	The failing test output before the fix and the passing output after, trimmed to the lines that matter

GitHub renders a fenced mermaid block in the description; keep a diagram under about 12 nodes.

Done when

Showcase holds the evidence the table in CONTRIBUTING asks for: a recording or a before and an after image for a view change; a diagram, table or code block for a behaviour change.
Every image or video opens from the description, and its alt text names the view and whether it is before or after.
Nothing in the evidence comes from a real account.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

It worked
Partly
It didn't

What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free