Skip to main content
Agent skill

File Transfer

Move files between the user and the sandbox/cluster through Nuphos's short-lived transfer store. Use when the user uploaded files for you to work on, or when you produced/fetched a file the user should download. Pull user uploads into the sandbox; push files out so the user can download them (single files or a zip), or save them straight onto a selected computer with localdownload.

Get started

Get the complete skill folder, including its scripts and reference files.

When to use this skill

Use File Transfer when an AI agent needs a reusable SKILL.md workflow for this job: Move files between the user and the sandbox/cluster through Nuphos's short-lived transfer store. Use when the user uploaded files for you to work on, or when you produced/fetched a file the user should download. Pull user uploads into the sandbox; push files out so the user can download them (single files or a zip), or save them straight onto a selected computer with localdownload.

When not to use it

Skip File Transfer when the task is outside the coding category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.

How to install

Where will you use it?

Install scope
Claude Code folder setup
mkdir -p ~/.claude/skills/file-transfer
# Save SKILL.md to ~/.claude/skills/file-transfer/SKILL.md
  1. Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/file-transfer/SKILL.md. For a shared project, commit the folder at .claude/skills/file-transfer/ instead.
  2. Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
  3. For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.

Full install guide for Claude, Cursor, and Codex →

Try a starter prompt

After installing the skill, paste this starter prompt into your agent to verify it triggers on a small task.

Starter prompt
Use the File Transfer skill for this task: Use File Transfer when this documented workflow matches the task. Confirm any required inputs or files before making changes.

What supports this recommendation?

71/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.

Documentation
77/100
Practical detail
68/100
Source evidence
63/100
Source signals
72/100
Model compatibility evidence
  • claudeuntested

    No model-specific signal or recorded compatibility test was found.

  • chatgptuntested

    No model-specific signal or recorded compatibility test was found.

  • geminiuntested

    No model-specific signal or recorded compatibility test was found.

  • copilotuntested

    No model-specific signal or recorded compatibility test was found.

  • llamauntested

    No model-specific signal or recorded compatibility test was found.

  • perplexityuntested

    No model-specific signal or recorded compatibility test was found.

  • mistraluntested

    No model-specific signal or recorded compatibility test was found.

  • grokuntested

    No model-specific signal or recorded compatibility test was found.

Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.

What this skill does

# File transfer

Nuphos has a temporary, S3-backed transfer store that ferries files between the user and agent workflows. You never touch buckets or credentials — these scripts call the backend, which hands back short-lived signed URLs, and the file moves **directly between the sandbox and S3**.

Two directions:

- **Pull** — the user uploaded files (an `upload` transfer group). Pull them into the sandbox to work on them. - **Push** — you produced or fetched a file (e.g. `kubectl cp` from a pod, or a report you generated). Push it out as a `download` group; a download card then appears in the user's conversation. Images and videos in it show inline, so pushing is also how you **show** the user a screenshot, recording, or chart image. Never leave such a file at a local path for the user to open, or describe it via OCR instead of sending it. An image that already has a public `https://` URL needs no push: put `![what it shows](https://…)` on a line of its own in your reply.

## Critical cost rule

The transfer store is **fully decoupled from this sandbox's lifecycle**. Always push a finished file out **during the current turn**, while the sandbox is already alive — never assume the sandbox will still exist later for the user to "pull from it". Once pushed to the store, the file lives in S3 with its own TTL and the user can download it long after this sandbox is gone. Pulling an upload likewise happens within the active turn.

## Auth (same pattern as other skills)

```bash # Helper: authenticated call to the backend, scoped to this agent session. ft() { local method="$1" path="$2"; shift 2 curl -fsSL -X "$method" \ -H @<(printf 'Authorization: Bearer %s\n' "$NUPHOS_TOKEN") \ -H "Content-Type: application/json" \ "${NUPHOS_BACKEND_URL:-https://api.nuphos.ai}/agent-sessions/${NUPHOS_SESSION_ID}/teams/${TEAM}/file-transfers${path}" "$@" } ```

`$TEAM` is the team id — get it from the `nuphos-api` skill (`GET /teams`) if you don't already have it. `$NUPHOS_TOKEN` and `$NUPHOS_SESSION_ID` are already in the environment. Use `ft` or the scripts below rather than another HTTP client; see the `nuphos-api` skill for why.

## Pull user uploads into the sandbox

When the user attaches files, the conversation gives you a transfer **groupId**. Pull it:

```bash bash skills/file-transfer/scripts/transfer-pull.sh <TEAM> <groupId> <dest-dir> # downloads every ready file into <dest-dir>, preserving relative paths ```

If some files are still uploading/failed the script reports them; re-run to pick up late arrivals.

The same command pulls any group of your team by its id, whoever pushed it: another conversation, a sub-agent or a sibling thread. To hand files to another conversation, push them and send it the groupId.

### Folder / multi-file uploads come as one archive

The desktop uses a **hybrid** upload model:

- A **single file** is uploaded as-is — pull it normally. - A **folder or multi-file** selection is packed into ONE `.zip` object (this avoids many tiny objects, the file-count cap, and OS junk like `.DS_Store`).

For the archive case the conversation message tells you so and includes `--extract`. Pass it and the script unpacks the zip **in place** (via python's `zipfile`, so no `unzip` binary is required) back into the original tree, then removes the zip:

```bash bash skills/file-transfer/scripts/transfer-pull.sh <TEAM> <groupId> ./uploads --extract # pulls assets.zip, extracts it → ./uploads/assets/... , removes the zip ```

Just follow the pull command given in the message; you don't decide the model.

## Push files out for the user to download

```bash # One or more discrete files → the user gets per-file download + "download all as zip" bash skills/file-transfer/scripts/transfer-push.sh <TEAM> ./report.csv ./chart.png

# A whole directory → preserves the tree bash skills/file-transfer/scripts/transfer-push.sh <TEAM> ./output/

# Large tree (hundreds of files) → zip it in the sandbox first and push ONE # archive. Cross-platform: plain `zip` here produces a UTF-8, mac+Windows # friendly archive (Linux zip adds no __MACOSX/._ junk). zip -r -X /tmp/results.zip ./output/ >/dev/null bash skills/file-transfer/scripts/transfer-push.sh <TEAM> /tmp/results.zip ```

The script prints the resulting **groupId** and a one-line summary.

**Keep the user-facing reply minimal.** Once the push succeeds, a download card renders in the conversation on its own — do NOT explain the mechanism (transfer store, S3, "download area", group ids, or that "a card will appear"). A short confirmation is enough, e.g. "Done — 404.html is ready to download." or just "Done ✅". The card speaks for itself; the user does not need to know how the transfer works.

### When to zip in the sandbox vs let the desktop zip

- **A few discrete files** → push them individually. The desktop offers both per-file download and a local "download all as zip", so the user chooses. - **A large directory / many files** → `zip` it here first and push the single archive. This avoids hundreds of separate objects and is faster.

### Files on a selected computer

When the person names a file on their computer, use **local_upload** with its absolute path (or `~/path`) and the selected device ID. It uses the computer's internal uploader and returns only `groupId`, `fileName` and `size`, as soon as the upload starts. Immediately pull that group into the agent workspace; the pull waits for the upload to arrive:

```bash bash skills/file-transfer/scripts/transfer-pull.sh <TEAM> <groupId> ./uploads ```

This needs an online, selected computer with local exec allowed and an updated Desktop or CLI host. It does not need an AWS login or a CLI transfer command. Only one regular file is supported; directories are not uploaded by this tool. The store's existing size/TTL limits apply. If the pull says the file is still uploading, run it again; if it says the upload failed, start `local_upload` again. Report a missing file, offline/old host, or transfer failure directly.

Signed URLs stay inside the trusted implementation. Never put them in `local_exec` arguments, tool results, transcript, logs or replies. Encoding a command does not hide its capability. Do not stage files through GitHub releases or another external service. Do not ask the person to drag the same file into chat when `local_upload` can import it.

When the person asks for a file **on** their computer ("save it to my laptop"), push it first, then use **local_download** with the `groupId` the push printed, an absolute target path (or `~/path`) and the selected device ID:

```bash bash skills/file-transfer/scripts/transfer-push.sh <TEAM> ./out/deck.html ```

The computer fetches the file itself and answers `{path, size}` once it is written. If it answers `file_exists`, ask the person before calling again with `overwrite: true`. If it answers `update_required`, tell them to update Nuphos on that computer. Pass `fileName` when the group holds several files.

## Failure handling

The scripts surface explicit errors: `file_too_large`, `too_many_files`, `transfer_too_large`, `transfer_expired`, `file_transfer_unconfigured`, `transfer_not_found`. If the store is unconfigured (`503 file_transfer_unconfigured`), tell the user file transfer isn't enabled on this deployment rather than retrying.

`file_transfer_rate_limited` (429) means the team used its hourly transfer limit. Do not retry: retries fail the same way until the hour turns. Tell the user the limit was reached and when it resets (the error's message, or `retryAfter` from `local_upload`), and offer to work with what is already in the sandbox.

## Safety

- Never push secrets/credentials out as downloadable files unless the user explicitly asked for that file. - Respect the size limits; if a file is rejected as too large, tell the user the limit instead of silently truncating.

Intended uses

  • Use File Transfer when this documented workflow matches the task.

Implementation notes

  • Review the source instructions and adapt inputs before running the workflow.

Try it, then tell us how it went

A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.