Claude Skill

uploading-files

File-upload bridge for Claude Code on the Web. CCotw has no native file mount; this skill creates a throwaway GitHub branch the user can drop files onto via the github.com web UI, then fetches them locally on the next turn. Use when the user wants to upload, share, or send files

LLM Mart · 0 points · 0 views 0 listing impressions 0 install-command copies
Virus-scanned Reviewed automatically before listing.

Full trust report

Download oaustegard-claude-skills-plugins_environment-and-config_skills_uploading-files-e39c726.zip · 6 KB
Part of oaustegard/claude-skills — 39 skills

Install

skills CLI npx skills add https://github.com/oaustegard/claude-skills/tree/main/plugins/environment-and-config/skills/uploading-files
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install oaustegard-claude-skills@llmmart
Git git clone https://github.com/oaustegard/claude-skills.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole oaustegard/claude-skills collection as a plugin from our marketplace. Git is the plain clone.

README

uploading-files

File-upload bridge for Claude Code on the Web. CCotw has no native file mount; this skill creates a throwaway GitHub branch the user can drop files onto via the github.com web UI, then fetches them locally on the next turn. Use when the user wants to upload, share, or send files into the session, or when a task clearly needs files the user has on disk that aren't in the repo.

Skill manifest

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).
Files (claude-skills)
  • scripts
    • upload.py 8.4 KB
      #!/usr/bin/env python3
      """File-upload bridge for Claude Code on the Web.
      
      CCotw has no native file mount. This script uses a throwaway GitHub branch
      on the working repo's `origin` remote as an upload target:
      
          init     create the upload branch on origin and print the GitHub web
                   upload URL for the user to drop files into
          fetch    download files committed onto the branch into ./.uploads/
          cleanup  delete the remote upload branch
          status   show the branch name, URL, and whether it exists on origin
      
      Branch name: upload-<short-session-id>. Session id comes from
      $CLAUDE_SESSION_ID, then from the most recent transcript under
      ~/.claude/projects/<encoded-cwd>/, then from a UTC timestamp as fallback.
      """
      from __future__ import annotations
      
      import json
      import os
      import subprocess
      import sys
      import urllib.error
      import urllib.request
      from datetime import UTC, datetime
      from pathlib import Path
      from typing import Any
      
      UPLOADS_DIR = ".uploads"
      
      
      def _token() -> str:
          for var in ("GH_TOKEN", "GITHUB_TOKEN", "GITHUB_PAT", "GH_PAT"):
              val = os.environ.get(var)
              if val:
                  return val
          sys.exit("error: no GitHub token in env (GH_TOKEN/GITHUB_TOKEN/GITHUB_PAT/GH_PAT)")
      
      
      def _api(method: str, path: str, body: dict | None = None) -> Any:
          url = f"https://api.github.com{path}"
          data = json.dumps(body).encode() if body is not None else None
          req = urllib.request.Request(url, data=data, method=method)
          req.add_header("Authorization", f"token {_token()}")
          req.add_header("Accept", "application/vnd.github+json")
          req.add_header("X-GitHub-Api-Version", "2022-11-28")
          if data is not None:
              req.add_header("Content-Type", "application/json")
          try:
              with urllib.request.urlopen(req) as r:
                  raw = r.read()
                  return json.loads(raw) if raw else None
          except urllib.error.HTTPError as e:
              msg = e.read().decode("utf-8", errors="replace")
              raise RuntimeError(f"GitHub API {method} {path} -> {e.code}: {msg}") from e
      
      
      def _origin_repo() -> tuple[str, str]:
          """Return (owner, repo) parsed from `git remote get-url origin`.
      
          Supports github.com SSH/HTTPS URLs and the CCotw local-proxy form
          (``http://local_proxy@127.0.0.1:PORT/git/<owner>/<repo>``).
          """
          try:
              url = subprocess.check_output(
                  ["git", "remote", "get-url", "origin"],
                  text=True,
                  stderr=subprocess.PIPE,
              ).strip()
          except subprocess.CalledProcessError as e:
              sys.exit(f"error: not in a git repo or origin missing: {e.stderr.strip()}")
          path: str | None = None
          if url.startswith("git@github.com:"):
              path = url.split(":", 1)[1]
          elif "github.com/" in url:
              path = url.split("github.com/", 1)[1]
          elif "/git/" in url:  # CCotw local proxy
              path = url.split("/git/", 1)[1]
          if path is None:
              sys.exit(f"error: cannot parse a github owner/repo from origin url: {url}")
          path = path.removesuffix(".git")
          owner, _, repo = path.partition("/")
          repo = repo.split("/", 1)[0]  # tolerate trailing path segments
          if not owner or not repo:
              sys.exit(f"error: could not parse owner/repo from origin url: {url}")
          return owner, repo
      
      
      def _session_id() -> str:
          for var in (
              "CLAUDE_CODE_SESSION_ID",
              "CLAUDE_CODE_REMOTE_SESSION_ID",
              "CLAUDE_SESSION_ID",
          ):
              sid = os.environ.get(var)
              if sid:
                  return sid
          projects = Path.home() / ".claude" / "projects"
          if projects.is_dir():
              encoded = "-" + str(Path.cwd().resolve()).replace("/", "-")
              proj = projects / encoded
              if proj.is_dir():
                  jsonls = sorted(proj.glob("*.jsonl"), key=lambda p: p.stat().st_mtime)
                  if jsonls:
                      return jsonls[-1].stem
          return "ts" + datetime.now(UTC).strftime("%Y%m%dT%H%M%S")
      
      
      def _branch_name() -> str:
          """upload-<short> where <short> is the last 12 alnum chars of the session id."""
          sid = _session_id()
          alnum = "".join(c for c in sid if c.isalnum())
          short = alnum[-12:] if len(alnum) >= 4 else (alnum or "session")
          return f"upload-{short}"
      
      
      def _branch_exists(owner: str, repo: str, branch: str) -> bool:
          try:
              _api("GET", f"/repos/{owner}/{repo}/branches/{branch}")
              return True
          except RuntimeError as e:
              if " -> 404" in str(e):
                  return False
              raise
      
      
      def _default_branch(owner: str, repo: str) -> str:
          return _api("GET", f"/repos/{owner}/{repo}")["default_branch"]
      
      
      def _upload_url(owner: str, repo: str, branch: str) -> str:
          return f"https://github.com/{owner}/{repo}/upload/{branch}"
      
      
      def _ensure_gitignore(entry: str) -> None:
          gi = Path.cwd() / ".gitignore"
          needle = entry.rstrip("/")
          if gi.exists():
              for line in gi.read_text().splitlines():
                  if line.strip().rstrip("/") == needle:
                      return
              text = gi.read_text()
              if text and not text.endswith("\n"):
                  text += "\n"
              gi.write_text(text + entry + "\n")
          else:
              gi.write_text(entry + "\n")
      
      
      def cmd_init() -> int:
          owner, repo = _origin_repo()
          branch = _branch_name()
          if _branch_exists(owner, repo, branch):
              print(f"Branch {branch} already exists on {owner}/{repo}; reusing it.")
          else:
              default = _default_branch(owner, repo)
              ref = _api("GET", f"/repos/{owner}/{repo}/git/ref/heads/{default}")
              sha = ref["object"]["sha"]
              _api(
                  "POST",
                  f"/repos/{owner}/{repo}/git/refs",
                  {"ref": f"refs/heads/{branch}", "sha": sha},
              )
              print(f"Created branch {branch} on {owner}/{repo} (from {default}).")
          print()
          print("UPLOAD URL — share verbatim with the user:")
          print(f"  {_upload_url(owner, repo, branch)}")
          print()
          print("Tell the user to drop files on that page and click 'Commit changes'.")
          print("When they confirm, run:  upload.py fetch")
          return 0
      
      
      def cmd_fetch() -> int:
          owner, repo = _origin_repo()
          branch = _branch_name()
          if not _branch_exists(owner, repo, branch):
              print(f"error: branch {branch} not found on {owner}/{repo}; run init first.")
              return 1
          default = _default_branch(owner, repo)
          cmp_data = _api("GET", f"/repos/{owner}/{repo}/compare/{default}...{branch}")
          files = [f for f in cmp_data.get("files", []) if f.get("status") != "removed"]
          if not files:
              print(f"No files on {branch} yet.")
              print(f"Upload URL: {_upload_url(owner, repo, branch)}")
              return 0
          out_dir = Path.cwd() / UPLOADS_DIR
          out_dir.mkdir(exist_ok=True)
          _ensure_gitignore(UPLOADS_DIR + "/")
          fetched: list[tuple[Path, int]] = []
          for f in files:
              rel = f["filename"]
              raw_url = f"https://raw.githubusercontent.com/{owner}/{repo}/{branch}/{rel}"
              req = urllib.request.Request(raw_url)
              req.add_header("Authorization", f"token {_token()}")
              with urllib.request.urlopen(req) as r:
                  data = r.read()
              dest = out_dir / Path(rel).name
              dest.write_bytes(data)
              fetched.append((dest, len(data)))
          print(f"Fetched {len(fetched)} file(s) into {out_dir}:")
          for dest, size in fetched:
              print(f"  {dest.relative_to(Path.cwd())}  ({size} bytes)")
          print()
          print("When done with these files, clean up the remote branch:")
          print("  upload.py cleanup")
          return 0
      
      
      def cmd_cleanup() -> int:
          owner, repo = _origin_repo()
          branch = _branch_name()
          if not _branch_exists(owner, repo, branch):
              print(f"Branch {branch} already gone on {owner}/{repo}.")
              return 0
          _api("DELETE", f"/repos/{owner}/{repo}/git/refs/heads/{branch}")
          print(f"Deleted remote branch {branch} on {owner}/{repo}.")
          print(f"Local files in ./{UPLOADS_DIR}/ are kept (gitignored).")
          return 0
      
      
      def cmd_status() -> int:
          owner, repo = _origin_repo()
          branch = _branch_name()
          exists = _branch_exists(owner, repo, branch)
          print(f"repo:    {owner}/{repo}")
          print(f"branch:  {branch}")
          print(f"exists:  {exists}")
          print(f"url:     {_upload_url(owner, repo, branch)}")
          return 0
      
      
      COMMANDS = {
          "init": cmd_init,
          "fetch": cmd_fetch,
          "cleanup": cmd_cleanup,
          "status": cmd_status,
      }
      
      
      def main() -> int:
          if len(sys.argv) < 2 or sys.argv[1] not in COMMANDS:
              sys.exit(f"usage: upload.py {{{'|'.join(COMMANDS)}}}")
          return COMMANDS[sys.argv[1]]()
      
      
      if __name__ == "__main__":
          raise SystemExit(main())
      
  • CHANGELOG.md 533 B
    # uploading-files - Changelog
    
    All notable changes to the `uploading-files` skill are documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
    
    ## [0.1.1] - 2026-04-20
    
    ### Other
    
    - uploading-files v0.1.1: add README (#566)
    - uploading-files: warn agent against wrapping the upload URL in markdown (#563)
    
    ## [0.1.1] - 2026-04-20
    
    ### Added
    
    - README.md with skill description
    
    ## [0.1.0] - 2026-04-20
    
    ### Other
    
    - uploading-files v0.1.0: GitHub-branch upload bridge for CCotw (#562)
  • README.md 398 B
    # uploading-files
    
    File-upload bridge for Claude Code on the Web. CCotw has no native file mount; this skill creates a throwaway GitHub branch the user can drop files onto via the github.com web UI, then fetches them locally on the next turn. Use when the user wants to upload, share, or send files into the session, or when a task clearly needs files the user has on disk that aren't in the repo.
    
  • SKILL.md 4.9 KB
    ---
    name: uploading-files
    description: File-upload bridge for Claude Code on the Web. CCotw has no native file mount; this skill creates a throwaway GitHub branch the user can drop files onto via the github.com web UI, then fetches them locally on the next turn. Use when the user wants to upload, share, or send files into the session, or when a task clearly needs files the user has on disk that aren't in the repo.
    metadata:
      version: 0.1.1
    ---
    
    # 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
    
    ```bash
    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:
    
    ```bash
    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:
    
    ```bash
    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
    
    ```bash
    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).
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.

Related