| name | jazztips |
| description | Create a Jazztips record markdown file from "Artist - Album" input. Searches the web for album metadata, cover art, and streaming links (Spotify/Tidal/Apple/Qobuz), generates Astro frontmatter, writes the file as a draft under src/content/, then runs `npm run build` — on success, removes the draft flag and pushes to origin; on failure, leaves the draft for the user to fix. Triggers on /jazztips or requests like "add Artist - Album to jazztips". |
| user_invocable | true |
Jazztips Record Creator
Replaces the n8n "Jazztips Record Creator Agent" workflow. Given Artist - Album, produce one markdown file under src/content/<slug>.md in this repo. The build script writes the record as a draft: true. After the file is written, run npm run build:
- Build succeeds → remove the
draft: true line, then git add the file and git commit -m "Add record: <Artist> - <Album>" and git push origin <BRANCH>.
- Build fails → leave the file as
draft: true and unstaged. Report the build error to the user. Do not commit.
Configuration
This skill is meant to be invoked from the root of the jazztips-astro repo. It operates on $CLAUDE_PROJECT_DIR directly — no separate repo path needed.
BRANCH: main
Before doing anything, sanity-check the working tree:
$CLAUDE_PROJECT_DIR must contain src/content/ (verify with ls "$CLAUDE_PROJECT_DIR/src/content").
- The repo must be on
BRANCH with a clean working tree. If not, stop and ask the user.
Inputs
User supplies Artist - Album (free text). Examples:
Nils Landgren - Love of My Life
John Coltrane - A Love Supreme
Workflow
Step 1 — Gather metadata (one WebSearch)
Search: <Artist> <Album> album credits musicians label discogs allmusic
From the results, extract (set any missing field to null, never omit):
release_date — YYYY-MM-DD if available, else YYYY
description — 2–4 paragraph neutral, factual summary. No opinions.
tags — genres only, e.g. ["Jazz", "Post-Bop"]. Never include years.
credits — array of {name, role} for principal musicians and their instruments only.
- Exclude: Recording Engineer, Mixing Engineer, Producer, Cover Design, Cover Photo, Arranger, Artwork.
label — record label
producers — array of producer names (separate from credits)
source_urls — at least 2 URLs you actually used (Discogs, AllMusic, Wikipedia, Bandcamp, official label pages preferred)
If WebSearch is rate-limited or returns nothing useful, fall back to WebFetch on a known source (e.g. https://www.discogs.com/search/?q=<artist>+<album>&type=release).
Step 2 — Cover art (one WebSearch)
Search: <Artist> <Album> album cover art
Pick the first direct image URL (.jpg/.jpeg/.png/.webp) from a reputable source. Prefer Discogs, Bandcamp, label sites, Wikipedia. This becomes cover_image_url.
Step 3 — Streaming links (four WebSearches, one per platform)
Run these in parallel:
| Platform | Query | Required URL shape |
|---|
| Spotify | <artist> <album> spotify | https://open.spotify.com/album/<id> |
| Tidal | <artist> <album> tidal | https://tidal.com/browse/album/<numeric-id> |
| Apple | <artist> <album> apple music | https://embed.music.apple.com/<cc>/album/<slug>/<id> |
| Qobuz | <artist> <album> qobuz | https://www.qobuz.com/<region>/album/<slug>/<id> |
Pick the best URL per platform using this scoring (ported from the n8n Extract Link node):
- Domain must match (
open.spotify.com, tidal.com, music.apple.com/embed.music.apple.com, qobuz.com). Otherwise discard.
- +100 if the path is
/album/... (or /browse/album/... for Tidal).
- −40 if it's an
/artist/ page.
- −20 if it's a
/track/ or /song/ page.
- −60 if it's a
/search page.
- +20 if the result title/snippet contains the artist name; +30 if it contains the album name.
- Tiebreaker: prefer URL length < 120 chars.
If no candidate scores positively, set that platform to null. Do not return search/artist/track URLs as a fallback.
URL normalization (the build script handles this; do not pre-normalize):
- Tidal
…/album/<id> → https://tidal.com/browse/album/<id>
- Apple
music.apple.com → embed.music.apple.com
Step 4 — Build the markdown
Assemble a single JSON object matching this schema:
{
"title": "Artist - Album",
"artist": "Artist Name",
"album": "Album Name",
"release_date": "YYYY-MM-DD",
"description": "...",
"tags": ["Jazz"],
"credits": [{"name": "...", "role": "..."}],
"label": "...",
"producers": ["..."],
"cover_image_url": "https://...",
"spotify": "https://open.spotify.com/album/...",
"tidal": "https://tidal.com/browse/album/...",
"apple": "https://embed.music.apple.com/...",
"qobuz": "https://www.qobuz.com/.../album/...",
"source_urls": ["https://...", "https://..."]
}
title MUST be exactly Artist - Album (single hyphen, spaces around it).
Write the JSON to /tmp/jazztips-meta.json, then pipe it into the build script:
node "$CLAUDE_PROJECT_DIR/.claude/skills/jazztips/build-markdown.js" < /tmp/jazztips-meta.json
It prints {"relPath": "src/content/<slug>.md", "markdown": "..."} on stdout. Use the Write tool to write markdown to $CLAUDE_PROJECT_DIR/<relPath>. The frontmatter includes draft: true at this point.
Step 5 — Build, then commit & push (or bail out)
Run the Astro build from $CLAUDE_PROJECT_DIR:
cd "$CLAUDE_PROJECT_DIR" && npm run build
If the build succeeds:
- Remove the
draft: true line from the new file (use the Edit tool — match exact line draft: true\n).
- Commit and push:
cd "$CLAUDE_PROJECT_DIR"
git add src/content/<slug>.md
git commit -m "Add record: <Artist> - <Album>"
git push origin main
- Report the commit SHA, file path, and the live permalink back to the user.
If the build fails:
- Leave the file as-is (
draft: true, unstaged).
- Report the build error output to the user — they will fix and commit themselves.
- Do not attempt to auto-fix or retry.
Field rules (must hold)
title exactly Artist - Album.
release_date year-only is fine if no full date.
tags are genres, never years or numbers.
credits is principal musicians only — strip engineers, designers, photographers, arrangers, producers (producers go in their own field).
description is factual; no opinions, no marketing language.
source_urls ≥ 2 entries.
- Any unknown field →
null. Never drop a key.
Error handling
- If WebSearch returns no usable data after Steps 1–3, stop and report which step failed. Don't write a file with placeholder data.
- If the working tree isn't on
BRANCH or has uncommitted changes, stop and ask the user before touching git.
- If the markdown file already exists, ask whether to overwrite before writing.