Skip to content
Get packs

Guide · Agent skill

How to use the GitHub File Attachments agent skill (gh-attach)

Updated · written with AI from the project's own documentation and checked against our catalogue data

The gh-attach skill lets an AI agent upload a local file such as a screenshot, image, PDF, zip or video to GitHub, then place that file inline in a pull request, issue or comment. It also downloads files that were already attached to GitHub. This guide explains what the skill does, how to install it, how to phrase requests so it triggers, and what it needs to run safely.

GitHub File Attachmentsgithub/awesome-copilot · MIT

Quick start

  1. 1Install the GitHub CLI. Install gh and sign in with gh auth login so gh-attach can match your browser account.
  2. 2Install the gh-attach extension. Run gh extension install sudosubin/gh-attach, or use the prerequisite check command in the guide.
  3. 3Add the skill folder. Unzip the downloaded ZIP into ~/.claude/skills/ or a project's .claude/skills/ folder, or upload it under Settings → Capabilities → Skills.
  4. 4Ask for an upload. Request something like attaching a screenshot to a pull request, naming the file with an absolute path.
  5. 5Confirm the embed. Check that the pull request or issue comment shows the image or file inline in a logged-in browser.
  6. 6Download when needed. Ask the agent to download a GitHub attachment and give it a destination path.

What is an agent skill, and what does gh-attach make the agent do?

An agent skill is a folder containing a SKILL.md file with instructions that an AI agent loads when a request matches the skill's description. The gh-attach skill is one of these. Its SKILL.md file is the only file listed for it.

With the skill installed, the agent can upload a local file to GitHub's user-attachments system and receive a URL. GitHub automatically displays that URL as an image, video or file wherever it is pasted. The agent can then post the URL in a comment, and it can download an existing GitHub attachment to a local path. The URL inherits the repository's visibility, so uploads to a private repository stay private.

Install the gh-attach skill

Download the ZIP from the skill's page on this site and unzip it. You can place the skill in one of two locations: your personal skills folder at ~/.claude/skills/, or a project's .claude/skills/ folder if you want it available only in that project. Alternatively, in the Claude apps, go to Settings → Capabilities → Skills and upload the ZIP there.

The skill also needs the GitHub CLI extension it is built on. The skill's prerequisite check installs it from GitHub if it is missing:

  • Install the GitHub CLI (gh) and make sure it is authenticated with gh auth login.
  • Install the gh-attach extension, which the source names as sudosubin/gh-attach.
gh extension list | grep -q 'gh attach' || gh extension install sudosubin/gh-attach

Set up authentication before the first upload

Uploads do not use the gh token. They use a GitHub browser session cookie. By default, gh must be authenticated so that gh-attach can select the matching browser account. If the wrong account is picked, add --browser <name> and --profile <name> to the command to choose the browser and profile explicitly.

For headless environments, you can set GH_ATTACH_SESSION_TOKEN to the bare user_session cookie value. Treat this value as a full account credential, because it grants full access to your GitHub account.

Upload a file and embed it in a pull request

The skill works in three steps: upload, embed and download. Use an absolute, quoted file path. The -R flag is optional when you are inside a repository. For GitHub Enterprise Server, use -R host/owner/repo. The upload command prints the URL on one line, and you use it as-is.

To embed the URL, the skill pipes a Markdown body into gh with --body-file -. This works with gh pr comment, gh pr edit, gh issue comment and gh issue edit. For sizing, the skill can embed an <img> tag with a width attribute instead of the bare URL.

  • Upload: the command prints one URL per file.
  • Embed: pass the Markdown body through --body-file - so the text is read from standard input.
  • Sizing: use <img width="800" src="URL"> to control display width.
URL=$(gh attach "$FILE" -R <owner>/<repo>) printf '## Screenshots\n\n%s\n' "$URL" | gh pr comment <pr> -R <owner>/<repo> --body-file -

Download an existing GitHub attachment

To download a file someone attached to an issue or pull request, specify the destination explicitly with -O. For private attachments, the skill uses your active gh token and falls back to browser cookies for authorization.

gh attach download "$URL" -O "$FILE"

Ask for it in plain language so the skill triggers

The agent loads the skill when your request resembles the skill's description. Requests that name the action and the target work best. The skill's description lists phrases such as the examples below, so reuse that wording when you can.

  • "Attach a screenshot to the PR."
  • "Add an image to the issue."
  • "Embed before/after screenshots in this pull request."
  • "Attach this file to the issue."
  • "Download this GitHub attachment."

Check results and handle private repositories

For a private repository, the URL renders only for people who are authorized to view it. If you fetch the URL anonymously, the source expects a 404 or 403 response. That is normal and not a sign that the upload failed.

The source also notes that GitHub Cloud and GHES decide which file extensions and content types they accept, so an unusual file type may be rejected by GitHub itself.

  • Open the pull request or issue in a browser while logged in to confirm the file renders.
  • Check the file extension if an upload is refused.

What people use it for

  • Adding before and after screenshots of a UI change to a pull request.
  • Attaching a log file, PDF or zip to an issue so the team can review it.
  • Keeping images in a private repository while ensuring they stay private.
  • Downloading files attached to an issue for local review.

Frequently asked questions

Is the gh-attach skill free to use?

The source lists the skill under an MIT licence. The skill depends on the GitHub CLI and the gh-attach extension, which are installed from GitHub; check their own licence terms. The source does not describe pricing.

What do I need to install gh-attach?

You need the GitHub CLI (gh), the gh-attach extension from sudosubin/gh-attach, and an authenticated gh session. Uploads also need a logged-in browser account that gh-attach can select.

Why do my uploads fail?

The source says uploads will fail without a usable browser session, because they use a browser session cookie rather than the gh token. Make sure you are logged in to GitHub in a browser, and use --browser and --profile if the wrong account is selected.

Does GitHub have an official API for uploading attachments?

No. The source states that GitHub has no public API for this. The skill uses GitHub's internal user-attachments endpoint, which could change without notice, so it is not an officially supported option.

Are my private repository files safe?

The uploaded URL inherits the repository's visibility, so it renders only for authorized viewers. The main risk is GH_ATTACH_SESSION_TOKEN, which holds a full account credential, so avoid exposing it in shared or production environments.

What are the alternatives if gh-attach does not fit my needs?

The source does not name alternatives. If you need an officially supported method, you would need to look outside this skill; the source only notes that the skill relies on an unofficial extension.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Use gh-attach if you are a developer or maintainer who regularly adds screenshots or files to GitHub pull requests and issues, and you can install GitHub CLI extensions and keep a logged-in browser session. Avoid it in shared or production environments, or where you need an officially supported API, because it depends on an undocumented endpoint and a session cookie that grants full account access.

Download the skill