Skip to main content
skill CX Codex

cloud-uploader — Claude Code skill for cloud uploads

cloud-uploader is a skill for uploading album promo videos and samplers to Cloudflare R2 or AWS S3 after the videos are created.

CC0-1.0 247 installs ★ 686 updated 2026-10-22

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add bitwize-music-studio/claude-ai-music-skills --skill cloud-uploader -a claude-code
Open on GitHub

What cloud-uploader does

The skill sends promo videos and an album sampler to Cloudflare R2 or AWS S3. It checks configuration and source files, and can show a dry-run preview before transferring anything. Choose all files, promo videos only, or the sampler only; --public makes uploaded files publicly readable.

Cloud credentials must be set in ~/.bitwize-music/config.yaml, with cloud.enabled: true, and Python needs the boto3 package. Generate the promo videos first with /bitwize-music:promo-director. Without those files, there is nothing to upload.

Objects go under {artist}/{album}/ in the bucket, with no genre directory in the cloud path. Uploads are manual rather than automatic. The script uses Python from ~/.bitwize-music/venv when that environment is available.

What it helps with

  • send album promo videos to R2 or S3
  • preview the files and sizes before transfer
  • upload just the album sampler
  • make uploaded files publicly readable

Example prompts for the agent

  • Upload the promo videos and sampler for my-album to cloud storage: /bitwize-music:cloud-uploader my-album
  • Preview what would be sent for my-album without uploading files: /bitwize-music:cloud-uploader my-album --dry-run
  • Upload only the promo videos for my-album: /bitwize-music:cloud-uploader my-album --type promos

How to install cloud-uploader

1Skills CLI (Vercel)

npx skills add bitwize-music-studio/claude-ai-music-skills --skill cloud-uploader -a claude-code

2Manually: put the files in place

~/.claude/skills/cloud-uploader/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/cloud-uploader/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about cloud-uploader

How do I install cloud-uploader in Claude Code?

Run npx skills add bitwize-music-studio/claude-ai-music-skills --skill cloud-uploader -a claude-code. The skill file is placed at ~/.claude/skills/cloud-uploader/SKILL.md.

What does cloud-uploader do?

It uploads album promo videos and a sampler to Cloudflare R2 or AWS S3. A --dry-run preview lets you inspect the planned transfer first.

What do I need before uploading to R2 or S3?

Set cloud.enabled: true, provider credentials, and a bucket in ~/.bitwize-music/config.yaml. Python requires boto3, and the promo videos must already be generated.

Source text

SKILL.md · CC0-1.0
---
name: cloud-uploader
description: Uploads promo videos and content to Cloudflare R2 or AWS S3. Use when the user wants to host promo content for social media or distribution.
model: sonnet
effort: low
prerequisites:
  - promo-director
allowed-tools:
  - Read
  - Bash
  - Glob
requirements:
  python:
    - boto3
---

# Cloud Uploader Skill

Upload promo videos and other album content to cloud storage (Cloudflare R2 or AWS S3).

## Purpose

After generating promo videos with `/bitwize-music:promo-director`, upload them to cloud storage for:
- Hosting on websites
- Sharing via direct links
- CDN distribution
- Backup and archival

## When to Use

- After promo videos generated, user wants to upload to cloud
- User says "upload promos to R2" or "upload to S3"
- User says "upload promo videos for [album]"
- Manual invocation only (not automatic)

## Position in Workflow

```
Generate → Master → Promo Videos → **[Cloud Upload]** → Release
```

Optional step after promo-director, before release-director.

## Prerequisites

### Cloud Configuration

Cloud credentials must be configured in `~/.bitwize-music/config.yaml`:

```yaml
cloud:
  enabled: true
  provider: "r2"  # or "s3"

  # For Cloudflare R2
  r2:
    account_id: "your-account-id"
    access_key_id: "your-access-key"
    secret_access_key: "your-secret-key"
    bucket: "promo-videos"

  # For AWS S3
  s3:
    region: "us-west-2"
    access_key_id: "your-access-key"
    secret_access_key: "your-secret-key"
    bucket: "promo-videos"
```

See `${CLAUDE_PLUGIN_ROOT}/reference/cloud/setup-guide.md` for detailed setup instructions.

### Required Files

- Promo videos generated (run `/bitwize-music:promo-director` first)
- Located at: `{audio_root}/artists/{artist}/albums/{genre}/{album}/promo_videos/`
- Album sampler at: `{audio_root}/artists/{artist}/albums/{genre}/{album}/album_sampler.mp4`

### Python Dependencies

```bash
# If using the shared venv (recommended)
~/.bitwize-music/venv/bin/pip install -r ${CLAUDE_PLUGIN_ROOT}/requirements.txt

# Or install separately
pip install boto3
```

The upload script uses `~/.bitwize-music/venv` if available, otherwise falls back to system Python.

## Workflow

### 1. Verify Prerequisites

**Check config:**
```bash
cat ~/.bitwize-music/config.yaml | grep -A 20 "cloud:"
```

Verify:
- `cloud.enabled: true`
- Provider credentials configured (r2 or s3)
- Bucket name set

**Check promo videos exist:**
```bash
ls {audio_root}/artists/{artist}/albums/{genre}/{album}/promo_videos/
ls {audio_root}/artists/{artist}/albums/{genre}/{album}/album_sampler.mp4
```

If missing:
```
Error: Promo videos not found.

Generate with: /bitwize-music:promo-director {album}
```

### 2. Get Python Command

**Call `get_python_command()` first** to get the venv Python path and plugin root. Use these for all bash invocations below.

```
PYTHON="{python from get_python_command}"
PLUGIN_DIR="{plugin_root from get_python_command}"
```

### 3. Preview Upload (Dry Run)

Preview first:
```bash
$PYTHON "$PLUGIN_DIR/tools/cloud/upload_to_cloud.py" {album} --dry-run
```

Output shows:
- Provider and bucket
- Files to upload
- S3 keys (paths in bucket)
- File sizes

### 4. Upload Files

**Upload all (promos + sampler):**
```bash
$PYTHON "$PLUGIN_DIR/tools/cloud/upload_to_cloud.py" {album}
```

**Upload only track promos:**
```bash
$PYTHON "$PLUGIN_DIR/tools/cloud/upload_to_cloud.py" {album} --type promos
```

**Upload only album sampler:**
```bash
$PYTHON "$PLUGIN_DIR/tools/cloud/upload_to_cloud.py" {album} --type sampler
```

**Upload with public access:**
```bash
$PYTHON "$PLUGIN_DIR/tools/cloud/upload_to_cloud.py" {album} --public
```

### 5. Verify Upload

**For R2:**
- Check Cloudflare dashboard → R2 → Your bucket
- Files should appear under `{artist}/{album}/`

**For S3:**
- Check AWS Console → S3 → Your bucket
- Or use AWS CLI: `aws s3 ls s3://{bucket}/{artist}/{album}/`

### 5. Report Results

```
## Cloud Upload Complete

**Provider:** R2 (or S3)
**Bucket:** {bucket}
**Album:** {album}

**Uploaded Files:**
- {artist}/{album}/promos/01-track_promo.mp4
- {artist}/{album}/promos/02-track_promo.mp4
- ...
- {artist}/{album}/promos/album_sampler.mp4

**Total:** 11 files, 125.4 MB

**Next Steps:**
1. Verify files in cloud dashboard
2. If public: Test URLs work
3. Continue to release: /bitwize-music:release-director {album}
```

## Upload Path Structure

**IMPORTANT: Cloud paths are FLAT - no genre folder.**

The cloud path structure is different from the local content structure:

| Location | Path Structure |
|----------|----------------|
| Local content | `{content_root}/artists/{artist}/albums/{genre}/{album}/` |
| Local audio | `{audio_root}/artists/{artist}/albums/{genre}/{album}/` |
| **Cloud** | `{artist}/{album}/` (no genre!) |

Files are organized in the bucket as:

```
{bucket}/
└── {artist}/
    └── {album}/
        └── promos/
            ├── 01-track_promo.mp4
            ├── 02-track_promo.mp4
            ├── ...
            └── album_sampler.mp4
```

**Example for album "my-album" by "bitwize" in rock genre:**
- Local: `~/music/artists/bitwize/albums/rock/my-album/`
- Cloud: `bitwize/my-album/promos/` (NOT `bitwize/albums/rock/my-album/`)

## Command Options

| Option | Description |
|--------|-------------|
| `--type promos` | Upload only track promo videos |
| `--type sampler` | Upload only album sampler |
| `--type all` | Upload both (default) |
| `--dry-run` | Preview without uploading |
| `--public` | Set files as public-read |
| `--audio-root PATH` | Override audio_root from config |

## Invocation Examples

**Basic upload:**
```
/bitwize-music:cloud-uploader my-album
```

**Preview only:**
```
/bitwize-music:cloud-uploader my-album --dry-run
```

**Upload promos only:**
```
/bitwize-music:cloud-uploader my-album --type promos
```

**Upload with public access:**
```
/bitwize-music:cloud-uploader my-album --public
```

## Error Handling

**"Cloud uploads not enabled"**
- Add `cloud.enabled: true` to config
- See `${CLAUDE_PLUGIN_ROOT}/reference/cloud/setup-guide.md`

**"Credentials not configured"**
- Add credentials to config file
- For R2: account_id, access_key_id, secret_access_key
- For S3: access_key_id, secret_access_key

**"Album not found"**
- Check album exists in `{audio_root}/artists/{artist}/albums/{genre}/{album}/`
- Verify artist name in config matches

**"No files found to upload"**
- Generate promo videos first: `/bitwize-music:promo-director {album}`

**"Access Denied"**
- Check credentials are correct
- For R2: Verify API token has write permissions
- For S3: Verify IAM policy allows s3:PutObject

**"Bucket not found"**
- Create bucket first in cloud dashboard
- Verify bucket name in config

## Security Notes

- Credentials stored in config file (ensure proper file permissions)
- Config file should be gitignored in user's content repo
- Default: Files uploaded as private (not public)
- Use `--public` flag only for files intended for public access
- Consider using environment variables for CI/CD (future enhancement)

## Integration with Other Skills

### Handoff FROM

**promo-director:**

After promo generation:
```
Promo videos generated successfully.

**Optional:** Upload to cloud storage: /bitwize-music:cloud-uploader {album}
```

### Handoff TO

**release-director:**

After cloud upload:
```
Cloud upload complete.

Ready for release workflow: /bitwize-music:release-director {album}
```

## Supported Providers

### Cloudflare R2

- S3-compatible API
- No egress fees
- Global CDN integration
- Good for high-traffic content

### AWS S3

- Industry standard
- Fine-grained IAM permissions
- CloudFront CDN available
- Good for AWS ecosystem integration

## Future Enhancements

- Environment variable credentials (for CI/CD)
- Multiple bucket support
- Automatic CDN invalidation
- Progress bar for large uploads
- Resume failed uploads
- Bucket creation if missing
- Additional providers (Backblaze B2, DigitalOcean Spaces)

## Related Documentation

- `${CLAUDE_PLUGIN_ROOT}/reference/cloud/setup-guide.md` - Detailed setup instructions
- `${CLAUDE_PLUGIN_ROOT}/skills/promo-director/SKILL.md` - Generate promo videos
- `${CLAUDE_PLUGIN_ROOT}/skills/release-director/SKILL.md` - Release workflow

## Model Recommendation

**Sonnet 4.5** - This skill runs scripts and coordinates workflow. No creative output from LLM.

## Version History

- v0.14.0 - Initial implementation
  - R2 and S3 support via boto3
  - Dry-run mode
  - Public/private upload options
  - Path organization by artist/album

© bitwize-music-studio · CC0-1.0 · bitwize-music-studio/claude-ai-music-skills

Similar skills

All skills for Cloud: AWS, Azure, GCP →

From the same set52

The whole set →
validate-album validate-album is a Claude Code skill that checks album directories, audio file paths, and track metadata before release. CX Codex +1 248installs researchers-financial researchers-financial is a Claude Code skill that researches financial records and market data for music projects about companies, financial crime, or market events. It gathers sources and marks claims for human review. CX Codex +1 248installs next-step next-step analyzes music album progress and recommends the single best next action with the exact command to run. CX Codex +1 247installs configure configure is a Claude Code skill that interactively creates, edits, and checks the ~/.bitwize-music/config.yaml configuration file. CX Codex +1 247installs resume resume finds an album by name and displays its status with a concrete next step. Use when returning to an unfinished project or checking where an album stands in its workflow. CX Codex +1 246installs researchers-primary-source The researchers-primary-source skill gathers statements from tweets, blogs, forums and chat logs. Use it when you need direct quotes or first-hand accounts instead of paraphrased reporting. CX Codex +1 246installs promote-idea promote-idea turns a pending album concept in IDEAS.md into a project with one command. Use it when an idea is ready to move into album planning. CX Codex +1 188installs health-check health-check — a skill that runs plugin diagnostics: checks virtual environment packages, verifies skill registration, and detects album slug collisions. Use it to confirm your setup is correct or troubleshoot missing components. CX Codex +1 187installs

Project sponsors

Companies that keep this analytics open