Skip to content

Rallly is an open-source scheduling and collaboration tool designed to make organizing events and meetings easier.

🔧 Add a pr-screenshots skill that hosts images outside the PR branch (#3433)

Luke Vellafc0b0cf86f2a
diff --git a/.claude/skills/pr-screenshots/SKILL.md b/.claude/skills/pr-screenshots/SKILL.md
new file mode 100644
index 000000000..983909e13
--- /dev/null
+++ b/.claude/skills/pr-screenshots/SKILL.md
@@ -0,0 +1,31 @@
+---
+name: pr-screenshots
+description: Add screenshots of a visual change to a pull request description without pushing commits to the PR branch. Use whenever a PR needs screenshots, before/after images, or any image in its body.
+---
+
+# PR screenshots
+
+Never commit screenshots to the PR branch. Every push there reruns CI and redeploys Vercel previews just to add images.
+
+Images go to `refs/meta/pr-assets` on origin instead, one folder per PR. It is a custom ref, not a branch: GitHub Actions only run for `main` and pull requests, and Vercel deploys every pushed branch (`refs/heads/*`), so neither sees it. An orphan `pr-assets` branch would not work, because Vercel would try and fail to build it. Keep the ref two levels deep: GitHub accepts a single-level `refs/pr-assets` once, then rejects every push to it with "cannot lock ref"; only `gh api -X DELETE repos/<owner>/<repo>/git/refs/pr-assets` removes it.
+
+## Steps
+
+1. **Capture.** Crop to the surface that changed, at a size where the text is legible. Show dark and light mode when the change has colour. Use a before/after pair when replacing something, a single shot for new UI. Crop with `sips -s format png --cropOffset <y> <x> -c <height> <width> <in> --out <out>.png`.
+2. **Confirm.** Send the images to the user in chat and wait for approval before uploading. Tweaks after upload mean another upload.
+3. **Upload.** From any checkout of the repo:
+
+ ```bash
+ .claude/skills/pr-screenshots/upload.sh <pr-number> <file>...
+ ```
+
+ It prints one `raw.githubusercontent.com` URL per file, pinned to the upload commit, and exits non-zero if a URL does not serve.
+4. **Edit the body.** Add a `## Screenshots` section above the checklist with `gh pr edit <pr-number> --body-file <file>`. Editing the body does not rerun CI. Put dark and light side by side:
+
+ ```markdown
+ | Dark | Light |
+ | -- | -- |
+ | ![Notify step, dark mode](<url>) | ![Notify step, light mode](<url>) |
+ ```
+
+Re-uploading a file with the same name is fine: the new URL carries the new commit, and old URLs keep serving the old image.
diff --git a/.claude/skills/pr-screenshots/upload.sh b/.claude/skills/pr-screenshots/upload.sh
new file mode 100755
index 000000000..d91656c0b
--- /dev/null
+++ b/.claude/skills/pr-screenshots/upload.sh
@@ -0,0 +1,72 @@
+#!/usr/bin/env bash
+# Uploads files to refs/meta/pr-assets on origin and prints a commit-pinned raw URL
+# for each. Usage: upload.sh <pr-number> <file>...
+#
+# refs/meta/pr-assets is not a branch, so the push triggers neither GitHub Actions
+# nor Vercel. A temporary index keeps the worktree and branch untouched.
+set -euo pipefail
+
+if [ "$#" -lt 2 ]; then
+ echo "usage: $0 <pr-number> <file>..." >&2
+ exit 1
+fi
+
+REF=refs/meta/pr-assets
+pr="$1"
+shift
+
+# Files land at <pr>/<basename>, so two inputs with one name would collide.
+duplicates=$(for file in "$@"; do basename "$file"; done | sort | uniq -d)
+if [ -n "$duplicates" ]; then
+ echo "duplicate file names: $duplicates" >&2
+ exit 1
+fi
+
+urlencode() {
+ local LC_ALL=C s="$1" out="" c i
+ for ((i = 0; i < ${#s}; i++)); do
+ c="${s:i:1}"
+ case "$c" in
+ [A-Za-z0-9._~-]) out+="$c" ;;
+ # printf reads bytes above 0x7F as negative; mask back to one byte.
+ *) out+=$(printf '%%%02X' $(($(printf '%d' "'$c") & 255))) ;;
+ esac
+ done
+ printf '%s' "$out"
+}
+
+repo=$(gh repo view --json nameWithOwner -q .nameWithOwner)
+git fetch -q origin "+$REF:$REF" 2>/dev/null || true
+
+export GIT_INDEX_FILE
+GIT_INDEX_FILE=$(mktemp)
+trap 'rm -f "$GIT_INDEX_FILE"' EXIT
+
+parent=()
+if git rev-parse -q --verify "$REF" >/dev/null; then
+ git read-tree "$REF"
+ parent=(-p "$(git rev-parse "$REF")")
+else
+ git read-tree --empty
+fi
+
+for file in "$@"; do
+ blob=$(git hash-object -w "$file")
+ git update-index --add --cacheinfo "100644,$blob,$pr/$(basename "$file")"
+done
+
+tree=$(git write-tree)
+# macOS ships bash 3.2, where an empty array is unbound under set -u.
+commit=$(git commit-tree "$tree" ${parent[@]+"${parent[@]}"} -m "PR #$pr assets")
+git update-ref "$REF" "$commit"
+git push -q origin "$REF:$REF"
+
+for file in "$@"; do
+ url="https://raw.githubusercontent.com/$repo/$commit/$pr/$(urlencode "$(basename "$file")")"
+ status=$(curl -s -o /dev/null -w "%{http_code}" "$url")
+ if [ "$status" != "200" ]; then
+ echo "$url returned $status" >&2
+ exit 1
+ fi
+ echo "$url"
+done