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
npx skills add bitwize-music-studio/claude-ai-music-skills --skill validate-album -a claude-codeWhat 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-code2Manually: put the files in place
~/.claude/skills/validate-album/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/validate-album/
1Skills CLI (Vercel)
npx skills add bitwize-music-studio/claude-ai-music-skills --skill validate-album -a codex2Manually: put the files in place
.agents/skills/validate-album/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add bitwize-music-studio/claude-ai-music-skills --skill validate-album -a cursor2Manually: put the files in place
.cursor/skills/validate-album/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install bitwize-music-studio/claude-ai-music-skills skills/validate-album2Manually: put the files in place
.github/skills/validate-album/SKILL.md1Skills CLI (Vercel)
npx skills add bitwize-music-studio/claude-ai-music-skills --skill validate-album -a gemini-cli2Platform CLI
gemini skills install https://github.com/bitwize-music-studio/claude-ai-music-skills --path skills/validate-albumManually: put the files in place
.devin/skills/validate-album/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add bitwize-music-studio/claude-ai-music-skills --skill validate-album -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
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