Skip to main content
skill CX Codex

promote-idea — Claude Code skill: what it does, how to install

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.

CC0-1.0 188 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 promote-idea -a claude-code
Open on GitHub

What promote-idea does

This skill locates a Pending idea, derives an album slug, and sends the promotion through bitwize-music-mcp. The MCP action creates the album structure, places the idea’s concept in a README.md section, changes the status to In Progress, and writes a Promoted To link back into IDEAS.md.

You can pass a slug yourself or add the documentary flag. That flag also creates RESEARCH.md and SOURCES.md; a regular promotion produces README.md and tracks/. The skill uses Read and bitwize-music-mcp, while get_ideas or search checks the source idea before promotion.

Only Pending ideas are accepted. Promotion is one-way, so there is no built-in undo; renaming the existing album or cleaning it up manually is the stated recovery path.

What it helps with

  • carry an idea’s concept into a new album README
  • scaffold the album directory and track folder
  • move an idea from Pending to In Progress
  • derive a normalized slug from an album title
  • link the original idea to its new album

Example prompts for the agent

  • Run /bitwize-music:promote-idea "Kleine Welt" and turn the idea into an album project.
  • Promote The Great Molasses Flood with the slug molasses-1919.
  • Create the documentary version of The Great Molasses Flood with /bitwize-music:promote-idea "The Great Molasses Flood" documentary.

How to install promote-idea

1Skills CLI (Vercel)

npx skills add bitwize-music-studio/claude-ai-music-skills --skill promote-idea -a claude-code

2Manually: put the files in place

~/.claude/skills/promote-idea/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/promote-idea/

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

Questions about promote-idea

How do I install promote-idea in Claude Code?

Run npx skills add bitwize-music-studio/claude-ai-music-skills --skill promote-idea -a claude-code, then use ~/.claude/skills/promote-idea/SKILL.md.

What does promote-idea do?

It turns a Pending entry from IDEAS.md into an album project, preserving the concept in README.md and updating the idea’s status.

What does the documentary flag change?

Passing documentary adds RESEARCH.md and SOURCES.md to the album structure. The idea’s Documentary type does not set this flag automatically.

Source text

SKILL.md · CC0-1.0
---
name: promote-idea
description: Converts an album idea from IDEAS.md into an actual album project in one step. Use when the user says "promote [idea title]", "turn idea into album", or "start working on [idea]".
argument-hint: <"idea title"> [album-slug-override]
model: haiku
allowed-tools:
  - Read
  - bitwize-music-mcp
---

## Your Task

**Input**: $ARGUMENTS

Convert a `Pending` idea from `IDEAS.md` into a full album project in one
call. Replaces the manual 3-step workflow (`get_ideas` → `new-album` →
`update_idea`) with a single entry point.

---

# Promote Idea Skill

## Step 1: Parse Arguments

Expected formats:

- `"<idea title>"` — auto-derive slug from the title
- `"<idea title>" <album-slug>` — override the auto-derived slug
- `"<idea title>" documentary` — standard slug, documentary flag on
- `"<idea title>" <album-slug> documentary` — explicit slug + documentary

Examples:

- `"Kleine Welt"` → slug auto-derived to `kleine-welt`
- `"The Great Molasses Flood" molasses-flood documentary`
- `"Ängstliche Kätzchen"` → slug `angstliche-katzchen` (diacritics stripped)

**If no arguments are supplied, or the title is empty**, list the available
pending ideas first and ask which one to promote:

```
Which idea should I promote?

Pending ideas:
1. Kleine Welt (electronic, Thematic)
2. The Great Molasses Flood (folk, Documentary)
3. Linux Kernel Wars (electronic, Character Study)

Reply with the exact title.
```

Use `get_ideas(status_filter="Pending")` to fetch the list.

## Step 2: Confirm the Derived Slug

Call `get_ideas(status_filter="Pending")` (or `search(query=idea_title, scope="ideas")`)
to confirm the idea exists and show the user what's about to happen.

Compute the slug locally for display only (lowercase, strip diacritics,
non-alphanumeric → hyphen). If the result looks odd, offer to override:

```
About to promote:
  Idea:  Kleine Welt
  Slug:  kleine-welt
  Genre: electronic
  Type:  Thematic

Proceed? (Or supply a different slug.)
```

Skip the confirmation step if the user has already provided an explicit slug
— that's the signal they've already thought about it.

## Step 3: Ask About Documentary Flag (if not already supplied)

The `documentary` flag decides whether `RESEARCH.md` and `SOURCES.md` are
created. This is **not** derivable from idea metadata — the idea's "Type"
field can say "Documentary" but that's a separate concept (narrative shape).
Ask once:

> Is this a documentary/true-story album? (Adds research + sources
> templates. Answer 'yes' for real-world events, 'no' for fiction.)

Skip this step if `documentary` is already in the arguments.

## Step 4: Promote via MCP

Call `promote_idea(idea_title, album_slug=<slug or "">, documentary=<bool>)`.

The tool performs all of:

1. Find the idea in state (error if missing or already promoted)
2. Create the album directory via `create_album_structure`
3. Inject the idea's concept into the new `README.md` under a `## Concept`
   section
4. Advance idea status `Pending` → `In Progress`
5. Add `**Promoted To**: <slug>` back-link to the idea in `IDEAS.md`

The tool returns `{promoted: true, slug, album_path, files, ...}` on
success or `{error: ...}` on failure.

## Step 5: Confirm and Suggest Next Step

On success, report:

```
Promoted "Kleine Welt" → album "kleine-welt"

Location: ~/bitwize-music/artists/bitwize/albums/electronic/kleine-welt/
Files:    README.md, tracks/

Concept block injected into README.md from idea.
Idea status: Pending → In Progress

Next step:
  /bitwize-music:album-conceptualizer

  This walks through the 7 Planning Phases (Vision, Identity, Sonic
  Direction, Structure, Tracks, Content, Approval) to develop the concept
  you just carried over into the album.
```

For documentary albums, add:

```
  Research files also created: RESEARCH.md, SOURCES.md
  Don't forget human source verification before generation.
```

---

## Error Handling

**Idea not found:**

```
Error: Idea "Nonexistent" not found in IDEAS.md.

Check available ideas: /bitwize-music:album-ideas list
```

**Idea already promoted:**

```
Error: Idea "Already Active" is already promoted (status: In Progress).

If you want to rename or re-scaffold, use /bitwize-music:rename on the
existing album instead.
```

**Idea has no genre:**

```
Error: Idea "No Genre" has no **Genre** field in IDEAS.md.

Set the genre first: /bitwize-music:album-ideas edit "No Genre"
```

**Invalid genre:**

```
Error: Invalid genre "xyz" on idea. Not in genres/.

Fix the genre in IDEAS.md, then retry.
```

**Duplicate album slug:**

```
Error: Album "kleine-welt" already exists.

Options:
1. Supply a different slug: /bitwize-music:promote-idea "Kleine Welt" kleine-welt-2
2. Resume the existing album: /bitwize-music:resume kleine-welt
```

---

## Examples

### Simple title

```
/bitwize-music:promote-idea "Kleine Welt"
```

Auto-derives slug `kleine-welt`, asks about documentary flag, calls
`promote_idea`, reports outcome.

### Explicit slug override

```
/bitwize-music:promote-idea "The Great Molasses Flood" molasses-1919
```

Uses `molasses-1919` instead of the auto-derived `the-great-molasses-flood`.

### Documentary album

```
/bitwize-music:promote-idea "The Great Molasses Flood" documentary
```

Creates `RESEARCH.md` and `SOURCES.md` in addition to the standard README
and tracks directory.

---

## Why a Dedicated Skill

The manual workflow required three steps in sequence:

1. `get_ideas` to find the idea's genre
2. `/bitwize-music:new-album <slug> <genre>` with a slug the user invented
3. `update_idea("<title>", "status", "In Progress")`

Problems this skill solves:

- **Concept transfer** — The idea's concept text is now merged into the new
  album README automatically (manual copy/paste used to be skipped often).
- **Status discipline** — Ideas no longer linger as `Pending` after being
  worked on; the transition is automatic and bidirectional (`Promoted To`
  back-link).
- **Slug derivation** — No more re-inventing the slug; diacritics and
  punctuation are normalized consistently.
- **Single entry point** — Newcomers learn one command instead of three.

---

## Remember

1. **Pending-only** — Only `Pending` ideas can be promoted. `In Progress`
   and `Complete` ideas return an error.
2. **One-way operation** — Promotion creates files and updates state. There
   is no "unpromote"; use `/bitwize-music:rename` or manual cleanup if you
   need to redo.
3. **Concept is preserved** — The idea's concept survives in two places
   after promotion: the idea's entry in `IDEAS.md` (historical record) and
   the new album's `README.md` (working document).
4. **Next step is always album-conceptualizer** — Promotion only scaffolds;
   the actual planning happens in the 7 Planning Phases.

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

Similar skills

SKILL.md skills catalog →

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 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 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 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