screenshots

name	screenshots
description	Locate macOS screenshots saved to ~/screenshots/ and route them into downstream workflows — most commonly attaching to GitHub PR/issue/comment bodies via the gh image extension, but also useful for previewing, organizing, copying to clipboard, or feeding into other tools. Use when the user mentions "screenshots", "today's screenshots", "find a screenshot", "attach screenshots", "upload screenshot", "images on machine", or wants to locate, preview, or share a local screenshot.
license	MIT
compatibility	opencode
metadata	{"scope":"global","tools":"bash"}

Screenshots

Local macOS screenshots are saved to ~/screenshots/. This skill covers locating them and using them in downstream workflows. The most detailed workflow is uploading to GitHub via gh image, but the skill also applies to previewing, sharing via other channels, and basic housekeeping.

One-time setup (per machine)

Verify before assuming:

# 1. macOS screenshot location is ~/screenshots/ (not Desktop)
defaults read com.apple.screencapture location
# expected: /Users/<you>/screenshots

# If empty or pointing at Desktop, set it once:
mkdir -p ~/screenshots
defaults write com.apple.screencapture location ~/screenshots
killall SystemUIServer

# 2. gh CLI authenticated (for the GitHub workflow below)
gh auth status

# 3. gh-image extension installed (one-time)
gh extension list | grep -q 'drogers0/gh-image' || gh extension install drogers0/gh-image

Per-day subdirs are not used by default — the filename already embeds the date (Screenshot 2026-05-21 at 10.38.18.png), so a flat dir keeps the workflow simple. If sorting ever becomes painful, layer on a Folder Action, launchd watcher, or Hazel rule.

Finding screenshots

# Listing (human-readable, today's only)
ls -lt ~/screenshots/ | grep "$(date +%Y-%m-%d)"

# Full paths (for piping into other commands)
ls ~/screenshots/Screenshot\ "$(date +%Y-%m-%d)"*.png

# All recent (last 24h, any filename)
find ~/screenshots/ -type f -mtime -1

Filename format is Screenshot YYYY-MM-DD at HH.MM.SS.png. Time separator may be . (Norwegian locale) or : (English locale) — prefer globs that don't depend on it.

Workflow: attach to a GitHub PR / issue / comment

The command

# Run from inside the target repo so origin is auto-detected:
gh image ~/screenshots/Screenshot\ 2026-05-21\ at\ 10.38.18.png \
         ~/screenshots/Screenshot\ 2026-05-21\ at\ 12.23.18.png

# Or pass --repo explicitly:
gh image --repo owner/repo ~/screenshots/...

Output is one ![filename](https://github.com/user-attachments/assets/...) line per upload. Capture stdout and paste into the target body.

End-to-end: attaching today's screenshots to a PR

1. Find the candidate files, newest first:

   ls -t ~/screenshots/Screenshot\ "$(date +%Y-%m-%d)"*.png
   

2. Read every candidate before uploading. Use the Read tool on each file (start with the most recent — those are usually the "for this PR" captures, while older ones in the same day are often unrelated work). For each one, decide:

   • Keep if it shows the change the PR is about (before/after states, mobile/desktop views, the bug being fixed, the feature in action)
   • Drop if it's a throwaway: code diffs already visible in Files Changed, scratch debug shots, accidental captures, screenshots from other unrelated work earlier in the day
   • Label the keepers with one short phrase (e.g. "Empty state on mobile", "Toast after save") — you'll use these as sub-headings in the PR body

   Never upload blind. An unfiltered batch dump pollutes the PR and forces reviewers to guess what each image is showing.

3. Upload only the keepers:

   gh image ~/screenshots/Screenshot\ 2026-05-21\ at\ 12.23.18.png \
            ~/screenshots/Screenshot\ 2026-05-21\ at\ 12.23.44.png
   

4. Fetch the current PR body, append a ## Screenshots section pairing each label with its returned markdown URL, then write back:

   gh pr view <num> --json body -q .body > /tmp/pr-body.md
   cat >> /tmp/pr-body.md <<'EOF'
   
   ## Screenshots
   
   ### <label for image 1>
   ![…](https://github.com/user-attachments/assets/…)
   
   ### <label for image 2>
   ![…](https://github.com/user-attachments/assets/…)
   EOF
   gh pr edit <num> --body-file /tmp/pr-body.md
   

Same flow works for issues (gh issue view, gh issue edit) and for posting as a comment (gh pr comment <num> --body-file ...).

Other workflows

• Preview / label — feed paths to the Read tool to identify content before using them anywhere.
• Copy path to clipboard — echo -n /path/to/file.png | pbcopy to paste into Slack, Teams, email, or design tools.
• Cleanup old files — find ~/screenshots/ -mtime +30 -name '*.png' -delete removes screenshots older than 30 days.
• Pre-process before sharing — sips, ImageMagick, or pngquant for cropping, resizing, or compressing.
• Reference in local markdown — drop a relative or absolute path into Obsidian / scratch notes.

Tips

• Group related shots with markdown sub-headings (### Mobile, ### Desktop) instead of dumping a raw list.
• Skip code-diff screenshots when the diff is already visible in the PR's Files Changed tab — they add noise.
• Reuse upload URLs. gh image returns CDN-backed URLs that work in any GitHub markdown surface (PRs, issues, comments, gists, Discussions).
• Filenames with spaces must be backslash-escaped or quoted — the macOS default format includes spaces.

Troubleshooting

Symptom	Fix
gh: image: unknown command	gh extension install drogers0/gh-image
401 / authentication required	gh auth login (the token used by gh image is the gh session token, not a PAT)
Wrong repo detected	Add --repo owner/repo or cd into the repo first
Filename glob misses today's files	Confirm defaults read com.apple.screencapture location matches ~/screenshots/