Skip to content

Commit 36d7dbd

Browse files
authored
feat: desktop-screenshot skill to stop agents uploading relay media to PRs (#862)
1 parent c10b4f8 commit 36d7dbd

6 files changed

Lines changed: 106 additions & 0 deletions

File tree

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../../../desktop/src-tauri/src/managed_agents/screenshot_skill.md
Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../../../desktop/src-tauri/src/managed_agents/screenshot_skill.md
Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../../../desktop/src-tauri/src/managed_agents/screenshot_skill.md
Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../../../desktop/src-tauri/src/managed_agents/screenshot_skill.md

‎AGENTS.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -224,6 +224,11 @@ See [TESTING.md](TESTING.md) for the full multi-agent E2E guide.
224224

225225
### Desktop Screenshots (Playwright)
226226

227+
> **Do NOT use `sprout upload`, the relay media endpoint, or any third-party
228+
> image host for PR screenshots.** Relay media URLs fail through GitHub's camo
229+
> proxy. Always use `scripts/post-screenshots.sh` — see the `desktop-screenshot`
230+
> skill for the full workflow.
231+
227232
The desktop app requires the E2E mock bridge to render — it cannot run in a plain
228233
browser. Use `just desktop-screenshot` to capture screenshots (builds frontend,
229234
starts preview server, runs Playwright automatically):
Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
---
2+
name: desktop-screenshot
3+
description: >
4+
Capture desktop app screenshots and post them to GitHub PRs with immutable URLs.
5+
version: 1
6+
---
7+
8+
# Desktop Screenshot Skill
9+
10+
## CRITICAL: How to Host Screenshots for PRs
11+
12+
**NEVER use `sprout upload`, the relay media endpoint, or any third-party image
13+
host (imgur, imgbb, etc.) for PR screenshots.** Relay media URLs fail through
14+
GitHub's camo proxy (`Non-Image content-type returned`). External hosts are
15+
unreliable and may expose content.
16+
17+
**ALWAYS use `scripts/post-screenshots.sh`** — it hosts PNGs on a per-developer
18+
git branch with immutable commit-SHA URLs that render correctly on GitHub.
19+
20+
## Step 1 — Capture Screenshots
21+
22+
`just desktop-screenshot` builds the frontend, starts a preview server, and
23+
runs Playwright with the mock bridge (no relay needed).
24+
25+
```bash
26+
just desktop-screenshot --name home
27+
just desktop-screenshot --name channel --route /channels/general
28+
just desktop-screenshot --name ctx-menu --right-click channel-random --clip 0,200,320,300
29+
just desktop-screenshot --name sidebar --active-channel general --messages /tmp/msgs.json --clip 0,0,256,720
30+
```
31+
32+
**Flags:** `--name` (filename, required), `--route` (client route), `--active-channel`
33+
(channel to view), `--click`/`--right-click`/`--hover` (interact before capture),
34+
`--clip` (crop as `x,y,w,h`), `--messages` (JSON file), `--wait` (ms, default 2000),
35+
`--viewport` (WxH, default 1280x720), `--outdir` (default `test-results/screenshots`).
36+
37+
Output: PNG path on stdout.
38+
39+
### Injecting Messages
40+
41+
Write a JSON array to a temp file. `channelName` and `content` are required:
42+
43+
```json
44+
[
45+
{"channelName": "random", "content": "Hey check this out", "kind": 40002},
46+
{"channelName": "random", "content": "Another message"}
47+
]
48+
```
49+
50+
Without `--active-channel`, the helper navigates to the message channel (for
51+
showing content). With `--active-channel`, messages can target other channels
52+
while the camera stays put (for unread indicators, badges).
53+
54+
### Available Mock Channels
55+
56+
`general`, `random`, `design`, `sales`, `engineering`, `agents`, `watercooler`,
57+
`announcements`, `alice-tyler`, `bob-tyler`.
58+
59+
`general` has pre-seeded messages (always shows `hasUnread`). Use `engineering`
60+
for "no unread" visual states.
61+
62+
## Step 2 — Post to a PR
63+
64+
```bash
65+
./scripts/post-screenshots.sh <PR-number> test-results/screenshots
66+
./scripts/post-screenshots.sh <PR-number> test-results/screenshots body.md
67+
```
68+
69+
The script pushes images to `agent-screenshots/<github-username>` and posts a
70+
PR comment with `## Screenshots` and all images. Re-runs overwrite that PR's
71+
images only.
72+
73+
### Body Templates
74+
75+
The optional third argument is a markdown file with `{{filename}}` placeholders
76+
(without `.png`). Images not referenced by a placeholder are appended at the end.
77+
78+
```markdown
79+
### Context menu
80+
Right-click shows "Star channel".
81+
82+
{{01-ctx-menu}}
83+
84+
### Starred section
85+
`engineering` appears under Starred.
86+
87+
{{02-starred}}
88+
```
89+
90+
## Gotchas
91+
92+
1. **Stale server** — `reuseExistingServer: true` means a prior build serves old
93+
code. Kill port 4173 and rebuild (`cd desktop && pnpm run build`) after code changes.
94+
2. **Clip for readability** — full 1280x720 screenshots are hard to read for sidebar
95+
features. Sidebar = 256px wide; context menus ~450px.
96+
3. **`post-screenshots.sh` requires `gh` auth** — the script uses `gh api` and
97+
`gh pr comment`. Ensure `gh auth status` succeeds.

0 commit comments

Comments
 (0)