gh-image: Attach Files to GitHub from the CLI
Upload screenshots, PDFs, logs and more straight from the terminal into GitHub issues, PRs, or READMEs, producing canonical user-attachments URLs that stay private on private repos.
SKILL.md's allowed-tools is tightly scoped to gh subcommands and read-only tools; it requires the user to install/authenticate themselves, confirm target repo and files per request, treats PR/issue bodies as untrusted injection sources with isolation markers, and prominently discloses the full-account scope of the session credential with leak-recovery guidance. Deducted: the underlying credential is a password-equivalent user_session cookie (not least privilege), reliance on GitHub's undocumented internal endpoint, and unverified publisher identity — so not full marks.
Instructions are self-consistent with version checks, semantic comparison, failure semantics distinguishing embed failure from upload failure, and a troubleshooting table (SAML, expired sessions); but this is a static review with no execution, and no committed test suite covering the skill's key paths is in evidence, so the anchor forbids scoring above 10.
Trigger descriptions are concrete, capability boundaries are clear (file types beyond --attach, read-only repos, README/commit-message use cases), and Limitations discloses the undocumented-API and session-expiry risks. Deducted: core function depends entirely on GitHub network reachability (unstable from mainland China) with no Chinese-language support stated, and boundary evidence is largely author-asserted.
SKILL.md is well layered (prerequisites → path → confirm → embed → verify → troubleshooting), MIT licensed, with installation notes, architecture docs, a signed release pipeline, SECURITY.md, and a supported-versions policy. Deducted: compatibility field says v1.1.0+ while the body requires v1.4.0+ (inconsistent versioning) and no changelog-level version governance evidence.
Output is a directly pasteable user-attachments reference with a built-in verification step, and comparative value over gh --attach is well argued. But static review did not reproduce any upload output; representative-output usability is unverified, so capped at 7 with a deduction for the execution-verification gap.
Auditable primary material exists: CI lint workflow, release workflow with build-provenance attestation, SECURITY.md, protocol documentation, and third-party usage cases (hermes-agent, openshift/console). Deducted: no committed test workflow covering key paths is shown, and most capability claims remain author-asserted, hence 4 within the static cap of 5.
- The user_session cookie used by this skill grants full GitHub account access — treat it like a password; prefer GH_SESSION_TOKEN with a dedicated bot account and avoid --token (visible in ps aux).
- Relies on an undocumented internal GitHub upload endpoint that may break without notice and carries no official guarantees.
- Core function requires access to github.com; availability from mainland-China networks may be unstable, and there is no Chinese-language documentation.
- The SKILL.md frontmatter version requirement (v1.1.0+) conflicts with the body (v1.4.0+); follow the body's requirement.
- Uploads are irreversible once published — always confirm the target repo and file list before executing.
- This was a static review with nothing executed; all conclusions are based on source reading and confidence is low.
What does this skill do, and when should you use it?
gh-image is a GitHub CLI extension that uploads local files through the internal endpoint GitHub's web UI uses (there is no public API) and prints a ready-to-paste Markdown reference. A companion Agent Skill (skills/github-image-upload) lets AI coding agents perform the upload and embedding when you ask in natural language. It authenticates with your existing gh token or browser session cookie, with no OAuth setup. Uploads go through GitHub's S3 presigned flow: images render inline, videos as players, other files as download links.
It first verifies gh auth status and the gh-image extension version (v1.4.0+ required), reporting failures without ever installing or authenticating on the user's behalf. After resolving and confirming file paths and the target repo, it uploads either via gh image <files> -- <gh command> to post directly to an issue/PR comment or body in one step, or standalone to capture the reference URL, which is then embedded through a --body-file - pipe. The upload walks GitHub's internal flow: fetch the repo page for an uploadToken, request an S3 policy from /upload/policies/assets, upload directly to S3 with presigned fields, then call the finalize endpoint. It finishes by counting user-attachments matches with grep to verify the embed landed. gh image download fetches existing attachments back to disk.
- A developer finishing code changes asks the agent to embed before/after screenshots in the PR description so reviewers see the visual impact immediately.
- A tester attaching failure logs, error screenshots, or repro videos to a bug report on a repo they only have read access to.
- A maintainer needing user-attachments links for README demo images or videos — the only URL kind that autoplays inline.
- A CI pipeline (as in NousResearch/hermes-agent) using a dedicated bot account's GH_SESSION_TOKEN to publish E2E screenshot evidence on every pull request automatically.
- A QA workflow (as in openshift/console's /qa-verify skill) attaching full-resolution QA evidence to PRs, avoiding CDN downscaling.
What are this skill's strengths and limitations?
- Handles any file type GitHub accepts (PDF, zip, logs, CSV, …), whereas gh v2.99.0's native --attach is limited to nine image/video extensions.
- Works on repositories you can only read — --attach cannot do this.
- GitHub Actions' GITHUB_TOKEN is rejected by --attach; this tool runs unattended in CI with a session token.
- No OAuth scopes to configure — reuses your existing gh token or browser session.
- The skill is defensively designed: confirms before uploading, treats issue bodies as untrusted data, verifies embeds, and never installs or authenticates for you.
- Relies on an undocumented internal GitHub API that may change without notice.
- Non-image/video uploads and uploads to repos without push access require a user_session cookie — a full-account credential that must be handled like a password.
- Chrome 127+ on Windows is unsupported by the cookie library, and Android/Termux has no browser cookie store; both require an explicit GH_SESSION_TOKEN.
- Uploads are irreversible — once published the file is accessible per repo visibility, which is why the skill demands confirmation per request.
- The source does not show automated test suite coverage; SAML SSO organizations must re-authorize the session roughly every 24 hours.
How do you install this skill?
- Install the GitHub CLI and run
gh auth login. 2. Rungh extension install drogers0/gh-image(v1.4.0+ required; upgrade old versions withgh extension upgrade gh-image). 3. Install the skill:npx skills add drogers0/gh-image, optionally with--agent claude-code codex opencode --globalfor several agents at once. The skill file lives at skills/github-image-upload/SKILL.md in the repo. Note: interactive local use requires an active GitHub session in a supported browser (Chrome/Brave/Chromium/Edge/Firefox/Opera/Safari); for CI, supply GH_SESSION_TOKEN, ideally from a dedicated bot account.
How do you use this skill?
Trigger in natural language, e.g. "attach this screenshot to the PR", "add this image to the issue", or "attach this log to the issue". Manual usage: upload a single file with gh image screenshot.png (repo inferred from the git remote, or --repo owner/repo); upload and comment in one step with gh image bug.png -- issue comment 42 --body-file repro.md; get a bare link with gh image report.pdf --repo owner/repo; fetch an attachment with gh image download <user-attachments-url>. Each successful upload prints one ready-to-paste reference line to stdout.
How does this skill compare with similar options?
The README explicitly compares against GitHub CLI v2.99.0's first-party --attach flag (shipped 2026-09-01): --attach suffices for attaching images/videos to repos you can push to; gh-image covers everything it does not — arbitrary file types, read-only repos, standalone links, downloading attachments, and CI automation — and actually wraps --attach rather than competing (gh commands after -- go through gh --attach first).