xdrop

Overview of xdrop skill

What xdrop does

The xdrop skill helps an agent upload local files or directories to an Xdrop server and download files back from an Xdrop share link, including local decryption of encrypted transfers. It is best for terminal-driven file automation where you want a repeatable command, a clean share URL, and optional machine-readable output.

Who should install the xdrop skill

Install this xdrop skill if you:

• move files through an Xdrop instance from scripts or agent workflows
• receive Xdrop links like /t/<transferId>#k=... and want local download plus decryption
• need stable CLI flags such as --json, --quiet, --output, --expires-in, or --api-url
• want a concrete upload/download path instead of improvising raw HTTP calls

Real job to be done

Most users are not looking for “a file sharing skill” in the abstract. They need to automate one of two jobs reliably:

1. turn local files into an Xdrop share link from the terminal
2. take an existing Xdrop link and restore the files locally without guessing at the protocol

That is where xdrop is useful: it packages the workflow into two runnable scripts rather than leaving the agent to reverse-engineer the share format.

Why xdrop is different from a generic prompt

A generic prompt can describe how Xdrop might work. The xdrop skill gives executable scripts that already handle the practical path:

• upload via scripts/upload.mjs
• parse share links and download via scripts/download.mjs
• use the expected API root by default
• support quiet and JSON output for automation-friendly pipelines

Key constraints to know first

Before adopting xdrop, confirm these requirements:

• bun is required to run the bundled scripts
• the agent needs local filesystem access
• the agent needs network access to the target Xdrop server
• uploads are intended for Xdrop-compatible servers, not arbitrary file hosts

If your environment cannot run Bun or cannot access the target server, this xdrop guide is not the right path.

How to Use xdrop skill

Install xdrop skill into your skills setup

If you use the Skills system, install xdrop with:

npx skills add https://github.com/xixu-me/skills --skill xdrop

Then work from the skill directory files:

• skills/xdrop/SKILL.md
• skills/xdrop/scripts/upload.mjs
• skills/xdrop/scripts/download.mjs

Install runtime requirements for xdrop usage

The skill itself is script-based, so the practical prerequisite is Bun. Check that Bun is available before trying xdrop usage:

bun --version

Also verify:

• you can read the local files you want to upload
• you can write to the output directory for downloads
• the Xdrop server is reachable from your environment

Read these files first

For a fast evaluation, read in this order:

1. SKILL.md for the supported workflow and flags
2. scripts/upload.mjs for upload arguments and limits
3. scripts/download.mjs for share-link parsing and output behavior

That reading order is usually enough to decide whether xdrop for File Automation fits your pipeline.

Understand the two core entry points

The xdrop skill is intentionally narrow. You mainly call one of these:

• Upload:

  bun scripts/upload.mjs --server <xdrop-site-url> <file-or-directory> [...]
  

• Download:

  bun scripts/download.mjs <share-url>
  

That narrow scope is a strength if you want dependable file transfer automation rather than a broad SDK.

Upload files with xdrop

A basic upload looks like:

bun scripts/upload.mjs --server http://localhost:8080 ./dist/report.pdf

You can also upload multiple paths:

bun scripts/upload.mjs --server https://xdrop.example.com ./photo.jpg ./notes.txt

Use this when the user’s goal is “share these local files and give me a link,” not when they need storage syncing, browsing, or account management features.

Use automation-friendly upload flags

The most useful flags for real automation are:

• --json for structured downstream parsing
• --quiet to keep stdout clean
• --expires-in <sec> to control transfer lifetime
• --name <value> to set a transfer label
• --api-url <url> if the API root is not the default
• --concurrency <n> to tune parallel upload behavior

Example:

bun scripts/upload.mjs \
  --server http://localhost:8080 \
  --expires-in 600 \
  --json \
  --quiet \
  ./notes.txt

For agent workflows, --json matters a lot because it returns fields such as transferId, shareUrl, and expiresAt instead of forcing fragile text extraction.

Download and decrypt from a share link

The main download case is a full Xdrop share URL containing the key fragment:

bun scripts/download.mjs "http://localhost:8080/t/abc#k=..."

The script parses the share link, fetches transfer metadata, downloads the encrypted content, and decrypts it locally. This is the main reason to prefer the xdrop skill over a hand-written prompt: the key-bearing link format is already handled for you.

Control download output cleanly

By default, downloads go into a directory like ./xdrop-<transferId>. Override that when your workflow expects a specific path:

bun scripts/download.mjs --output ./downloads "http://localhost:8080/t/abc#k=..."

Useful flags:

• --output <dir> for deterministic file placement
• --json for machine-readable result output
• --quiet for cleaner logs
• --api-url <url> when the API root differs from <share-origin>/api/v1

Turn rough intent into a strong xdrop prompt

Weak request:

upload this file to xdrop

Better request:

Use the xdrop skill to upload ./build/app.tar.gz to https://xdrop.example.com, set expiry to 600 seconds, return JSON only, and keep stdout quiet.

Weak request:

fetch this xdrop link

Better request:

Use xdrop to download https://xdrop.example.com/t/abc#k=..., save it under ./artifacts/incoming, and return the output path as JSON.

Good xdrop usage prompts include:

• the server URL or full share URL
• exact local file paths
• desired output directory
• whether output should be plain text or JSON
• expiry needs for uploads

Best workflow for xdrop for File Automation

A practical workflow is:

1. verify Bun and network access
2. test with a small file first
3. switch to --json once the command works
4. add --quiet if another script or agent will parse stdout
5. only then move to larger or multi-file transfers

This reduces debugging time because most failures come from environment issues, path mistakes, or server reachability, not the transfer logic itself.

Practical limits and tradeoffs

From the script signals, xdrop is optimized for straightforward transfers, not unlimited bulk movement. The upload script defines:

• max concurrency capped at 6
• a max transfer size of 256 * 1024 * 1024 bytes

That means this xdrop guide fits short-lived sharing and automation tasks better than very large archival workflows.

xdrop skill FAQ

Is xdrop skill beginner-friendly

Yes, if you are comfortable running Bun scripts from the terminal. The interface is simple, but beginners may still need help with:

• installing Bun
• passing correct filesystem paths
• understanding the difference between site URL and API URL
• preserving the #k=... fragment in a share link

When is xdrop better than a normal prompt

The xdrop skill is better when you need execution, not explanation. A normal prompt can describe Xdrop, but this skill gives a concrete upload/download path with the right flags and local decryption workflow already encoded.

What input does xdrop need from me

For upload:

• a public Xdrop site URL via --server
• one or more local file or directory paths

For download:

• a full share URL, ideally including the key fragment
• optionally an output directory and API override

Without those inputs, an agent will have to guess, and xdrop usage quality drops quickly.

Do I need the full share URL for download

Yes, in practice you should provide the full Xdrop link. The download script explicitly expects a full share link and uses it to derive the transfer ID, origin, and key material. A bare transfer ID is not enough for the complete local decryption flow.

Can xdrop fit CI or scripted pipelines

Yes. This is one of the best reasons to install xdrop. The support for --json and --quiet makes it suitable for shell scripts, CI jobs, and agent chains where stdout must stay parseable.

When should I not use xdrop

Skip xdrop if:

• you cannot run Bun
• you need browser-first UX rather than terminal automation
• you need features beyond upload/download automation
• your target is not an Xdrop-compatible server
• your workflow involves files beyond the script’s intended transfer limits

How to Improve xdrop skill

Give xdrop complete, unambiguous inputs

The fastest way to improve xdrop results is to specify all operational inputs up front:

• exact file paths
• exact server or share URL
• desired expiry
• desired output directory
• whether you want JSON
• whether stdout must stay quiet

That removes most guesswork and avoids follow-up corrections.

Preserve the share URL fragment

A common failure mode in xdrop usage is losing the #k=... fragment when copying links between tools. If that fragment is missing, local decryption may fail even if the transfer ID is valid. Tell users explicitly to pass the full URL unchanged.

Prefer JSON for downstream automation

If another tool, script, or agent will consume the result, prefer:

• upload with --json
• download with --json

This improves reliability because you avoid parsing human-oriented console text.

Test with a small transfer before scaling up

For better xdrop for File Automation outcomes, validate the full round trip with a small file first:

1. upload a small test file
2. capture the returned share URL
3. download it into a temp directory
4. confirm the file contents match expectations

This isolates environment and server issues before you spend time debugging large transfers.

Use output and quiet flags deliberately

Two small choices improve quality a lot:

• use --output when the downloaded path matters to later steps
• use --quiet when logs would interfere with machine parsing

These flags are minor on paper but high-impact in real pipelines.

Adjust concurrency only when needed

The upload script supports --concurrency, but higher is not always better. Increase it only if you are sure the server and network path can handle more parallel work. Otherwise, keep the default behavior and optimize for predictable completion.

Handle server-specific API differences early

If your Xdrop deployment exposes the API somewhere other than the default <server>/api/v1, set --api-url immediately instead of debugging mysterious failures later. This is one of the first things to check when xdrop seems correct but cannot talk to the server.

Improve first-pass prompts with runnable detail

A strong xdrop guide for prompting looks like this:

Use the xdrop skill. Upload `./release.zip` to `https://xdrop.example.com`.
Set `--expires-in 1800`, return `--json`, and suppress progress with `--quiet`.
If the upload succeeds, report only `shareUrl` and `expiresAt`.

Why this works:

• it names the skill directly
• it provides the concrete source path
• it specifies server, expiry, and output format
• it defines the expected response shape

Diagnose the most likely failure points first

If xdrop fails, check these in order:

1. Bun is installed and runnable
2. local paths actually exist
3. the server URL is reachable
4. the full share URL includes #k=...
5. the API root needs --api-url
6. transfer size or environment constraints are being exceeded

That order usually resolves issues faster than reading the whole repository.

What to change after a weak first result

If the first xdrop run is messy or incomplete:

• add --json if output parsing was brittle
• add --quiet if logs polluted stdout
• add --output if files landed in the wrong place
• replace vague file references with exact paths
• test against a local or known-good Xdrop server before blaming the script

These changes usually improve the second run more than rewriting the whole workflow.