gitshot — Upload Images to GitHub
Upload images from terminal and get markdown-ready URLs for GitHub issues, PRs, and comments.
When to Use This Skill
- User asks to "upload", "attach", or "embed" an image/screenshot to a GitHub PR or issue
- A workflow produces screenshots or images that need to go into a PR comment or issue body
- User asks for a "visual diff", "before/after", or "screenshot" in a PR
- User says "add image to PR", "attach screenshot to issue", or similar
- You have taken a screenshot and need to include it in GitHub markdown
Quick Reference
# Upload one image — returns markdown
npx gitshot screenshot.png
# → 
# Upload and comment on a PR (most common agent workflow)
npx gitshot screenshot.png | gh pr comment <PR_NUMBER> --body-file -
# Upload and create an issue with image
npx gitshot bug.png | gh issue create --title "Bug report" --body-file -
# Upload multiple images
npx gitshot before.png after.png
# Get raw URL only (for embedding in larger text)
npx gitshot --raw screenshot.png
# JSON output (structured, for programmatic use)
npx gitshot --json screenshot.png
# → {"url":"...","markdown":"","filename":"...","backend":"release"}
How It Works
- If
gh CLI is authenticated (most common): Uploads to <user>/gitshot-images repo as a GitHub Release Asset. Creates the repo automatically on first use.
- If no
gh CLI: Falls back to catbox.moe (free, no signup).
- Optional: Set
CLOUDINARY_URL or IMGBB_API_KEY env vars for those backends.
Common Agent Workflows
Screenshot → PR Comment
# Take screenshot on macOS, upload, comment on PR
screencapture -x /tmp/shot.png
npx gitshot /tmp/shot.png | gh pr comment 42 --body-file -
Visual Diff in PR Description
BEFORE=$(npx gitshot --raw before.png)
AFTER=$(npx gitshot --raw after.png)
echo "## Visual Diff\n| Before | After |\n|--------|-------|\n|  |  |" | gh pr comment 42 --body-file -
Upload Image and Get URL for Manual Embedding
URL=$(npx gitshot --raw diagram.png)
# Now use $URL anywhere in markdown text
Create Issue with Screenshot
BODY=$(npx gitshot bug.png)
gh issue create --title "UI Bug: Button misaligned" --body "$BODY"
Important Notes
- stdout contains ONLY the URL or markdown (pipe-safe)
- stderr contains status messages (backend name, progress)
- Exit code 0 = success, 1 = failure
- Supported formats: PNG, JPG, JPEG, GIF, SVG, WebP, BMP, ICO, TIFF, AVIF
- First run with release backend auto-creates
<user>/gitshot-images repo (one-time)
- Privacy: The release backend uploads to a PUBLIC repo. Do not upload sensitive images (credentials, internal dashboards). Use Cloudinary or imgbb for sensitive content.
1---2name: gitshot3description: Upload screenshots and images to GitHub, returning markdown-ready URLs for PRs, issues, and comments. Use when needing to attach images to GitHub PRs/issues, upload screenshots, embed visuals in markdown, or when a workflow produces images that should be shared on GitHub. Trigger words - upload image, attach screenshot, add image to PR, embed screenshot, visual diff, before/after screenshot.4license: MIT5---67# gitshot — Upload Images to GitHub89Upload images from terminal and get markdown-ready URLs for GitHub issues, PRs, and comments.1011## When to Use This Skill1213- User asks to "upload", "attach", or "embed" an image/screenshot to a GitHub PR or issue14- A workflow produces screenshots or images that need to go into a PR comment or issue body15- User asks for a "visual diff", "before/after", or "screenshot" in a PR16- User says "add image to PR", "attach screenshot to issue", or similar17- You have taken a screenshot and need to include it in GitHub markdown1819## Quick Reference2021```bash22# Upload one image — returns markdown23npx gitshot screenshot.png24# → 2526# Upload and comment on a PR (most common agent workflow)27npx gitshot screenshot.png | gh pr comment <PR_NUMBER> --body-file -2829# Upload and create an issue with image30npx gitshot bug.png | gh issue create --title "Bug report" --body-file -3132# Upload multiple images33npx gitshot before.png after.png3435# Get raw URL only (for embedding in larger text)36npx gitshot --raw screenshot.png3738# JSON output (structured, for programmatic use)39npx gitshot --json screenshot.png40# → {"url":"...","markdown":"","filename":"...","backend":"release"}41```4243## How It Works44451. **If `gh` CLI is authenticated** (most common): Uploads to `<user>/gitshot-images` repo as a GitHub Release Asset. Creates the repo automatically on first use.462. **If no `gh` CLI**: Falls back to catbox.moe (free, no signup).473. **Optional**: Set `CLOUDINARY_URL` or `IMGBB_API_KEY` env vars for those backends.4849## Common Agent Workflows5051### Screenshot → PR Comment52```bash53# Take screenshot on macOS, upload, comment on PR54screencapture -x /tmp/shot.png55npx gitshot /tmp/shot.png | gh pr comment 42 --body-file -56```5758### Visual Diff in PR Description59```bash60BEFORE=$(npx gitshot --raw before.png)61AFTER=$(npx gitshot --raw after.png)62echo "## Visual Diff\n| Before | After |\n|--------|-------|\n|  |  |" | gh pr comment 42 --body-file -63```6465### Upload Image and Get URL for Manual Embedding66```bash67URL=$(npx gitshot --raw diagram.png)68# Now use $URL anywhere in markdown text69```7071### Create Issue with Screenshot72```bash73BODY=$(npx gitshot bug.png)74gh issue create --title "UI Bug: Button misaligned" --body "$BODY"75```7677## Important Notes7879- stdout contains ONLY the URL or markdown (pipe-safe)80- stderr contains status messages (backend name, progress)81- Exit code 0 = success, 1 = failure82- Supported formats: PNG, JPG, JPEG, GIF, SVG, WebP, BMP, ICO, TIFF, AVIF83- First run with release backend auto-creates `<user>/gitshot-images` repo (one-time)84- **Privacy:** The release backend uploads to a PUBLIC repo. Do not upload sensitive images (credentials, internal dashboards). Use Cloudinary or imgbb for sensitive content.
vipulgupta2048