Uploading Files

Uploading Files

Claude Code on the Web has no file-upload widget and no shared mount. Whenever the user needs to get a file (image, PDF, CSV, doc, archive, anything) into the session, route them through a temporary GitHub branch on the working repo's origin remote.

When to use

Trigger this skill when:

• The user asks to upload, attach, share, or send a file
• A task clearly needs a file the user has locally that isn't in the repo (e.g. "summarize this PDF", "the spreadsheet I exported", "the screenshot from earlier")
• You're about to ask the user to paste a long binary or large text blob — offer upload instead

Don't trigger when the file is already in the repo, on a public URL you can fetch, or short enough to paste inline.

Workflow

The script lives at /mnt/skills/user/uploading-files/scripts/upload.py once installed. It must be run from inside the working git repo (it uses origin and cwd).

Step 1 — Create the upload branch

python3 /mnt/skills/user/uploading-files/scripts/upload.py init

This creates upload-<short-session-id> on origin (from the default branch) and prints a GitHub upload URL. Show that URL to the user on its own line, with no surrounding markdown — no **bold**, no [link](...), no backticks. Some chat renderers concatenate trailing punctuation/markup onto the URL when the user clicks it, breaking the branch name. Bare URL only. Then tell them:

Open that link, drag the file(s) into the page, scroll to the bottom and click Commit changes (the default options are fine). Reply here when done.

Then stop and wait for the user. Do not pretend they've uploaded.

Step 2 — Fetch files

After the user confirms the upload:

python3 /mnt/skills/user/uploading-files/scripts/upload.py fetch

This downloads everything on the branch (vs default) into ./.uploads/ (filenames are flattened to basenames) and ensures .uploads/ is in .gitignore. Treat the files in .uploads/ like any other local input.

If the script reports "No files on branch yet", the user probably forgot to click commit. Ask them to refresh the upload page and verify they committed, then re-run fetch.

Step 3 — Cleanup

When the uploaded files are no longer needed — typically after the work is done and anything worth keeping has been moved into the repo proper, and before opening a PR — delete the remote branch:

python3 /mnt/skills/user/uploading-files/scripts/upload.py cleanup

Local files in ./.uploads/ are kept (they're gitignored). If the user might want them again, leave them; otherwise rm -rf .uploads after cleanup.

Optional — status

python3 /mnt/skills/user/uploading-files/scripts/upload.py status

Prints the repo, branch name, whether the branch exists on origin, and the upload URL. Useful when you've context-switched and want to recover the URL without recreating the branch.

How it works

• Branch name — upload-<short> where <short> is the first hyphen-segment of $CLAUDE_SESSION_ID, or of the most recent transcript filename under ~/.claude/projects/<encoded-cwd>/, or a UTC timestamp tsYYYYMMDD-HHMMSS as fallback. The same session always resolves to the same branch, so re-running init is idempotent.
• Repo — parsed from git remote get-url origin. Must be a github.com remote.
• Auth — uses $GH_TOKEN (then $GITHUB_TOKEN, $GITHUB_PAT, $GH_PAT). Token needs Contents: write on the working repo.
• Network calls — only api.github.com and raw.githubusercontent.com.

Constraints

• GitHub web upload caps at 25 MB per file. Larger files won't work via this flow.
• Filenames are flattened to basenames in .uploads/. If the user uploads two files with the same name in different subdirs, the second overwrites the first. Tell them to rename first if it matters.
• Binary files survive the round-trip fine (raw download, byte-exact).
• The skill does not read the upload branch's history beyond "what's there now vs default". If the user pushes multiple commits, you get the union of files.

Anti-patterns

• Don't ask the user to paste binary content (base64, hex dumps). Use this skill.
• Don't create the branch and immediately try to fetch — the user has to upload first.
• Don't leave the upload branch around after a PR is opened. It clutters the repo's branch list.
• Don't commit anything in .uploads/ to the working repo. If a file should be persisted, copy it to a proper location first (and git add from there).