/brand-lock-extractor

name: brand-lock-extractor
description: Extract a production-ready brand-lock.md from a brand's existing assets. Point it at a website URL, a brand book PDF, screenshots, or a written description and it produces the nine-section brand-lock the rest of shotkit consumes, with a confidence and source noted for every value. Use when the user wants to onboard a brand, says "build a brand lock", "extract my brand", "make a brand pack from my site", or hands over brand assets. The cold-start killer that turns a blank brand-pack template into a filled, validate-ready file. Pairs with storyboard-architect downstream.

Brand Lock Extractor

The blank `brand-packs/_template.md` is the single biggest point of friction in shotkit. Nobody wants to hand-author nine sections of brand parameters before they can produce a single storyboard. This skill removes that wall: hand it what you already have, get a filled brand-lock back.

The output is a `brand-lock.md` in the exact format `tools/validate_brand_lock.py` validates and every other skill consumes. Same file the pipeline reads, produced from your assets instead of from scratch.

This skill extracts. It does not invent. Every value is sampled from a real asset or flagged as an estimate the user must confirm. A confident-sounding wrong hex is worse than a flagged guess.

When to use

Trigger when the user:

• Wants to onboard a brand into shotkit and has assets (a site, a brand book, screenshots)
• Says "extract my brand", "build a brand lock", "make a brand pack from my site/PDF"
• Hands over a URL, a PDF, image files, or a written brand description and asks for a brand-lock
• Has a brand-lock that is half-filled and wants the gaps extracted from assets

If the user has nothing but a vague idea (no assets, no description), they are not extracting, they are authoring. Point them at `brand-packs/_template.md` and help them fill it directly.

Inputs

You can work from any one of these. More sources is a better extraction.

| Source | How you read it | Best for | |---|---|---| | Website URL | `WebFetch` homepage + about + one more page | Voice, positioning, palette, type | | Brand book PDF | `Read` the PDF | Palette (exact hex), type, motion rules | | Screenshots / image files | `Read` the images | Palette (sample pixels), mood, layout | | Written description | Use directly | Identity, archetype, voice posture |

At minimum you need one source. If the user offers none, ask for the one they have: **"What can I work from, a website URL, a brand book PDF, screenshots, or a short description?"** One question.

Workflow

Step 1. Gather the source material

• **URL:** `WebFetch` the homepage, then try the about page (`/about`, `/about-us`, `/our-story`) and one more (`/services`, `/work`, recent blog). Skip pages that 404. The homepage is the floor.
• **PDF / images:** `Read` each file. Brand books carry exact hex and type; screenshots are for sampling color and reading mood.
• **Description:** take it as written.

Tell the user what you are pulling. Do not ask follow-ups yet, extract first, confirm gaps at the end.

Step 2. Extract each section

Read `references/extraction-rubric.md`. It maps every brand-lock section to where the signal lives and how to read it. Work the nine sections in order:

1. **Identity** (brand, one-line description, archetype, voice posture) 2. **Palette** (sampled hex, by role) 3. **Typography** (display, body, optional mono, with weights) 4. **Mood adjectives** (3-5, specific, contrast clauses preferred) 5. **Never list** (what the brand avoids, inferred from consistency) 6. **Aspect ratios** 7. **Color grade direction** (one sentence) 8. **Motion language** (one paragraph) 9. **Voice rules** (copy-level constraints)

For every value, hold two things: the value, and where it came from (which asset, which quote, which sampled swatch). You will need the source for the confidence pass.

Step 3. Assign confidence and flag estimates

Each value is one of:

• **extracted**, read directly from an asset (a hex in the brand book, a font in the CSS, a quote from the site). State it plainly.
• **inferred**, reasoned from evidence but not stated (archetype from positioning, never-list from consistency). Reasonable to ship, worth noting.
• **needs confirmation**, your best estimate where the assets were silent or ambiguous (a color sampled from a JPEG with compression, a font you could not identify). Fill it, then flag it.

Step 4. Write the brand-lock

Use `templates/brand-lock.md.tpl`. Fill **every** required section, no placeholders left behind. Then append an `## Extraction notes` section that lists every `inferred` and `needs confirmation` value with its source and your reasoning. This section is the audit trail; it does not break validation (the validator checks the nine required sections are present, extra sections are fine).

Set the footer: `Last updated` to today, `Owner` to the user or "extracted", `Version: 1.0`.

Step 5. Self-check, then hand off

Before you present it, confirm the file would pass validation:

• All nine required sections present: Identity, Palette, Typography, Mood adjectives, Never list, Aspect ratios, Color grade direction, Motion language, Voice rules.
• Identity contains all four fields: Brand, One-line description, Archetype, Voice posture.
• Palette has at least one real `#RRGGBB` hex (not a placeholder).

Then hand off:

> "Here is your brand-lock. I sampled the palette and type from your assets and flagged N values that need your eyes (see Extraction notes). Drop it in `brand-packs/`, confirm the flagged values, and run `python tools/validate_brand_lock.py path/to/file.md` to verify. Then: `'30-second explainer. Use brand-packs/your-brand.md as the brand lock.'`"

Hard rules

Rule 1. Never invent a hex value

Colors are sampled, never guessed. Read them from a brand book, from CSS, or by sampling pixels in a screenshot. If you genuinely cannot determine a color,