skilldrop-cli 0.16.3__py3-none-any.whl

skilldrop_cli/data/packs/design/skills/brand-kit/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: brand-kit
+description: Capture a brand once as a reusable brand.json — logo files (and an on-dark version), colour roles as hex codes, heading and body fonts, voice, imagery rules, a PowerPoint template, contact details and the legal footer — plus a one-page BRAND.md, with text contrast checked and every value traced to where it came from. Use when the user wants decks, flyers or documents in their branding, says "use our brand", "here's our logo and colours", "set up our brand kit", or hands over brand guidelines.
+---
+
+# brand-kit
+
+You turn whatever the user has about their brand (logo files, a guidelines PDF, a website, a
+few hex codes, "we use green") into one `brand.json` that other skills build from:
+[`deck-builder`](../deck-builder/SKILL.md) for PowerPoint decks and
+[`marketing-flyer`](../marketing-flyer/SKILL.md) for flyers. Capturing the brand once means
+nobody answers the same questions for every deck, and the deck and the flyer match.
+
+## How to respond
+
+1. **Ask for everything in one message, and take what they already gave.** Never ask for
+   something the user already supplied.
+
+   > To set up your brand kit, send whatever you have. Anything you skip I'll either take from
+   > what you sent or leave for you to confirm:
+   > 1. **Brand name**, and a tagline if you use one
+   > 2. **Logo files.** The main logo, plus a white or light version for dark backgrounds if
+   >    you have one. PNG is best; SVG works for flyers, but PowerPoint needs PNG.
+   > 3. **Colours** as hex codes (`#0E5A46`), or a guidelines PDF or website I can read them from
+   > 4. **Fonts** for headings and body text
+   > 5. **Voice:** how you sound, and words you always or never use
+   > 6. **Imagery:** the kind of photos or illustrations you use, and what to avoid
+   > 7. **A PowerPoint template** (`.potx` or `.pptx`) if your company has one
+   > 8. **Contact and legal:** website, email, phone, and any footer line such as "© 2026 …"
+
+2. **Read the sources the user points to.** From a guidelines PDF or website, extract colour
+   hex codes, font names, logo usage rules and voice. Tag every value with where it came from
+   in `sources`: `[explicit]` when the source states it, `[inferred]` when you derived it (a
+   colour sampled from the logo, a tone read from the About page). Never present an inferred
+   value as the brand's own rule.
+
+3. **Fill the five colour roles.** The roles are `primary` (main brand colour; slide title
+   bars, flyer bands), `secondary` (supporting), `accent` (highlights, calls to action),
+   `background` and `text`. If the user gave one or two colours, derive the rest and say which
+   roles you filled. Usually `background` is white or a near-white tint of the primary,
+   `text` is a near-black, and `secondary` is a lighter or darker step of the primary.
+
+4. **Write the files** next to the logo files, so relative paths resolve:
+   - `brand.json`, in the shape of [`templates/brand.json`](templates/brand.json). Leave a
+     field out instead of guessing it.
+   - `BRAND.md`: one page with the name, colour swatches as a table (role, hex, use), fonts,
+     voice, imagery rules and logo rules, readable by a person who never opens the JSON.
+
+5. **Check it.**
+
+   ```bash
+   # Claude Code
+   python3 "${CLAUDE_SKILL_DIR}/scripts/check_brand.py" ./brand/brand.json
+   # Other IDEs (from the skill folder)
+   python3 scripts/check_brand.py ./brand/brand.json
+   ```
+
+   It fails on a malformed hex code, text-on-background contrast below 4.5:1, a missing logo
+   file or template. It warns when white text on the primary is hard to read, when the accent
+   is too light for text, when a logo is SVG or EPS, or when fonts aren't set. Fix the
+   failures. Report each warning with what it means for the deck or flyer.
+
+6. **Hand off.** Tell the user the path to `brand.json` and that `deck-builder` and
+   `marketing-flyer` will use it: `build_deck.py --brand brand.json`, or the flyer spec's
+   `brand` field.
+
+**Non-interactive runs** (subagent, CI, headless): never invent a brand colour, font or logo.
+Use only what the input supplies, tag derived colours `[inferred]`, and list missing fields
+at the top of the response. With no brand material at all, emit `BLOCKED: need at least a
+brand name and either a logo file or one brand colour`.
+
+## Useful references in this skill
+
+- [`templates/brand.json`](templates/brand.json) — the full shape, with every field filled in for a sample brand
+- [`scripts/check_brand.py`](scripts/check_brand.py) — the checker: hex format, contrast, logo files and formats, template
+- [`examples/northwind-brand.md`](examples/northwind-brand.md) — worked example: a logo, two hex codes and a website become a brand kit
+
+## Quality bar
+
+- **Every colour is a hex code with a role.** "Our green" is not a brand colour; `#0E5A46` used for title bars is.
+- **Text on background passes 4.5:1,** checked by the script rather than by eye.
+- **Every value says where it came from,** and inferred values are marked as inferred.
+- **Logo files are real paths that exist,** with a PNG for PowerPoint and an on-dark version when the brand has one.
+- **Nothing is invented.** A field the user didn't supply and couldn't be read from their sources is left out and listed, not guessed.
+- **BRAND.md fits on one page.** A person checks the brand from it without opening the JSON.
+
+## When to use this skill
+
+- ✅ Before the first branded deck or flyer, so both come out in the same brand
+- ✅ The user hands over brand guidelines, a logo, or a website and asks for things "in our style"
+- ✅ A brand has changed and the old `brand.json` needs updating
+
+## When NOT to use this skill
+
+- ❌ Designing a new brand from scratch: this captures a brand, it doesn't invent one
+- ❌ Building the deck or flyer itself; use `deck-builder` or `marketing-flyer`
+- ❌ A one-off document where the user only wants the default look
+
+## Anti-patterns to avoid
+
+- ❌ **Asking eight separate questions** instead of one message with everything.
+- ❌ **Sampling a colour from a JPEG** and recording it as the official hex without the `[inferred]` tag.
+- ❌ **Accepting an SVG logo for PowerPoint use** without saying a PNG is needed.
+- ❌ **Picking a pale accent as the text colour** because it is "on brand". It fails contrast and nobody can read it.
+- ❌ **Filling the voice section with adjectives** ("innovative, passionate"). Words to use and words to avoid are what a writer can act on.

skilldrop_cli/data/packs/design/skills/brand-kit/evals/eval_queries.json

@@ -0,0 +1,30 @@
+[
+  {
+    "query": "Here's our logo and brand colours \u2014 set up a brand kit we can reuse",
+    "should_trigger": true
+  },
+  {
+    "query": "Use our brand guidelines PDF so everything matches our style",
+    "should_trigger": true
+  },
+  {
+    "query": "Capture our fonts, colours and logo rules in one place",
+    "should_trigger": true
+  },
+  {
+    "query": "Make our decks and flyers on-brand \u2014 start with the brand settings",
+    "should_trigger": true
+  },
+  {
+    "query": "Build a PowerPoint deck for the board meeting",
+    "should_trigger": false
+  },
+  {
+    "query": "Make a flyer for our open day",
+    "should_trigger": false
+  },
+  {
+    "query": "Design a new logo for my startup",
+    "should_trigger": false
+  }
+]

skilldrop_cli/data/packs/design/skills/brand-kit/evals/evals.json

@@ -0,0 +1,18 @@
+{
+  "skill_name": "brand-kit",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Set up our brand kit. Logo is ./brand/northwind-logo.png and there's a white version ./brand/northwind-logo-white.png. Our colours are #0E5A46 and #F2A541. We use Georgia for headings. Website is northwindhealth.example.",
+      "assertions": [
+        "Writes brand.json next to the logo files, with logo.primary and logo.on_dark set to the two supplied paths",
+        "colors.primary is #0E5A46 and colors.accent is #F2A541; secondary, background and text are filled and listed as derived",
+        "fonts.heading.family is Georgia; the body font is either asked for or marked as a default, not presented as the brand's",
+        "Every value has a source, with derived values tagged [inferred]",
+        "Runs check_brand.py and reports its contrast figures",
+        "Writes a one-page BRAND.md with a colour table (role, hex, use)",
+        "Invents no tagline, phone number, address or legal footer"
+      ]
+    }
+  ]
+}

skilldrop_cli/data/packs/design/skills/brand-kit/examples/northwind-brand.md

@@ -0,0 +1,48 @@
+# Worked example — a logo, two colours and a website become a brand kit
+
+## Input given to the skill
+
+> Set up our brand kit. Logo is `./brand/northwind-logo.png` and there's a white version
+> `./brand/northwind-logo-white.png`. Our colours are `#0E5A46` and `#F2A541`. We use Georgia
+> for headings. Website is northwindhealth.example.
+
+---
+
+**Wrote** `./brand/brand.json` and `./brand/BRAND.md`.
+
+**Filled for you, please confirm:** `secondary` `#3D7F6B` (a lighter step of your green),
+`background` `#FFFFFF` and `text` `#1F2A28` (near-black with a green cast). Voice is read
+from your About page and tagged `[inferred]`.
+
+**Not set (nothing supplied):** body font, tagline, phone, address, legal footer, PowerPoint
+template. Tell me your body font; until then decks and flyers use their defaults.
+
+```
+$ python3 scripts/check_brand.py ./brand/brand.json
+  text on background   14.79:1
+  white on primary      8.17:1
+WARN accent on background is 2.05:1 — use the accent for shapes and rules, not text
+WARN fonts.body is not set; generators fall back to their defaults
+OK: brand.json — 0 failure(s), 2 warning(s)
+```
+
+### BRAND.md
+
+| Role | Hex | Use |
+|---|---|---|
+| primary | `#0E5A46` | Slide title bars, flyer header band, buttons |
+| secondary | `#3D7F6B` | Charts, secondary panels |
+| accent | `#F2A541` | Call to action, highlights; shapes and rules, never body text |
+| background | `#FFFFFF` | Page and slide background |
+| text | `#1F2A28` | Body text |
+
+- **Fonts:** headings Georgia (from you); body font not set yet
+- **Logo:** full colour on white; the white version on the green. Never the full-colour logo on the green.
+- **Voice** `[inferred]`: warm and plain, short sentences. Says "members", not "patients".
+
+---
+
+**Why this is a good output:** it uses every fact the user gave and invents none. It fills only
+the colour roles a deck needs, says which ones it filled, and leaves the tagline and legal
+footer empty rather than making them up. The checker's figures show white titles on the
+green will read, and its accent warning is carried into BRAND.md as "never body text".

skilldrop_cli/data/packs/design/skills/brand-kit/manifest.json

@@ -0,0 +1,45 @@
+{
+  "name": "brand-kit",
+  "version": "0.1.0",
+  "description": "Capture a brand once as a reusable brand.json — logo files (and an on-dark version), colour roles as hex codes, heading and body fonts, voice, imagery rules, a PowerPoint template, contact details and the legal footer — plus a one-page BRAND.md, with text contrast checked and every value traced to where it came from. Use when the user wants decks, flyers or documents in their branding, says \"use our brand\", \"here's our logo and colours\", \"set up our brand kit\", or hands over brand guidelines.",
+  "entrypoint": "SKILL.md",
+  "deps": {
+    "npm": [],
+    "pip": []
+  },
+  "env": {
+    "required": [],
+    "optional": []
+  },
+  "related": [
+    "deck-builder",
+    "marketing-flyer"
+  ],
+  "handoff": [
+    {
+      "to": "deck-builder",
+      "when": "the brand kit is written and the user wants a deck",
+      "purpose": "Build the PowerPoint deck in this brand: build_deck.py --brand brand.json.",
+      "fallback": "If deck-builder is absent, give the user the brand.json path and the five hex codes to paste into whatever deck tool they use."
+    },
+    {
+      "to": "marketing-flyer",
+      "when": "the brand kit is written and the user wants a flyer or one-page sheet",
+      "purpose": "Build a print-ready flyer in this brand from the flyer spec's brand field.",
+      "fallback": "If marketing-flyer is absent, give the user BRAND.md so a designer or tool can apply it by hand."
+    }
+  ],
+  "tags": [
+    "brand",
+    "logo",
+    "colours",
+    "fonts",
+    "design",
+    "style-guide"
+  ],
+  "permissions": {"network": [], "commands": [], "files": "none", "notes": "The checker reads brand.json and the files it names, and writes nothing."},
+  "model": {
+    "tier": "standard",
+    "rationale": "Extracts and normalises brand facts from files and pages, then runs a checker. Bounded synthesis."
+  }
+}

skilldrop_cli/data/packs/design/skills/brand-kit/scripts/check_brand.py

@@ -0,0 +1,114 @@
+#!/usr/bin/env python3
+"""Check a brand.json before anything is generated from it. Stdlib only.
+
+Checks:
+  - every colour role is a 6-digit hex code
+  - text on background, and white on primary, reach WCAG AA contrast (4.5:1)
+  - each logo file exists, and is PNG or JPG (PowerPoint cannot place SVG or EPS)
+  - a referenced .pptx/.potx template exists
+  - heading and body fonts are named
+
+Usage:
+  python3 check_brand.py path/to/brand.json
+Exit code 1 if any check fails; warnings alone exit 0.
+"""
+import json
+import re
+import sys
+from pathlib import Path
+
+HEX = re.compile(r"^#[0-9A-Fa-f]{6}$")
+ROLES = ("primary", "secondary", "accent", "background", "text")
+
+
+def luminance(hex_str):
+    h = hex_str.lstrip("#")
+    def ch(v):
+        v = int(v, 16) / 255
+        return v / 12.92 if v <= 0.03928 else ((v + 0.055) / 1.055) ** 2.4
+    r, g, b = (ch(h[i:i + 2]) for i in (0, 2, 4))
+    return 0.2126 * r + 0.7152 * g + 0.0722 * b
+
+
+def contrast(a, b):
+    la, lb = sorted((luminance(a), luminance(b)), reverse=True)
+    return (la + 0.05) / (lb + 0.05)
+
+
+def main(argv):
+    if len(argv) != 1:
+        print(__doc__)
+        return 2
+    path = Path(argv[0]).expanduser().resolve()
+    base = path.parent
+    try:
+        brand = json.loads(path.read_text())
+    except (OSError, json.JSONDecodeError) as e:
+        print(f"FAIL cannot read {path}: {e}")
+        return 1
+    fails, warns = [], []
+
+    colors = brand.get("colors") or {}
+    for role in ROLES:
+        v = colors.get(role)
+        if not v:
+            warns.append(f"colors.{role} is missing; the generators will derive it from the others")
+        elif not HEX.match(v):
+            fails.append(f"colors.{role} is {v!r}, not a 6-digit hex code like #1A2A6C")
+    for x in colors.get("extra") or []:
+        if not HEX.match(str(x.get("hex", ""))):
+            fails.append(f"colors.extra {x.get('name', '?')!r} has hex {x.get('hex')!r}")
+    if HEX.match(colors.get("text", "")) and HEX.match(colors.get("background", "")):
+        r = contrast(colors["text"], colors["background"])
+        if r < 4.5:
+            fails.append(f"text on background contrast is {r:.2f}:1, below 4.5:1")
+        print(f"  text on background   {r:5.2f}:1")
+    if HEX.match(colors.get("primary", "")):
+        r = contrast("#FFFFFF", colors["primary"])
+        msg = f"white text on primary is {r:.2f}:1"
+        if r < 4.5:
+            warns.append(msg + " — slide title bars and flyer bands will use dark text instead")
+        print(f"  white on primary     {r:5.2f}:1")
+    if HEX.match(colors.get("accent", "")) and HEX.match(colors.get("background", "")):
+        r = contrast(colors["accent"], colors["background"])
+        if r < 3:
+            warns.append(f"accent on background is {r:.2f}:1 — use the accent for shapes and rules, not text")
+
+    logo = brand.get("logo") or {}
+    if isinstance(logo, str):
+        logo = {"primary": logo}
+    if not logo.get("primary") and not logo.get("on_dark"):
+        warns.append("no logo file — decks and flyers will carry the brand name as text instead")
+    for field in ("primary", "on_dark", "mark"):
+        ref = logo.get(field)
+        if not ref:
+            continue
+        lp = (base / ref) if not Path(ref).is_absolute() else Path(ref)
+        if not lp.exists():
+            fails.append(f"logo.{field} {ref!r} does not exist (looked in {lp.parent})")
+        elif lp.suffix.lower() not in (".png", ".jpg", ".jpeg"):
+            warns.append(f"logo.{field} is {lp.suffix}: fine for the flyer, but PowerPoint needs PNG or JPG — export one")
+
+    tpl = (brand.get("templates") or {}).get("pptx")
+    if tpl:
+        tp = (base / tpl) if not Path(tpl).is_absolute() else Path(tpl)
+        if not tp.exists():
+            fails.append(f"templates.pptx {tpl!r} does not exist")
+
+    fonts = brand.get("fonts") or {}
+    for role in ("heading", "body"):
+        f = fonts.get(role)
+        fam = f.get("family") if isinstance(f, dict) else f
+        if not fam:
+            warns.append(f"fonts.{role} is not set; generators fall back to their defaults")
+
+    for w in warns:
+        print(f"WARN {w}")
+    for f in fails:
+        print(f"FAIL {f}")
+    print(f"{'FAILED' if fails else 'OK'}: {path.name} — {len(fails)} failure(s), {len(warns)} warning(s)")
+    return 1 if fails else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

skilldrop_cli/data/packs/design/skills/brand-kit/templates/brand.json

@@ -0,0 +1,54 @@
+{
+  "$comment": "brand-kit output. deck-builder and marketing-flyer read this file; any field left out is asked for or defaulted by them. Paths are relative to this file. Every value carries where it came from in `sources`.",
+  "name": "Northwind Health",
+  "tagline": "Care that comes to you",
+  "logo": {
+    "primary": "logo.png",
+    "on_dark": "logo-white.png",
+    "mark": "mark.png",
+    "notes": "Keep clear space equal to the height of the N on every side. Never place the full-colour logo on the green."
+  },
+  "colors": {
+    "primary": "#0E5A46",
+    "secondary": "#3D7F6B",
+    "accent": "#F2A541",
+    "background": "#FFFFFF",
+    "text": "#1F2A28",
+    "extra": [
+      { "name": "Mist", "hex": "#E8F1EE", "use": "panel backgrounds" }
+    ]
+  },
+  "fonts": {
+    "heading": { "family": "Georgia", "fallback": "serif", "weight": 700 },
+    "body": { "family": "Arial", "fallback": "sans-serif", "weight": 400 }
+  },
+  "voice": {
+    "tone": "Warm, plain, confident. Short sentences.",
+    "use": ["members", "care team", "near you"],
+    "avoid": ["patients", "cutting-edge", "solutions"]
+  },
+  "imagery": {
+    "style": "Real people in daylight, community settings, no stock handshakes.",
+    "do": ["natural light", "diverse ages"],
+    "dont": ["clinical close-ups", "illustrated icons as hero images"]
+  },
+  "templates": {
+    "pptx": "northwind-master.potx"
+  },
+  "contact": {
+    "website": "northwindhealth.example",
+    "email": "hello@northwindhealth.example",
+    "phone": "",
+    "address": ""
+  },
+  "legal": {
+    "footer": "© 2026 Northwind Health",
+    "disclaimer": ""
+  },
+  "sources": {
+    "colors": "brand guidelines PDF, page 4 [explicit]",
+    "fonts": "brand guidelines PDF, page 6 [explicit]",
+    "voice": "website About page [inferred]",
+    "logo": "files supplied by the user [explicit]"
+  }
+}

skilldrop_cli/data/packs/design/skills/deck-builder/SKILL.md

@@ -0,0 +1,201 @@
+---
+name: deck-builder
+description: Generate a real PowerPoint (.pptx) file from content, audience, and either a brand template or a color palette — with charts, tables and images, not only bullets. Slide count, density and layout are tuned to the audience: execs, boards, technical reviewers, sales prospects, investors, internal teams. Use when the user wants an actual editable .pptx rather than an outline, wants their corporate template or brand colours applied, or says "build the deck", "make it a pptx", "use our template".
+---
+
+# deck-builder
+
+This skill produces an **actual editable `.pptx` file**, not an outline. It runs `python-pptx`
+to materialise slides — either on a brand template's own masters and layouts, or on the skill's
+built-in design in the user's brand: their colours, logo and fonts.
+
+It pairs with three others:
+- **[`brand-kit`](../brand-kit/SKILL.md)** — captures the brand once as a `brand.json` this skill reads, so nobody answers the brand questions for every deck
+- **[`audience-profile`](../../../stakeholder-comms/skills/audience-profile/SKILL.md)** — decides how dense, how many, which sections
+- **[`slide-outliner`](../slide-outliner/SKILL.md)** — drafts per-slide content before this skill builds it
+
+For a single fast pipeline, run all three in order: profile → outline → build.
+
+## How to respond
+
+### 1. Run the setup block — once
+
+Ask everything in **one** message, with defaults already chosen, so the user can answer with a
+single line or say "go". Never trickle out four separate questions, and never generate a deck
+with the design silently defaulted.
+
+> Before I build, confirm these — reply "go" to take the defaults:
+> 1. **Audience** — `exec` · `board` · `technical` · `sales` · `internal` · `investor` · `partner` · `customer`
+> 2. **Format** — live presentation / read-ahead / async share, **how many minutes**, and **16:9** (default) or **4:3**
+> 3. **Brand** — the deck should look like it came from your team. Send any of:
+>    - a **`brand.json`** from brand-kit, which covers everything below in one file;
+>    - a **template**: path to a corporate `.pptx` / `.potx`, and the deck inherits its masters, fonts, colours, logo and slide size;
+>    - your **logo** as a PNG (and a white version for dark slides), **brand colours** as hex values for `primary` / `secondary` / `accent` / `background` / `text`, and your **heading and body fonts**;
+>    - or, with no brand, a named **palette**: `corporate-blue` (default for B2B) · `monochrome` · `vibrant` · `dark-mode` · `editorial` · `forest` · `sunset`
+> 4. **Anything to embed** — numbers to chart, a table, diagram PNGs
+
+Rules for reading the answers:
+
+- **Content is the one hard input.** If the user supplied only a topic, stop and ask for the
+  material. Inventing the content is the easiest way to produce a bad deck.
+- **A free-form audience maps to the closest archetype** — "VP of Eng and their staff at a
+  partner" → `technical`, stated out loud. Mixed audience → the least technical archetype, with
+  the rest served by appendix slides.
+- **Time sets slide count**, not the other way round: 1.5–2 minutes per slide live. 30 minutes →
+  12–15 slides including cover and close.
+- **A partial brand palette gets completed**, using the rules in
+  [`reference.md`](reference.md#color-palette-principles) — say which roles were filled in.
+- **Template beats palette** for chrome; the palette still colours charts, tables, big numbers
+  and quote bars, so ask for brand hexes even when a template is supplied.
+- **Brand material beats a named palette.** If the user sent a logo or brand colours, never fall
+  back to `corporate-blue`. If they have brand material but no `brand.json`, suggest running
+  `brand-kit` first, so the next deck and any flyer match this one.
+- **Logos must be PNG or JPG.** PowerPoint can't place SVG or EPS: ask for a PNG export, and
+  never build with the logo silently missing.
+
+**Non-interactive runs** (subagent, CI, headless): audience, format, time and palette degrade to
+`[assumption]` lines stated at the top of the response — default `exec`, live, 16:9,
+`corporate-blue`, or the `brand.json` when one is in the input. Never invent a logo or brand colour. Missing *content* does not degrade: emit `BLOCKED: need deck content
+(outline, doc, or point list)` and build nothing.
+
+### 2. Plan the slide list against the audience archetype
+
+| Audience | Slide count | Density | Required sections |
+|---|---|---|---|
+| `exec` | 6–10 | Low — 3 bullets max | Ask • TL;DR • Business impact • Risks • Ask (closing) |
+| `board` | 8–12 | Low — big numbers | Cover • TL;DR • Strategic context • Financials • Risks • Ask |
+| `technical` | 12–20 | High — detail welcome | Context • Goals • Proposal (3–5) • Alternatives • Risks • Rollout |
+| `sales` | 8–12 | Story arc, visual | Hook • Pain • Solution • Proof • Pricing • Close |
+| `internal` | 5–10 | Mixed | Context • Proposal • Discussion topics • Action items |
+| `investor` | 10–15 | Polished, narrative | Problem • Market • Product • Traction • Team • Ask |
+
+Full archetype spec: [`audience-profile`](../../../stakeholder-comms/skills/audience-profile/SKILL.md). Slide-count budgets per
+format and time: [`reference.md`](reference.md#slide-count-budgets).
+
+### 3. Build a deck spec
+
+A JSON document — full schema, with every layout and the template block, in
+[`templates/deck-spec.json`](templates/deck-spec.json):
+
+```json
+{
+  "title": "ProjectX Migration — Board Update",
+  "audience": "board",
+  "aspect": "16:9",
+  "template": "./brand/acme-master.potx",
+  "layout_map": { "title": "Title Slide", "content": "Title and Content" },
+  "palette": { "primary": "#1A2A6C", "accent": "#FDBB2D" },
+  "brand": "./brand/brand.json",
+  "slides": [
+    { "layout": "title", "title": "...", "subtitle": "...", "presenter": "...", "date": "..." },
+    { "layout": "content", "title": "...", "bullets": ["..."], "notes": "..." },
+    { "layout": "chart", "title": "...", "takeaway": "...", "chart": { "type": "column", "categories": ["..."], "series": [{ "name": "...", "values": [1, 2] }] }, "source": "..." },
+    { "layout": "table", "title": "...", "columns": ["..."], "rows": [["..."]] },
+    { "layout": "image", "title": "...", "image": "./diagram.png", "position": "right", "bullets": ["..."] },
+    { "layout": "big_number", "title": "...", "number": "$24M", "caption": "ARR at risk" },
+    { "layout": "closing", "title": "Approval requested", "subtitle": "..." }
+  ]
+}
+```
+
+Ten layouts: `title`, `section`, `content`, `two_column`, `big_number`, `quote`, `image`,
+`table`, `chart`, `closing`. Most slides are `content`; `chart`, `table` and `big_number` carry
+the evidence; `quote` and `image` break the rhythm. Which content shape earns which layout:
+[`reference.md`](reference.md#layout--content-matching).
+
+Every slide gets a `notes` field. Slide numbers appear automatically past 10 slides — override
+with `"slide_numbers": false`.
+
+### 4. Build from the user's template when there is one
+
+A corporate template is the difference between a deck that gets presented and one that gets
+rebuilt by hand. When the user names one:
+
+```bash
+# Claude Code — list the template's layouts first
+python3 "${CLAUDE_SKILL_DIR}/scripts/build_deck.py" --list-layouts ~/brand/acme-master.potx
+
+# Other IDEs (from the skill folder)
+python3 scripts/build_deck.py --list-layouts ~/brand/acme-master.potx
+```
+
+Map each logical layout to one of the printed names in `layout_map`, then build. The template's
+masters, theme fonts, colours, logos and slide size are inherited; any sample slides it ships
+with are dropped. A logical layout left out of the map falls back to the skill's built-in
+design on the template's blank layout — acceptable for `big_number` or `quote`, wrong for
+`title` and `content`, which is where the branding shows.
+
+`.potx` and `.pptx` both work. Templates carry no charts or tables of their own, so those are
+drawn into whatever content region the mapped layout defines.
+
+### 5. Run the build script
+
+```bash
+# Claude Code
+python3 "${CLAUDE_SKILL_DIR}/scripts/build_deck.py" /tmp/deck-spec.json -o ./out/deck.pptx
+
+# Other IDEs (from the skill folder)
+cd path/to/deck-builder && python3 scripts/build_deck.py /tmp/deck-spec.json -o ./out/deck.pptx
+```
+
+Add `--brand ./brand/brand.json` to build in the user's brand (or set `"brand"` in the spec).
+The brand fills whatever the spec leaves out: palette colours, the template, logo files and
+fonts. On the built-in design the logo goes on every slide: large on the cover, small in the
+lower-left corner elsewhere, and the on-dark version on dark section and closing slides. The
+brand's heading and body fonts are applied to titles, text, tables and charts. A template
+already carries its own logo and fonts, so they come from the template instead.
+
+Add `--strict` to fail the build on a missing or unreadable image instead of drawing a
+placeholder box — use it in CI, not in a conversation.
+
+**Read the warnings.** The script degrades rather than crashing: a missing image, a short data
+series, an unresolvable template layout each produce a warning and a visible fallback. Report
+every warning to the user with the file path; never present a deck with an unexplained
+placeholder box in it.
+
+### 6. Recommend the refinement pass
+
+A generated deck is a strong first draft. Always tell the user to:
+
+- Review the speaker notes — the agent wrote them, and they get read aloud
+- Replace any placeholder box with the real diagram
+- Do one audience pass: read every slide title in order, does the *narrative* land for that audience?
+- Run [`doc-critique`](../../../core/skills/doc-critique/SKILL.md) against the deck rubric before it goes out
+
+## Useful references
+
+- [`reference.md`](reference.md) — palette principles, layout-vs-content matching, chart and table rules, density and slide-count budgets
+- [`templates/deck-spec.json`](templates/deck-spec.json) — full JSON schema with every layout and the template block
+- [`templates/palettes.json`](templates/palettes.json) — the seven presets
+- [`examples/exec-board-update.md`](examples/exec-board-update.md) — worked example: brief → spec → deck
+- [`examples/templated-brand-deck.md`](examples/templated-brand-deck.md) — worked example: corporate `.potx` → layout map → deck
+- [`scripts/build_deck.py`](scripts/build_deck.py) — the generator (don't edit unless adding a layout)
+
+## Quality bar
+
+- **Design is chosen by the user, never silently defaulted** — a `brand.json`, a template, brand colours and logo, or a named palette, confirmed in the setup block.
+- **The user's brand shows on every slide** — their logo (PNG) and colours, and their fonts when they gave them. A deck built from brand material that comes out in `corporate-blue` has failed.
+- **A supplied template is actually inherited** — `layout_map` covers `title`, `section`, `content` and `closing` at minimum. A branded deck rendered on the blank layout has thrown away the branding.
+- **Title slide isn't blank** — real title, subtitle, presenter, date.
+- **Numbers are charted, not bulleted** — three or more comparable figures belong in a `chart` or a `table`, not a bullet list.
+- **Every chart and table cites its `source`** and uses only figures from the user's material.
+- **Bullet density matches audience** — `exec`, *3 bullets max*, period. `technical`, up to 6 when the content needs it.
+- **Speaker notes on every slide** — even one sentence.
+- **Section dividers used sparingly** — at most one every 4–5 content slides.
+- **Zero unexplained warnings** — every warning the script emits is fixed or reported to the user.
+- **Colour is consistent** — palette roles only, no stray colours; text-on-background contrast ≥ 4.5:1.
+
+## Anti-patterns to avoid
+
+- ❌ Ignoring a template the user already named, or asking for a palette after they supplied one. The template is the answer to "what should this look like".
+- ❌ Asking for brand colours when a `brand.json` was supplied, or building without the logo because it was an SVG. Ask for a PNG export instead.
+- ❌ Mapping every logical layout onto the template's one title-and-bullets layout. That is a branded deck that still looks generated.
+- ❌ Generating without confirming audience. The same content for execs and engineers is a different deck.
+- ❌ Inventing a statistic to fill a `big_number`, or a series to fill a chart. No source, no chart.
+- ❌ A table with 20 rows. Over ~12 it is an appendix or a spreadsheet, not a slide.
+- ❌ Passing an SVG or EMF diagram to `image` — `python-pptx` reads raster only. Convert to PNG first.
+- ❌ Shipping the deck with a grey placeholder box still in it because the warning went unread.
+- ❌ Defaulting to bullets when a `big_number`, `chart`, `quote` or `two_column` would land harder.
+- ❌ More than ~20 slides for any audience. If the point needs 21, the deck is the wrong format.
+- ❌ **Showing the machinery.** The reply and the artifact are for the person who asked. Don't mention this skill, its files, templates, caps or internal terms, or that the run is non-interactive. Name another skill once, at the end, as a suggested next step, never inside the artifact.
+- ❌ **A bare `BLOCKED` line.** Keep the `BLOCKED: need <X>` line, then write for a person: what is missing in plain words, what you will produce once you have it, and anything the request already lets you say.

skilldrop_cli/data/packs/design/skills/deck-builder/evals/eval_queries.json

@@ -0,0 +1,14 @@
+[
+  { "query": "Build me a PowerPoint from this content", "should_trigger": true },
+  { "query": "Generate a .pptx deck for this exec presentation", "should_trigger": true },
+  { "query": "Turn this into actual slides I can present, with our brand colors", "should_trigger": true },
+  { "query": "I need a real deck file, not an outline", "should_trigger": true },
+  { "query": "Build the deck on our corporate template — marketing rejects anything else", "should_trigger": true },
+  { "query": "Use our .potx master for this QBR deck", "should_trigger": true },
+  { "query": "Put these quarterly numbers on a slide as a chart", "should_trigger": true },
+  { "query": "Just outline the slides — I'll build the deck myself", "should_trigger": false },
+  { "query": "Write a one-page summary for executives", "should_trigger": false },
+  { "query": "Which audience archetype should I target and what are its rules?", "should_trigger": false },
+  { "query": "Critique the deck I already made", "should_trigger": false },
+  { "query": "Extract the text out of this existing .pptx so I can email it", "should_trigger": false }
+]