kdp-listing

What this skill does

# KDP Listing Craft

Generate the four marketing artifacts for an Amazon KDP listing: blurb (book description), keywords, BISAC categories, and author bio. This skill gathers just enough context about the book to write effective marketing copy, then saves all artifacts to the user's project config.

## Workflow

### 1. Load User Config

Read `.claude/kdp.local.md` if it exists (Read tool). Extract the `kdp` section and `author` metadata from YAML frontmatter. Key fields to look for:

- `kdp.blurb` — existing blurb draft (if any)
- `kdp.keywords` — existing keyword list
- `kdp.categories` — existing BISAC categories
- `kdp.author_bio` — existing bio
- `kdp.pen_name` — pen name (if different from `author.name`)
- `kdp.series` — series name and volume number
- `kdp.genre` — declared genre
- `author.name` — author's real name
- `author.bio` — general bio text

If the config file is missing, offer to create one from the template at `${CLAUDE_PLUGIN_ROOT}/docs/user-config-template.md`.

### 2. Analyze the Manuscript

Gather enough context to write marketing copy. This skill does not read or analyze the full manuscript — it collects what it needs to sell the book.

**Scan for existing context docs** (Glob tool):
Search for files that summarize the book's content and intent:
- `outline*`, `synopsis*`, `summary*`, `pitch*`
- `worldbuild*`, `blurb*`, `logline*`
- `README*`, `CONCEPT*`, `PREMISE*`

**Read found docs** (Read tool):
Read any matching files. These often contain the clearest distillation of what the book is about — more useful for marketing copy than the manuscript itself.

**Read the opening** (Read tool):
Find and read the first chapter or opening section to understand tone, voice, and genre register. Look for the first chapter file, or the first 100 lines of the main manuscript file. The opening establishes the voice that the blurb should echo.

**Ask the user to fill gaps**:
After reading available context, ask for anything still missing:
- Describe the book in 2-3 sentences (the "elevator pitch")
- Name the core conflict or central question
- Identify 2-3 comparable titles ("readers who liked X will like this")
- Describe the target reader (who picks this book up and why)

### 3. Draft Blurb

The blurb is the single most important marketing asset. It appears on the Amazon product page and its first two sentences appear in search results.

**Check existing blurb**: If `kdp.blurb` is non-empty in the config, present it and ask: refine the existing blurb, or start fresh?

**Consult exemplars** (Read tool):
Reference the exemplar blurb patterns for genre-appropriate structures, anti-patterns, and annotated examples.

**Structure by book type**:

*Fiction*: Hook sentence (concrete, visual, specific) -> escalation of conflict -> stakes (both personal and external) -> NO spoilers past the first act -> comp-title call to action.

*Nonfiction*: Problem the reader faces -> promise of what the book delivers -> author's authority to deliver it -> what the reader will gain or be able to do.

*Technical*: What the book covers and why it matters -> who it is for (specific audience) -> what makes it different from other books on the topic.

**Generate 2-3 variants** for the user to pick from or combine. Each variant should take a different angle on the hook or emphasize different stakes.

**Apply HTML formatting** for Amazon display:
- `<b>` for emphasis on hook lines or key phrases
- `<i>` for comp-title CTAs and book titles
- `<br>` for paragraph breaks (Amazon strips standard line breaks)

**Validate**:
- Under 4000 characters (Amazon's hard limit)
- Hook lands in the first 2 sentences (these are what Amazon shows in search results and category browse pages — everything after is behind the "Read more" fold)
- No spoilers beyond the first act or first 20% of the book
- No superlative claims ("the best," "an unforgettable," "a masterpiece")
- No external links or contact information

**Iterate** with the user until they are satisfied with the blurb. Offer specific revisions: tighten the hook, raise the stakes, adjust tone, add or remove comp titles.

### 4. Keywords (7 Slots)

Each keyword slot can hold a phrase up to 50 characters. Keywords supplement the title, subtitle, and categories — they help readers find the book through Amazon search but do not appear on the listing page.

**Consult exemplars** (Read tool):
Consult the exemplars reference doc for effective keyword patterns and TOS boundaries.

**Generate keyword candidates** using these strategies:
- Genre + subgenre phrases (e.g., "dark fantasy sword and sorcery")
- Thematic phrases readers search for (e.g., "reluctant hero quest")
- Setting and tone markers (e.g., "small town mystery")
- Comp-adjacent phrasing without naming authors (e.g., "books like grimdark fantasy")

**Rules**:
- Do NOT repeat words already in the title or subtitle (they are indexed automatically)
- Do NOT use competitor author names or book titles (TOS violation)
- Do NOT use subjective claims ("best," "award-winning")
- Do NOT use temporary claims ("new release 2026")
- Each keyword should pass the test: would a reader searching this phrase be happy to find this book?

**Present recommendations** with reasoning for each keyword. Explain what search behavior each phrase targets. Let the user adjust, swap, or reorder.

### 5. BISAC Categories (Up to 3)

Amazon uses BISAC (Book Industry Standards and Advisory Committee) codes for browse classification. Select 2 categories at setup (3 for print books). After publication, request up to 10 total via KDP support.

**Consult exemplars** (Read tool):
Consult the exemplars reference doc for example BISAC paths and the niche-vs-broad trade-off.

**Recommend specific subcategories** over broad top-level categories. Choosing "Fiction > Fantasy > Epic" places the book in three browse paths (Epic, Fantasy, Fiction), while choosing just "Fiction > Fantasy" gives only two.

**Explain the niche-vs-broad trade-off**: Narrow categories have fewer competitors but also fewer browsers. The goal is to rank in a category where the book can reach the top 20, which earns visibility on the category page.

**Present 2-3 primary recommendations** plus 2-3 post-publish expansion candidates. For each, explain why the book fits and what the competitive landscape looks like.

### 6. Author Bio

The author bio appears on the Amazon product page and the Author Central page. Maximum 2000 characters.

**Pull existing data**: Use `author.name` (or `kdp.pen_name` if set) and `author.bio` from the config as a starting point.

**Consult exemplars** (Read tool):
Consult the exemplars reference doc for genre conventions and annotated bio examples.

**Adapt for genre context**:
- *Genre fiction* (fantasy, thriller, sci-fi, romance): Third person. Lead with genre credentials and personality. Light tone is welcome.
- *Literary fiction*: Third person or first person. Lead with publications, awards, residencies. More restrained tone.
- *Technical/nonfiction*: Third person. Lead with professional credentials and expertise relevant to the book's topic.

**Draft the bio** following these principles:
- Lead with what makes the author credible for this specific book
- Include geographic grounding (readers like knowing where authors live)
- If previous publications exist, name them; if not, don't apologize for it
- One personal detail humanizes; three personal details pad
- Keep under 2000 characters

### 7. Series Metadata (If Applicable)

**Check config**: Look for `kdp.series` in the user config.

**If not set**, ask whether the book is part of a series. If yes, capture:
- Series name
- Volume number (e.g., "Book 1")
- Whether earlier volumes are already published

**If part of a series**, note that all books in the series should share at least one BISAC category to keep them grouped in browse results and strengthen the series page.

### 8. Save Artifacts

Write all outputs back to `.claude/kdp.local.md` under the `kdp` se