/skills-styles

name: skills-styles
description: "Manage the local style library — bundled (24 carousel + 12 video director + 12 music genre) plus user overrides at ~/.claude/style-library/. CRUD + submit (upstream-PR packages) + schema validation. Use when: 'add a custom carousel style', 'create a directorial style', 'genre preset for k-pop', 'list available styles', 'submit my style upstream'."

license: MIT
allowed-tools:
  - Read
  - Write
  - Edit
  - Bash
  - Grep
  - Glob

<objective> Provide a thin CLI on top of `~/.claude/style-library/` so users can manage custom styles without editing dotfiles by hand. The library is the source of truth for `carousel-builder`, `reel-builder`, and `music-prompt` — bundled styles ship with the repo; user overrides + new entries live under `~/.claude/style-library/<modality>/<id>.md` and take priority when the loader resolves a style id.

This skill does NOT:

• Modify bundled styles (under `<repo>/common/style-library/`) — only user overrides.
• Run the auto-PR creation flow end-to-end (no `gh pr create`). The `submit` subcommand builds a self-contained submission package + step-by-step instructions; you run the git ops + the PR yourself.
• Generate the style content for you. The skill creates a template skeleton; YOU (or Claude in the conversation) fill in the anchor + body.
• Manage API keys (that's `skills-keys`) or skill updates (that's `skills-update`).

</objective>

ROLE

Read the user's intent (list / show / add / edit / remove / validate / diff / path / submit) → call the matching `common/runners/cli/styles.py` subcommand → relay the result. For `add` workflows, after the skeleton file is created, OPEN the file and FILL OUT the placeholders based on the user's description, then run `validate` to confirm.

PIPELINE

1. **Parse intent**: which subcommand + modality (carousel|video|music) + style id. 2. **Run** `python3 scripts/run.py <subcommand> [args]`. 3. **For add workflows**: after the skeleton is created, READ the new file, FILL the placeholders (frontmatter + body anchors) using the user's description, then run `validate` to confirm. 4. **Relay the output** — masked / structured by the CLI. 5. **Suggest next step**: edit / validate / submit as appropriate.

MODES

Inspection

• `skills-styles list [modality]` — show all styles with status (bundled / user-only / override)
• `skills-styles list [modality] --user-only` — only user-overrides
• `skills-styles list [modality] --bundled-only` — only bundled
• `skills-styles show <modality> <id>` — print the resolved file (user wins over bundled)
• `skills-styles path [modality] [id]` — print resolved path

Creation + edit

• `skills-styles add <modality> <id>` — create a new user style from the bundled template
• `skills-styles add <modality> <id> --from <existing-id>` — start as a copy of an existing style
• `skills-styles add <modality> <id> --force` — overwrite if it already exists
• `skills-styles edit <modality> <id>` — open the user-override in `$EDITOR`
• `skills-styles remove <modality> <id> --force` — delete the user-override (reverts to bundled if any)

Validation

• `skills-styles validate <modality> <id>` — frontmatter + body schema check per modality
• `skills-styles diff <modality> <id>` — diff user-override vs bundled (useful when customizing a bundled style)

Upstream PR

• `skills-styles submit <modality> <id>` — validate, then build `./style-submission-<ts>-<modality>-<id>/` with the file at the correct repo path + a PR description template + a step-by-step instructions README. You do the git ops + `gh pr create` manually.

REFERENCES (load on demand)

| File | When to load | |---|---| | [references/usage.md](references/usage.md) | Detailed UX for each subcommand — exit codes, edge cases, examples | | [references/templates.md](references/templates.md) | Per-modality frontmatter schema + required body fields + validation rules + conventions reviewers enforce on PRs |

EXAMPLES

See [examples/before-after.md](examples/before-after.md) — 4 example sessions: create a carousel style from scratch via template, create a video style as a copy of `fincher-cold-lowkey`, validate + submit a music genre to upstream, customize a bundled style (override → edit → diff → submit).

CONSTRAINTS

• **Bundled styles are read-only.** This skill operates ONLY on `~/.claude/style-library/`. To modify a bundled style, use `add --from <id>` to copy it, then edit the user override.

• **User wins on resolution.** When both a bundled `<id>.md` and a user `<id>.md` exist, the loader picks user. `skills-styles list` shows the `override` status so you know.

• **Add doesn't auto-fill the content.** It creates a skeleton with `<placeholders>`. After `add`, YOU (or Claude in the chat) fill the file based on user intent, then run `validate`.

• **Validation is strict on schema, soft on content.** It checks frontmatter shape + required body fields + anchor length. It does NOT enforce style guidelines (no copyrighted artist names, no real-brand mimicry, no clichés) — those are reviewer checks during PR. The skill prints reviewer-checklist reminders in the submission package.

• **Submit doesn't run git.** v1 prepares a submission package + prints exact instructions. Users do `git clone fork → cp → commit → push → gh pr create` themselves. Auto-PR is intentionally deferred — fork detection + multi-step gh interaction is brittle.

• **Submit validates first.** If the style has schema issues, submit refuses unless `--force` is passed. Don't submit broken styles upstream.

• **No copyrighted living-artist names in anchor text.** The `video/_template.md` warning + the PR checklist enforce this. Bundled video styles store the director's name in `display:` and `Inspired by:` ONLY — those fields are user-facing, not model-facing.

• **No real-brand mimicry in anchor text.** "Apple's WWDC look" / "Stripe's hero" are banned. Use era + cultural movement instead ("developer-platform brand aest