xdrop

xdrop 스킬 개요

xdrop 스킬이 하는 일

xdrop 스킬은 로컬 파일이나 디렉터리를 Xdrop 서버에 업로드하고, Xdrop 공유 링크에서 파일을 다시 다운로드하며, 암호화된 전송은 로컬에서 복호화까지 처리하도록 도와줍니다. 반복 실행 가능한 명령, 깔끔한 공유 URL, 선택적인 기계 판독용 출력이 필요한 터미널 중심 파일 자동화에 특히 잘 맞습니다.

어떤 경우에 xdrop 스킬을 설치하면 좋은가

다음에 해당하면 xdrop 스킬 설치를 권장합니다:

• 스크립트나 에이전트 워크플로에서 Xdrop 인스턴스를 통해 파일을 주고받는다
• /t/<transferId>#k=... 형태의 Xdrop 링크를 받아 로컬 다운로드와 복호화를 하고 싶다
• --json, --quiet, --output, --expires-in, --api-url 같은 안정적인 CLI 플래그가 필요하다
• raw HTTP 호출을 즉석에서 짜기보다, 명확한 업로드/다운로드 경로가 필요하다

실제로 해결하려는 작업

대부분의 사용자는 추상적인 의미의 “파일 공유 스킬”을 찾는 것이 아닙니다. 실제로는 다음 두 가지 작업을 안정적으로 자동화하려는 경우가 많습니다:

1. 터미널에서 로컬 파일을 Xdrop 공유 링크로 바꾸기
2. 기존 Xdrop 링크를 받아 프로토콜을 추측하지 않고 로컬에 파일을 복원하기

xdrop가 유용한 이유가 여기에 있습니다. 공유 포맷을 에이전트가 역으로 분석하게 두는 대신, 이 워크플로를 실행 가능한 두 개의 스크립트로 패키징해 두었기 때문입니다.

xdrop가 일반 프롬프트와 다른 점

일반 프롬프트도 Xdrop가 어떻게 동작할지 설명할 수는 있습니다. 하지만 xdrop 스킬은 실제 실행 가능한 스크립트를 제공해, 실무에 필요한 경로를 이미 처리해 둡니다:

• scripts/upload.mjs로 업로드
• scripts/download.mjs로 공유 링크 파싱 및 다운로드
• 기본적으로 기대되는 API root 사용
• 자동화 파이프라인에 맞도록 quiet 출력과 JSON 출력 지원

먼저 알아둘 핵심 제약

xdrop를 도입하기 전에 다음 조건을 먼저 확인하세요:

• 번들된 스크립트를 실행하려면 bun 이 필요합니다
• 에이전트가 로컬 파일시스템에 접근할 수 있어야 합니다
• 에이전트가 대상 Xdrop 서버에 네트워크로 접근할 수 있어야 합니다
• 업로드 대상은 임의의 파일 호스트가 아니라 Xdrop 호환 서버를 전제로 합니다

환경에서 Bun을 실행할 수 없거나 대상 서버에 접근할 수 없다면, 이 xdrop 가이드는 적합한 경로가 아닙니다.

xdrop 스킬 사용 방법

스킬 환경에 xdrop 스킬 설치하기

Skills 시스템을 사용 중이라면 다음으로 xdrop를 설치하세요:

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

그다음 아래 스킬 디렉터리 파일을 기준으로 작업하면 됩니다:

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

xdrop 사용을 위한 런타임 요구사항 설치

이 스킬은 스크립트 기반이므로, 실질적인 선행 조건은 Bun입니다. xdrop를 사용하기 전에 먼저 Bun이 사용 가능한지 확인하세요:

bun --version

또한 다음도 함께 점검하세요:

• 업로드하려는 로컬 파일을 읽을 수 있는지
• 다운로드 결과를 쓸 출력 디렉터리에 쓰기 권한이 있는지
• 현재 환경에서 Xdrop 서버에 접속 가능한지

먼저 읽어볼 파일

빠르게 적합성을 판단하려면 다음 순서로 읽는 것이 좋습니다:

1. 지원 워크플로와 플래그를 보는 SKILL.md
2. 업로드 인자와 제한을 확인하는 scripts/upload.mjs
3. 공유 링크 파싱과 출력 동작을 확인하는 scripts/download.mjs

보통 이 순서만 읽어도 File Automation 용도의 xdrop가 현재 파이프라인에 맞는지 판단하기에 충분합니다.

두 가지 핵심 진입점 이해하기

xdrop 스킬은 의도적으로 범위를 좁게 잡았습니다. 실제로는 아래 둘 중 하나를 주로 호출하게 됩니다:

• Upload:

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

• Download:

  bun scripts/download.mjs <share-url>
  

파일 전송 자동화에서 넓은 범위의 SDK보다 신뢰할 수 있는 동작이 중요하다면, 이런 좁은 범위는 오히려 장점입니다.

xdrop로 파일 업로드하기

기본적인 업로드 예시는 다음과 같습니다:

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

여러 경로를 한 번에 업로드할 수도 있습니다:

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

사용자 목표가 “이 로컬 파일들을 공유하고 링크를 달라”일 때 적합합니다. 스토리지 동기화, 브라우징, 계정 관리 기능이 필요한 경우에는 맞지 않습니다.

자동화 친화적인 업로드 플래그 활용

실제 자동화에서 특히 유용한 플래그는 다음과 같습니다:

• 구조화된 후속 파싱을 위한 --json
• stdout을 깔끔하게 유지하는 --quiet
• 전송 만료 시간을 제어하는 --expires-in <sec>
• 전송 라벨을 지정하는 --name <value>
• 기본 API root가 아닐 때 사용하는 --api-url <url>
• 병렬 업로드 동작을 조정하는 --concurrency <n>

예시:

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

에이전트 워크플로에서는 --json 의 가치가 특히 큽니다. 사람이 읽는 콘솔 텍스트를 취약하게 추출하지 않아도 되고, transferId, shareUrl, expiresAt 같은 필드를 바로 받을 수 있기 때문입니다.

공유 링크에서 다운로드하고 복호화하기

대표적인 다운로드 사례는 키 fragment가 포함된 전체 Xdrop 공유 URL을 받는 경우입니다:

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

이 스크립트는 공유 링크를 파싱하고, 전송 메타데이터를 가져오고, 암호화된 콘텐츠를 다운로드한 뒤, 로컬에서 복호화합니다. 이것이야말로 xdrop 스킬이 직접 작성한 프롬프트보다 나은 핵심 이유입니다. 키가 포함된 링크 포맷을 이미 처리하도록 구현돼 있기 때문입니다.

다운로드 출력을 깔끔하게 제어하기

기본적으로 다운로드 결과는 ./xdrop-<transferId> 같은 디렉터리에 저장됩니다. 워크플로에서 특정 경로가 필요하다면 아래처럼 덮어쓰세요:

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

유용한 플래그:

• 파일 위치를 예측 가능하게 만드는 --output <dir>
• 기계가 읽기 쉬운 결과 출력을 위한 --json
• 로그를 줄이는 --quiet
• API root가 <share-origin>/api/v1 와 다를 때 사용하는 --api-url <url>

모호한 요청을 강한 xdrop 프롬프트로 바꾸기

약한 요청:

upload this file to xdrop

더 나은 요청:

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.

약한 요청:

fetch this xdrop link

더 나은 요청:

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

좋은 xdrop 사용 프롬프트에는 보통 다음이 포함됩니다:

• 서버 URL 또는 전체 공유 URL
• 정확한 로컬 파일 경로
• 원하는 출력 디렉터리
• 일반 텍스트로 받을지 JSON으로 받을지
• 업로드 만료 시간 요구사항

File Automation용 xdrop의 권장 워크플로

실무적으로는 다음 순서가 가장 안정적입니다:

1. Bun과 네트워크 접근 가능 여부를 확인한다
2. 먼저 작은 파일로 테스트한다
3. 명령이 정상 동작하면 --json 으로 전환한다
4. 다른 스크립트나 에이전트가 stdout을 파싱해야 한다면 --quiet 를 추가한다
5. 그다음에야 더 큰 파일이나 다중 파일 전송으로 넘어간다

이 순서가 디버깅 시간을 줄여주는 이유는, 실제 실패 원인의 대부분이 전송 로직 자체보다 환경 문제, 경로 실수, 서버 도달 가능성에 있기 때문입니다.

실무에서 알아둘 한계와 트레이드오프

스크립트 구조를 보면 xdrop는 무제한 대용량 이동보다는 단순하고 명확한 전송에 최적화돼 있습니다. 업로드 스크립트에는 다음 제한이 정의돼 있습니다:

• 최대 동시성은 6 으로 제한
• 최대 전송 크기는 256 * 1024 * 1024 bytes

즉, 이 xdrop 가이드는 초대형 아카이브 워크플로보다, 짧은 수명의 공유와 자동화 작업에 더 잘 맞습니다.

xdrop 스킬 FAQ

xdrop 스킬은 초보자도 쓰기 쉬운가

네, 터미널에서 Bun 스크립트를 실행하는 데 익숙하다면 어렵지 않습니다. 인터페이스 자체는 단순하지만, 초보자는 여전히 아래 부분에서 도움이 필요할 수 있습니다:

• Bun 설치
• 올바른 파일시스템 경로 전달
• site URL과 API URL의 차이 이해
• 공유 링크의 #k=... fragment를 그대로 유지하기

xdrop는 언제 일반 프롬프트보다 나은가

설명이 아니라 실행이 필요할 때 xdrop 스킬이 더 낫습니다. 일반 프롬프트는 Xdrop를 설명할 수 있지만, 이 스킬은 올바른 플래그, 업로드/다운로드 경로, 로컬 복호화 워크플로까지 이미 담고 있는 구체적인 실행 경로를 제공합니다.

xdrop를 쓰려면 어떤 입력이 필요한가

업로드 시:

• --server 로 전달할 공개 Xdrop 사이트 URL
• 하나 이상의 로컬 파일 또는 디렉터리 경로

다운로드 시:

• 가능하면 키 fragment를 포함한 전체 공유 URL
• 선택적으로 출력 디렉터리와 API override

이 입력이 없으면 에이전트가 추측해야 하는 부분이 많아지고, xdrop 사용 품질도 빠르게 떨어집니다.

다운로드할 때 전체 공유 URL이 꼭 필요한가

네. 실무적으로는 전체 Xdrop 링크를 제공하는 것이 맞습니다. 다운로드 스크립트는 전체 공유 링크를 명시적으로 기대하며, 여기서 transfer ID, origin, 키 정보를 도출합니다. 단순한 transfer ID만으로는 완전한 로컬 복호화 흐름을 처리할 수 없습니다.

xdrop는 CI나 스크립트 파이프라인에 맞는가

네. 이것이 xdrop를 설치할 가장 강한 이유 중 하나입니다. --json 과 --quiet 를 지원하므로, stdout이 계속 파싱 가능해야 하는 셸 스크립트, CI 작업, 에이전트 체인에 잘 맞습니다.

언제 xdrop를 쓰지 말아야 하나

다음에 해당하면 xdrop는 건너뛰는 편이 낫습니다:

• Bun을 실행할 수 없다
• 터미널 자동화보다 브라우저 중심 UX가 필요하다
• 업로드/다운로드 자동화 이상의 기능이 필요하다
• 대상 서버가 Xdrop 호환 서버가 아니다
• 워크플로가 스크립트가 의도한 전송 한도를 넘는 파일을 다룬다

xdrop 스킬 개선 방법

xdrop에 완전하고 모호하지 않은 입력 주기

xdrop 결과를 가장 빠르게 개선하는 방법은 실행에 필요한 입력을 처음부터 모두 명확하게 주는 것입니다:

• 정확한 파일 경로
• 정확한 서버 URL 또는 공유 URL
• 원하는 만료 시간
• 원하는 출력 디렉터리
• JSON이 필요한지 여부
• stdout을 조용하게 유지해야 하는지 여부

이렇게 하면 대부분의 추측이 사라지고, 후속 수정도 줄어듭니다.

공유 URL의 fragment를 보존하기

xdrop 사용에서 흔한 실패 원인 중 하나는 도구 사이에서 링크를 복사하는 과정에서 #k=... fragment가 빠지는 것입니다. 이 fragment가 없으면 transfer ID가 유효하더라도 로컬 복호화가 실패할 수 있습니다. 사용자에게 전체 URL을 변경 없이 그대로 전달해야 한다고 명확히 안내하세요.

후속 자동화에는 JSON 우선

다른 도구, 스크립트, 에이전트가 결과를 소비한다면 다음을 우선하세요:

• 업로드는 --json
• 다운로드도 --json

사람이 읽는 콘솔 텍스트를 파싱하지 않아도 되므로 신뢰성이 높아집니다.

규모를 키우기 전에 작은 전송으로 먼저 검증하기

File Automation 용도의 xdrop 결과를 더 안정적으로 만들려면, 먼저 작은 파일로 전체 왕복 과정을 검증하세요:

1. 작은 테스트 파일을 업로드한다
2. 반환된 공유 URL을 저장한다
3. 임시 디렉터리로 다운로드한다
4. 파일 내용이 기대와 일치하는지 확인한다

이 과정을 거치면 대용량 전송을 디버깅하기 전에 환경 문제와 서버 문제를 먼저 분리해낼 수 있습니다.

output과 quiet 플래그를 의도적으로 사용하기

작아 보이지만 품질에 큰 영향을 주는 선택이 두 가지 있습니다:

• 이후 단계에서 다운로드 경로가 중요하다면 --output 사용
• 로그가 기계 파싱을 방해할 수 있다면 --quiet 사용

문서상으로는 사소해 보여도 실제 파이프라인에서는 영향이 큽니다.

동시성은 필요할 때만 조정하기

업로드 스크립트는 --concurrency 를 지원하지만, 값을 높인다고 항상 좋은 것은 아닙니다. 서버와 네트워크 경로가 더 많은 병렬 작업을 감당할 수 있다는 확신이 있을 때만 높이세요. 그렇지 않다면 기본 동작을 유지하고, 예측 가능한 완료를 우선하는 편이 낫습니다.

서버별 API 차이는 초기에 처리하기

Xdrop 배포 환경의 API가 기본값인 <server>/api/v1 가 아니라 다른 위치에 노출돼 있다면, 나중에 애매한 실패를 디버깅하기보다 처음부터 --api-url 을 지정하세요. xdrop 구성이 맞아 보이는데도 서버와 통신하지 못할 때 가장 먼저 확인할 항목 중 하나입니다.

첫 프롬프트부터 실행 가능한 디테일 넣기

프롬프트용 xdrop 가이드를 강하게 쓰려면 이런 식이 좋습니다:

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`.

이 방식이 잘 작동하는 이유:

• 스킬 이름을 직접 명시한다
• 구체적인 소스 경로를 제공한다
• 서버, 만료 시간, 출력 형식을 지정한다
• 기대하는 응답 형태를 정의한다

가장 가능성 높은 실패 지점부터 진단하기

xdrop가 실패하면 다음 순서로 확인하세요:

1. Bun이 설치되어 있고 실행 가능한지
2. 로컬 경로가 실제로 존재하는지
3. 서버 URL에 접근 가능한지
4. 전체 공유 URL에 #k=... 가 포함되어 있는지
5. API root에 --api-url 이 필요한지
6. 전송 크기 제한이나 환경 제약을 넘고 있지는 않은지

보통 이 순서가 저장소 전체를 읽는 것보다 더 빠르게 문제를 해결해 줍니다.

첫 결과가 약했을 때 무엇을 바꿔야 하나

첫 xdrop 실행 결과가 지저분하거나 불완전했다면 다음을 조정해 보세요:

• 출력 파싱이 취약했다면 --json 추가
• 로그가 stdout을 오염시켰다면 --quiet 추가
• 파일이 잘못된 위치에 저장됐다면 --output 추가
• 모호한 파일 지시를 정확한 경로로 교체
• 스크립트를 탓하기 전에 로컬 또는 검증된 Xdrop 서버에서 먼저 테스트

대부분의 경우, 워크플로 전체를 다시 쓰는 것보다 이런 수정이 두 번째 실행 결과를 더 크게 개선합니다.