Skip to main content
skill CX Codex

validate-album — Claude Code skill: what it does, how to install

validate-album is a Claude Code skill that checks album directories, audio file paths, and track metadata before release.

CC0-1.0 248 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 validate-album -a claude-code
Open on GitHub

What validate-album does

This skill audits an album package across several directories. It begins by calling get_config() and find_album through bitwize-music-mcp. If ~/.bitwize-music/config.yaml is missing, execution halts immediately with a prompt to run /configure.

The routine inspects directory paths, README files, track listings, and documentary files like RESEARCH.md when applicable. It checks whether WAV files follow the expected artist and genre path hierarchy rather than sitting directly under the audio root. Inside individual markdown track files, it verifies Suno input sections, status fields, and consistency of the instrumental flag between frontmatter and the details table.

Without an active ~/.bitwize-music/config.yaml, the check fails at step one. Upon completion, the agent lists counts for passed, failed, and skipped checks alongside ready-to-run shell commands for any mislocated audio.

What it helps with

  • detect missing track files or README files in album directories
  • spot audio folders saved outside the expected artist hierarchy
  • verify Suno prompts, styles, and links across track notes
  • generate exact shell commands to fix displaced audio folders

Example prompts for the agent

  • Validate album structure for sample-album
  • Check integrity and audio paths for album synth-wave
  • Run validation on electronic-odyssey before publishing

How to install validate-album

1Skills CLI (Vercel)

npx skills add bitwize-music-studio/claude-ai-music-skills --skill validate-album -a claude-code

2Manually: put the files in place

~/.claude/skills/validate-album/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/validate-album/

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

Questions about validate-album

How to install validate-album in Claude Code?

Run npx skills add bitwize-music-studio/claude-ai-music-skills --skill validate-album -a claude-code in your terminal.

What does validate-album do?

It verifies album directory structure, checks track markdown files for Suno metadata, and flags displaced audio directories.

What prerequisite files does the skill require?

It requires ~/.bitwize-music/config.yaml containing root paths and artist settings, plus access to bitwize-music-mcp.

Source text

SKILL.md · CC0-1.0
---
name: validate-album
description: Validates album directory structure, file locations, and content integrity. Use before release or whenever the user wants to check an album's structural health.
argument-hint: <album-name>
model: haiku
context: fork
allowed-tools:
  - Read
  - Bash
  - Glob
  - Grep
  - bitwize-music-mcp
---

# Album Validator Agent

## Your Task

**Input**: $ARGUMENTS (album name, e.g., `sample-album`)

Validate that an album has all required files in the correct locations, catching path issues and missing content before they become problems.

---

## Step 1: Load Config & Find Album

1. Call `get_config()` — returns paths (`content_root`, `audio_root`, `documents_root`) and `artist.name`
   - If config missing, STOP and report:
     ```
     [FAIL] Config file missing: ~/.bitwize-music/config.yaml
            Run /configure to set up the plugin.
     ```

2. Call `find_album(album_name)` — fuzzy match by name, slug, or partial
   - If not found, STOP and report (MCP returns available albums):
     ```
     [FAIL] Album not found: {album-name}
     ```

3. Optionally call `validate_album_structure(album_slug)` — runs structural validation checks and returns `{passed, failed, warnings, skipped, issues[], checks[]}`. This MCP tool handles directory structure, required files, audio placement, and track content checks in one call.

**Note**: The MCP `validate_album_structure` tool performs many of the checks below automatically. You can use its results directly or run the manual checks for more detailed reporting.

---

## Step 3: Run Validations

### Initialize Counters
- `passed = 0`
- `failed = 0`
- `warnings = 0`
- `skipped = 0`
- `issues = []` (list of fix commands)

### Output Header
```
═══════════════════════════════════════════════════════════
ALBUM VALIDATION: {album-name}
═══════════════════════════════════════════════════════════
```

---

## Validation Categories

### CONFIG
```
CONFIG
──────
```

| Check | Pass | Fail |
|-------|------|------|
| Config file exists | `[PASS] Config file exists` | `[FAIL] Config file missing` |
| content_root defined | `[PASS] content_root: {value}` | `[FAIL] content_root not defined` |
| audio_root defined | `[PASS] audio_root: {value}` | `[FAIL] audio_root not defined` |
| artist defined | `[PASS] artist: {value}` | `[FAIL] artist.name not defined` |

### ALBUM STRUCTURE
```
ALBUM STRUCTURE
───────────────
```

| Check | How | Pass | Fail |
|-------|-----|------|------|
| Album dir exists | `test -d {album_path}` | `[PASS] Album directory: {path}` | `[FAIL] Album directory missing` |
| README.md exists | `test -f {album_path}/README.md` | `[PASS] README.md exists` | `[FAIL] README.md missing` |
| tracks/ dir exists | `test -d {album_path}/tracks` | `[PASS] tracks/ directory exists` | `[FAIL] tracks/ directory missing` |
| Track files exist | `ls {album_path}/tracks/*.md` | `[PASS] {N} track files found` | `[WARN] No track files found` |

**For documentary albums** (check README.md for type):
| Check | How | Pass | Fail |
|-------|-----|------|------|
| RESEARCH.md exists | `test -f {album_path}/RESEARCH.md` | `[PASS] RESEARCH.md exists` | `[WARN] RESEARCH.md missing (documentary album)` |
| SOURCES.md exists | `test -f {album_path}/SOURCES.md` | `[PASS] SOURCES.md exists` | `[WARN] SOURCES.md missing (documentary album)` |

### AUDIO FILES
```
AUDIO FILES
───────────
```

Expected path: `{audio_root}/artists/{artist}/albums/{genre}/{album}/`

| Check | How | Pass | Fail |
|-------|-----|------|------|
| Audio dir exists (correct path) | `test -d {audio_root}/artists/{artist}/albums/{genre}/{album}` | `[PASS] Audio directory: {path}` | See below |
| Audio dir in wrong location | `test -d {audio_root}/{album}` | N/A | `[FAIL] Audio in wrong location (missing artist folder)` |

**If audio in wrong location**, add to issues:
```
→ Expected: {audio_root}/artists/{artist}/albums/{genre}/{album}/
→ Found at: {audio_root}/{album}/ (WRONG - missing artist folder)
→ Fix: mv {audio_root}/{album}/ {audio_root}/artists/{artist}/albums/{genre}/{album}/
```

| Check | How | Pass | Skip |
|-------|-----|------|------|
| WAV files present | `ls {audio_path}/*.wav` | `[PASS] {N} WAV files found` | `[SKIP] No audio files yet` |
| mastered/ exists | `test -d {audio_path}/mastered` | `[PASS] mastered/ directory exists` | `[SKIP] Not mastered yet` |

### ALBUM ART
```
ALBUM ART
─────────
```

| Check | How | Pass | Skip |
|-------|-----|------|------|
| Art in audio folder | `test -f {audio_path}/album.png` | `[PASS] album.png in audio folder` | `[SKIP] No album art yet` |
| Art in content folder | `test -f {album_path}/album-art.*` | `[PASS] album-art in content folder` | `[SKIP] No album art yet` |

### TRACKS
```
TRACKS
──────
```

For each track file in `{album_path}/tracks/*.md`:

1. Read the file
2. Check for required fields:
   - Status field exists
   - Suno Style Box exists (has `## Suno Inputs` section)
   - Suno Lyrics Box exists
   - If Status is `Generated` or `Final`: Suno Link present
   - If documentary: Sources Verified status
3. Check instrumental field sync:
   - Read frontmatter `instrumental` field (true/false/missing)
   - Read Track Details table `**Instrumental**` row (Yes/No/missing)
   - If both present and they disagree → `[WARN] {filename} - Instrumental field mismatch: frontmatter={value}, table={value}`
   - If only one is set → `[WARN] {filename} - Instrumental field missing from {frontmatter|table} (set in {other})`

Output per track:
- `[PASS] {filename} - Status: {status}, Suno Link: {present/missing}`
- `[WARN] {filename} - Status: {status}, missing {what}`
- `[FAIL] {filename} - No Status field`

---

## Step 4: Summary

```
═══════════════════════════════════════════════════════════
SUMMARY: {passed} passed, {failed} failed, {warnings} warning(s), {skipped} skipped
═══════════════════════════════════════════════════════════
```

If any issues:
```
ISSUES TO FIX:
1. {issue description}
   {fix command}
2. ...
```

---

## Example Output

```
═══════════════════════════════════════════════════════════
ALBUM VALIDATION: sample-album
═══════════════════════════════════════════════════════════

CONFIG
──────
[PASS] Config file exists
[PASS] content_root: ~/bitwize-music
[PASS] audio_root: ~/bitwize-music/audio
[PASS] artist: bitwize

ALBUM STRUCTURE
───────────────
[PASS] Album directory: ~/bitwize-music/artists/bitwize/albums/electronic/sample-album/
[PASS] README.md exists
[PASS] tracks/ directory exists
[PASS] 5 track files found

AUDIO FILES
───────────
[FAIL] Audio directory in wrong location
       → Expected: ~/bitwize-music/audio/artists/bitwize/albums/electronic/sample-album/
       → Found at: ~/bitwize-music/audio/sample-album/
       → Fix: mv ~/bitwize-music/audio/sample-album/ ~/bitwize-music/audio/artists/bitwize/albums/electronic/sample-album/

ALBUM ART
─────────
[SKIP] No album art yet

TRACKS
──────
[PASS] 01-intro.md - Status: Final, Suno Link: present
[PASS] 02-track.md - Status: Final, Suno Link: present
[WARN] 03-t-day-beach.md - Status: Generated, Suno Link: missing

═══════════════════════════════════════════════════════════
SUMMARY: 8 passed, 1 failed, 1 warning, 1 skipped
═══════════════════════════════════════════════════════════

ISSUES TO FIX:
1. Move audio folder to include artist:
   mv ~/bitwize-music/audio/sample-album/ ~/bitwize-music/audio/artists/bitwize/albums/electronic/sample-album/
```

---

## Important Notes

1. **Use MCP tools first** - `get_config()`, `find_album()`, `validate_album_structure()` before manual checks
2. **Check both correct AND wrong locations** - Catch misplaced files
3. **Provide actionable fixes** - Include exact commands to fix issues
4. **Use appropriate status** - PASS/FAIL/WARN/SKIP based on severity
5. **Count everything** - Report totals in summary

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

Similar skills

All skills for Notes, tasks and projects →

From the same set52

The whole set →
verify-sources verify-sources guides human review of track citations before Suno music generation. It extracts source links, awaits manual confirmation, and dates track records. CX Codex +1 249installs rename Renames music albums and tracks while synchronizing slugs, folder structures, and metadata. Handy for organizing studio catalog assets. CX Codex +1 249installs about The about skill displays the bitwize-music plugin version and creator details. Trigger it when you need to verify plugin capabilities or check which version is installed. CX Codex +1 248installs genre-creator The genre-creator skill builds documentation for a music genre and updates the library index and mastering presets. Use it when adding a genre to bitwize-music. 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 cloud-uploader cloud-uploader is a skill for uploading album promo videos and samplers to Cloudflare R2 or AWS S3 after the videos are created. CX Codex +1 247installs

Project sponsors

Companies that keep this analytics open