upload-screenshot

Upload Screenshot

Upload images to GitHub via release assets and get back stable, embeddable URLs. This is the recommended way to share screenshots of frontend changes, UI diffs, or any visual artifacts in PR comments and issue descriptions.

Important: Always upload to the fork repo, not upstream, to avoid polluting upstream releases.

When to Use This Skill

Use this skill when you:

• Have taken a screenshot of a frontend/UI change and need to show it in a PR
• Need to attach visual evidence (error screenshots, UI comparisons) to a GitHub issue or PR comment
• Want to embed an image in any GitHub markdown context (PR description, comment, issue)
• Are working in an agentic workflow and need to share visual output

Prerequisites

1. gh CLI: Authenticated with gh auth login
2. Repository write access: The gh token must have permission to create releases on the target repo

Implementation

Upload a screenshot

bash "${CLAUDE_PLUGIN_ROOT}/skills/upload-screenshot/upload_screenshot.sh" \
  --file /path/to/screenshot.png \
  --repo owner/fork-repo

Upload with a custom title

bash "${CLAUDE_PLUGIN_ROOT}/skills/upload-screenshot/upload_screenshot.sh" \
  --file /path/to/screenshot.png \
  --repo owner/fork-repo \
  --title "Login page after dark mode changes"

Parameters

Parameter	Required	Description
--file	Yes	Path to the image file (png, jpg, gif, svg, webp)
--repo	No	Target GitHub repository in owner/repo format (defaults to $FORK_REPO env var)
--title	No	Alt text for the image (defaults to filename)
--token-file	No	Path to a file containing a GitHub token to use for auth

When --token-file is provided, the token is loaded into GITHUB_TOKEN for the duration of the script. This is useful in CI where the default GITHUB_TOKEN may not have write access to the target repo.

Environment variable defaults: If --repo is not provided, the script uses $FORK_REPO. If no explicit token is provided via --token-file, the script uses $GH_FORK_TOKEN when available. This means in CI environments where these env vars are set, you can call the script with just --file and it will upload to the correct fork with the right credentials.

Output

JSON on stdout:

{
  "url": "https://github.com/owner/fork-repo/releases/download/screenshot-1719100000-a1b2c3d4/screenshot.png",
  "markdown": "![Login page](https://github.com/owner/fork-repo/releases/download/screenshot-1719100000-a1b2c3d4/screenshot.png)",
  "tag": "screenshot-1719100000-a1b2c3d4",
  "repo": "owner/fork-repo"
}

Embedding in a PR comment

After uploading, use the markdown field directly in a gh pr comment:

result=$(bash "${CLAUDE_PLUGIN_ROOT}/skills/upload-screenshot/upload_screenshot.sh" \
  --file /tmp/screenshot.png --repo owner/fork-repo --title "UI change")

markdown=$(echo "$result" | jq -r '.markdown')
gh pr comment 123 --repo owner/upstream-repo --body "## Screenshot

$markdown"

How It Works

1. Creates a GitHub prerelease with a unique tag (screenshot-<timestamp>-<random>)
2. Attaches the image file as a release asset
3. Extracts the browser_download_url from the GitHub API
4. Returns the URL in both raw and markdown-formatted forms

The release is marked as a prerelease and tagged with a screenshot- prefix for easy identification and cleanup.

Cleanup

Screenshot releases accumulate over time. To clean up old uploads:

# Delete a specific screenshot release
gh release delete screenshot-1719100000-a1b2c3d4 --yes --cleanup-tag --repo owner/fork-repo

# Delete all screenshot releases older than 30 days
gh api "repos/owner/fork-repo/releases" --paginate --jq \
  '.[] | select(.tag_name | startswith("screenshot-")) | select(.prerelease) | .tag_name' | \
  while read -r tag; do
    gh release delete "$tag" --yes --cleanup-tag --repo owner/fork-repo
  done

Limitations

• URLs are only accessible as long as the release exists
• For private repos, viewers must have repo access to see the images
• GitHub release asset size limit is 2 GB per file
• Creates one release per upload (use cleanup to manage volume)

Error Handling

Error	Cause	Resolution
Missing required arguments	--file or --repo not provided	Provide both required arguments
File not found	Image path doesn't exist	Check the file path
Failed to create release	Auth or permission issue	Run gh auth login or check repo access
Failed to retrieve asset URL	Release created but asset missing	Retry; the release is auto-cleaned on failure

See Also

• GitHub Releases API: https://docs.github.com/en/rest/releases
• gh release create docs: https://cli.github.com/manual/gh_release_create