| name | process-album |
| description | End-to-end processing of downloaded music purchases: extract ZIPs, verify metadata, import to Apple Music, archive to NAS, clean up. Use when processing new music downloads. |
| allowed-tools | Bash Read Skill |
| metadata | {"author":"eyelock","version":"0.3.0"} |
Delegation Rule
This skill is a pure orchestrator. It MUST invoke other skills using the Skill tool:
Skill("media-management:<skill-name>", args="<arguments>")
DO NOT call underlying scripts directly via Bash.
DO NOT re-implement sub-skill logic inline.
When a step says → Invoke:, use the Skill tool exactly as shown.
The ONLY exception is Step 2 and Step 11 (ZIP extraction), which use this skill's own script.
Setup
- Check environment variables: MEDIA_MGMT_DOWNLOADS, MEDIA_MGMT_LIBRARY_IMPORT,
MEDIA_MGMT_LIBRARY_STORAGE, MEDIA_MGMT_ARCHIVE_WORKDIR
- For any unset variables, use the default paths from CLAUDE.md
- If CLAUDE.md has no paths, read config.json from $MEDIA_MGMT_CONFIG_PATH (defaults to ~/.config/media-management/config.json)
Scripts are in scripts/ relative to this skill directory.
Scripts
extract-zip.sh <zip_file> <dest_folder> — Extract a ZIP into a named subfolder with safety checks. Run --help for details.
References
See references/safety-rules.md for critical safety rules.
See references/album-types.md for album classification.
Workflow
Phase 1: MP3 Processing
Step 1: Identify release
→ Invoke: Skill("media-management:select-release")
- If a release is specified in $ARGUMENTS, pass it as args
- NEVER trust filename suffixes — the skill inspects archive contents
Step 2: Extract MP3 ZIP
Run the extraction script:
bash scripts/extract-zip.sh "$MP3_ZIP" "$DOWNLOADS/$RELEASE_NAME"
The script creates the subfolder, extracts the ZIP, and outputs JSON with the file list.
If extraction fails, ask user to extract manually via Finder.
Step 3: Inspect metadata
→ Invoke: Skill("media-management:manage-metadata", args="inspect $EXTRACTION_FOLDER")
- Review the output for missing/inconsistent fields
Step 4: MANDATORY metadata verification — STOP AND ASK USER
- Present: track count, detected artist, album title
- Present numbered genre list from the inspect results, ask user to select or type custom
- Ask user to verify artist name
- Ask user to verify album title
- Check for multiple artists — if found, ask: "Is this a compilation?"
- See references/album-types.md for classification
- DO NOT PROCEED without user confirmation of ALL fields
Step 5: Check for long tracks
- Check duration of each MP3 (available from the inspect output)
- If any track > 78 minutes (4680 seconds), inform user and ask about splitting
→ If user confirms:
Skill("media-management:split-long-tracks", args="$EXTRACTION_FOLDER")
- After splitting, update track count via manage-metadata
Step 6: Update metadata
→ Invoke: Skill("media-management:manage-metadata", args="update $EXTRACTION_FOLDER genre=$GENRE clear-album-artist|set-album-artist=$ARTIST update-track-count")
- Pass user-confirmed values (genre, album artist, compilation flag)
Step 7: Import to Apple Music
→ Invoke: Skill("media-management:import-to-apple-music", args="$EXTRACTION_FOLDER")
Step 8: MANDATORY Apple Music verification — STOP AND ASK USER
- Tell user: "Please check Apple Music and confirm the import looks correct"
- Check for: files appearing as a single album (not individual tracks)
- DO NOT PROCEED until user confirms
Phase 2: NAS Staging
Step 9: Archive MP3s
→ Invoke: Skill("media-management:archive-media", args="mp3 $ARTIST $ALBUM")
- Source:
$LIBRARY_STORAGE/Artist/Album/ (from Apple Music, captures edits)
- Destination:
$ARCHIVE_WORKDIR/to_nas/mp3/Artist/Album/
Step 10: Verify MP3 archival
- Check the JSON output from archive-media:
verified should be true
- If not, warn user about count mismatch
Phase 3: WAV Processing
Step 11: Extract WAV ZIP
Run the extraction script:
bash scripts/extract-zip.sh "$WAV_ZIP" "$DOWNLOADS/$RELEASE_NAME-wav"
Step 12: Archive WAVs (SKIP Apple Music)
→ Invoke: Skill("media-management:archive-media", args="wav $ARTIST $ALBUM $WAV_EXTRACTION_FOLDER")
- WAVs NEVER go through Apple Music import
Step 13: Cleanup
→ Invoke: Skill("media-management:cleanup", args="$ARTIST - $ALBUM")
- Moves original ZIPs to processed/, cleans extraction folders
