用途:Claude Code on the Web 没有文件上传控件,也没有共享挂载。当用户需要把本地文件(图片、PDF、CSV、文档、压缩包等)带入会话时,此技能借助工作仓库 origin 上的临时 GitHub 分支完成传输。
触发时机:用户要求上传、附加、分享或发送文件;任务明显需要仓库中不存在的本地文件(如“总结这个 PDF”“我导出的表格”“之前的截图”);或即将要求用户粘贴长二进制/大段文本时,可改为提供上传方式。文件已在仓库、可通过公开 URL 获取或短到可内联粘贴时,不应触发。
使用方式:脚本安装后位于 /mnt/skills/user/uploading-files/scripts/upload.py,必须在工作 git 仓库内运行(依赖 origin 与当前目录)。
第一步,创建上传分支:python3 /mnt/skills/user/uploading-files/scripts/upload.py init。它会在 origin 上基于默认分支创建 upload-<short-session-id> 并打印 GitHub 上传 URL。应把该 URL 单独一行、不加任何 markdown 展示,避免渲染器把标点或标记拼到链接上导致分支名出错。随后告知用户打开链接、拖入文件、滚动到底部点击 Commit changes,完成后回复,然后停止等待。
第二步,用户确认后拉取:python3 /mnt/skills/user/uploading-files/scripts/upload.py fetch。它把分支上相对默认分支的全部文件下载到 ./.uploads/(文件名扁平化为基名),并确保 .uploads/ 写入 .gitignore。若提示“No files on branch yet”,通常是用户未提交,请其刷新页面确认后重试。
第三步,清理:文件不再需要时(通常在成果已移入仓库、开 PR 之前)删除远程分支:python3 /mnt/skills/user/uploading-files/scripts/upload.py cleanup。本地 ./.uploads/ 会保留(已被 gitignore),如需可再 rm -rf .uploads。
可选状态查询:python3 /mnt/skills/user/uploading-files/scripts/upload.py status,打印仓库、分支名、分支是否存在于 origin 及上传 URL。
实现要点:分支名为 upload-<short>,<short> 取自 $CLAUDE_SESSION_ID 的首个连字符段,或 ~/.claude/projects/<encoded-cwd>/ 下最近记录文件名,或 UTC 时间戳 tsYYYYMMDD-HHMMSS 兜底;同一会话解析到同一分支,init 幂等。仓库从 git remote get-url origin 解析,须为 github.com 远程。认证使用 $GH_TOKEN(其次 $GITHUB_TOKEN、$GITHUB_PAT、$GH_PAT),令牌需对工作仓库有 Contents: write 权限。网络仅访问 api.github.com 与 raw.githubusercontent.com。
限制:GitHub 网页上传单文件上限 25 MB,更大文件无法走此流程;文件名扁平化,不同子目录同名文件后者覆盖前者,重要时需先改名;二进制文件可字节级完整往返;技能只比较分支当前内容与默认分支,不读取历史,多次提交得到文件并集。
反模式:不要让用户粘贴 base64/十六进制等二进制内容;不要创建分支后立即 fetch,须等用户先上传;开 PR 后不要遗留上传分支;不要把 .uploads/ 中的内容提交到工作仓库,需持久化应先复制到合适位置再 git add。