skills-styles

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

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	Detailed UX for each subcommand — exit codes, edge cases, examples
references/templates.md	Per-modality frontmatter schema + required body fields + validation rules + conventions reviewers enforce on PRs

EXAMPLES

See 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 aesthetic of the 2022-2025 era").

• No emoji. Anywhere in any style file. Reviewer rejects.

• id must be kebab-case (^[a-z][a-z0-9-]{1,40}$). The validator enforces.

• Style anchor minimum 40 chars. The validator enforces. Shorter anchors lose to the per-slide content prompt.

• Use the bundled templates (common/style-library/<modality>/_template.md) as the schema reference. They contain inline conventions + the validator targets exactly that shape.

• For Claude to fill content: after add, read the new file at the path printed by stdout, edit each <placeholder> based on the user's description, then run validate to confirm the result is parseable. Don't skip the validate step.

INVOCATION HINTS

When the user says any of:

• "add a custom style for X", "create a carousel style called Y"
• "make a video style inspired by [director]", "build a music genre preset"
• "list available styles", "show what's in [style-id]"
• "edit the [style-id] style", "tweak the [style-id]"
• "remove my [style-id] style"
• "validate my style", "check if [style-id] is valid"
• "submit my style upstream", "send [style-id] to the repo", "PR my carousel style"
• "diff my override against bundled"

RU triggers:

• «добавь свой стиль для X», «создай carousel стиль »
• «сделай директорский стиль в духе X», «сделай music-пресет жанра Y»
• «покажи доступные стили», «что внутри [style-id]»
• «отредактируй стиль [style-id]», «правка [style-id]»
• «удали мой стиль [style-id]»
• «провалидируй стиль», «проверь корректность [style-id]»
• «отправь стиль наверх / в апстрим», «PR мой carousel стиль»
• «дифф моего override и bundled»

Defaults when intent is ambiguous: list (safe — read-only, shows what's available).

This is a meta-skill, sibling to skills-keys and skills-update. All three wrap common/runners/cli/... plumbing. Their outputs are tool outputs to be relayed honestly — don't paraphrase the validation results, just show them.

When the user creates a new style and gives a brief description, the recommended flow is:

1. skills-styles add <modality> <id> — create skeleton
2. Read the newly created file
3. Fill the frontmatter + body anchors based on the user's description
4. skills-styles validate <modality> <id> — confirm schema
5. Optionally: skills-styles submit <modality> <id> — prepare PR package

For modifying a bundled style:

1. skills-styles add <modality> <id> --from <id> — copy bundled as starting point
2. Edit the user-override file (the file the user is allowed to change)
3. skills-styles diff <modality> <id> — review what changed
4. skills-styles validate <modality> <id>
5. Optionally submit upstream