skilldrop-cli 0.13.5 → 0.13.7

package/packs/{stakeholder-comms → design}/skills/deck-builder/SKILL.md

@@ -7,10 +7,11 @@ description: Generate a real PowerPoint (.pptx) file from content, audience, and
 
 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 driven by a colour palette.
+built-in design in the user's brand: their colours, logo and fonts.
 
-It pairs with two others:
-- **[`audience-profile`](../audience-profile/SKILL.md)** — decides how dense, how many, which sections
+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.
@@ -26,9 +27,11 @@ 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. **Design** — either
->    - a **template**: path to a corporate `.pptx` / `.potx`, and the deck inherits its masters, fonts, colours and slide size; or
->    - a **palette**: `corporate-blue` (default for B2B) · `monochrome` · `vibrant` · `dark-mode` · `editorial` · `forest` · `sunset`, or brand hex values for `primary` / `secondary` / `accent` / `background` / `text`
+> 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:
@@ -44,10 +47,15 @@ Rules for reading the answers:
   [`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`. Missing *content* does not degrade: emit `BLOCKED: need deck content
+`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
@@ -61,7 +69,7 @@ Rules for reading the answers:
 | `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`](../audience-profile/SKILL.md). Slide-count budgets per
+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
@@ -77,6 +85,7 @@ A JSON document — full schema, with every layout and the template block, in
   "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": "..." },
@@ -129,6 +138,13 @@ python3 "${CLAUDE_SKILL_DIR}/scripts/build_deck.py" /tmp/deck-spec.json -o ./out
 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.
 
@@ -157,7 +173,8 @@ A generated deck is a strong first draft. Always tell the user to:
 
 ## Quality bar
 
-- **Design is chosen by the user, never silently defaulted** — a template path or a named palette, confirmed in the setup block.
+- **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.
@@ -171,6 +188,7 @@ A generated deck is a strong first draft. Always tell the user to:
 ## 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.

package/packs/{stakeholder-comms → design}/skills/deck-builder/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "deck-builder",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "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\".",
   "entrypoint": "SKILL.md",
   "deps": {
@@ -8,7 +8,7 @@
     "pip": ["python-pptx==1.0.2"]
   },
   "env": { "required": [], "optional": [] },
-  "related": ["audience-profile", "slide-outliner", "doc-critique"],
+  "related": ["brand-kit", "audience-profile", "slide-outliner", "doc-critique"],
   "install": {
     "pip": "python3 -m pip install -r requirements.txt"
   },

package/packs/{stakeholder-comms → design}/skills/deck-builder/scripts/build_deck.py

@@ -9,6 +9,9 @@ The spec schema is documented in templates/deck-spec.json. Top-level fields:
              colors and slide size are inherited
 - layout_map: logical layout -> template layout name or index (template mode)
 - palette:   a hex-color block, or a name resolvable from templates/palettes.json
+- brand:     path to a brand.json (the brand-kit skill writes one) or the same object
+             inline. It supplies anything the spec leaves out: palette colours, template,
+             logo files and fonts. --brand on the command line overrides it.
 - slide_numbers: true/false (default: true when the deck has more than 10 slides)
 - slides:    list of slide specs, each with a `layout` field
 
@@ -16,7 +19,7 @@ Supported layouts: title, section, content, two_column, big_number, quote,
 image, table, chart, closing.
 
 Usage:
-    python3 build_deck.py <spec.json> [-o output.pptx] [--strict]
+    python3 build_deck.py <spec.json> [-o output.pptx] [--strict] [--brand brand.json]
 """
 
 from __future__ import annotations
@@ -73,6 +76,12 @@ RASTER_OK = {".png", ".jpg", ".jpeg", ".gif", ".bmp", ".tif", ".tiff"}
 WARNINGS: list[str] = []
 
 
+# Set from brand.json in build(): fonts for the built-in design, and the logo files placed on
+# its slides. A supplied template already carries its own fonts and logo, so these are only
+# used when a slide renders on the built-in design.
+BRAND = {"heading_font": None, "body_font": None, "logo": None, "logo_on_dark": None}
+
+
 def warn(msg: str) -> None:
     WARNINGS.append(msg)
     sys.stderr.write(f"warning: {msg}\n")
@@ -405,6 +414,9 @@ def add_textbox(slide, text: str, *, left, top, width, height,
     run.font.size = size
     run.font.bold = bold
     run.font.color.rgb = hex_color(color)
+    font = BRAND["heading_font"] if (bold or size >= Pt(24)) else BRAND["body_font"]
+    if font:
+        run.font.name = font
 
 
 def add_bullets(slide, bullets, *, left, top, width, height,
@@ -419,6 +431,8 @@ def add_bullets(slide, bullets, *, left, top, width, height,
         for run in p.runs:
             run.font.size = size
             run.font.color.rgb = hex_color(color)
+            if BRAND["body_font"]:
+                run.font.name = BRAND["body_font"]
 
 
 def add_rect(slide, *, left, top, width, height, fill: str) -> None:
@@ -503,6 +517,8 @@ def place_table(slide, columns, rows, region: Region, c: Canvas, palette: dict)
                 run.font.bold = True
                 run.font.size = c.pt(body_pt + 1)
                 run.font.color.rgb = hex_color("#FFFFFF")
+                if BRAND["heading_font"]:
+                    run.font.name = BRAND["heading_font"]
 
     for i, row in enumerate(rows, start=1):
         for j in range(n_cols):
@@ -514,6 +530,8 @@ def place_table(slide, columns, rows, region: Region, c: Canvas, palette: dict)
             for p in cell.text_frame.paragraphs:
                 for run in p.runs:
                     run.font.size = c.pt(body_pt)
+                    if BRAND["body_font"]:
+                        run.font.name = BRAND["body_font"]
                     run.font.color.rgb = hex_color(palette["text"])
 
 
@@ -543,6 +561,8 @@ def place_chart(slide, chart_spec: dict, region: Region, c: Canvas, palette: dic
                                  region.width, region.height, data)
     chart = gfx.chart
     chart.font.size = c.pt(13)
+    if BRAND["body_font"]:
+        chart.font.name = BRAND["body_font"]
     chart.font.color.rgb = hex_color(palette["text"])
 
     is_pie = kind in ("pie", "doughnut")
@@ -934,9 +954,81 @@ def layout_numbers_slides(layout) -> bool:
 # ----------------------------------------------------------------- driver
 
 
-def build(spec_path: Path, out_path: Path, script_dir: Path, *, strict: bool) -> None:
+def load_brand(ref, base: Path):
+    """brand.json path or inline object -> (dict, directory its relative paths resolve from)."""
+    if not ref:
+        return {}, base
+    if isinstance(ref, dict):
+        return ref, base
+    path = (base / ref).expanduser() if not Path(ref).is_absolute() else Path(ref)
+    if not path.exists():
+        warn(f"brand file not found: {path}; building without it")
+        return {}, base
+    try:
+        return json.loads(path.read_text()), path.parent
+    except json.JSONDecodeError as e:
+        warn(f"brand file {path} is not valid JSON ({e}); building without it")
+        return {}, base
+
+
+def apply_brand(spec: dict, brand: dict, brand_dir: Path, spec_dir: Path) -> None:
+    """Fill what the spec leaves out from the brand. The spec always wins: a deck can still
+    override one colour or swap the template without editing the brand file."""
+    colors = {k: v for k, v in (brand.get("colors") or {}).items()
+              if k in ("primary", "secondary", "accent", "background", "text") and v}
+    if colors and not spec.get("palette"):
+        spec["palette"] = colors
+    elif colors and isinstance(spec.get("palette"), dict):
+        spec["palette"] = {**colors, **spec["palette"]}
+    tpl = (brand.get("templates") or {}).get("pptx") or brand.get("template")
+    if tpl and not spec.get("template"):
+        spec["template"] = str((brand_dir / tpl).resolve()) if not Path(tpl).is_absolute() else tpl
+    fonts = brand.get("fonts") or {}
+    BRAND["heading_font"] = (fonts.get("heading") or {}).get("family") if isinstance(fonts.get("heading"), dict) else fonts.get("heading")
+    BRAND["body_font"] = (fonts.get("body") or {}).get("family") if isinstance(fonts.get("body"), dict) else fonts.get("body")
+    logo = brand.get("logo") or {}
+    for key, field in (("logo", "primary"), ("logo_on_dark", "on_dark")):
+        ref = logo.get(field) if isinstance(logo, dict) else (logo if field == "primary" else None)
+        if not ref:
+            continue
+        lp = (brand_dir / ref) if not Path(ref).is_absolute() else Path(ref)
+        if lp.suffix.lower() not in (".png", ".jpg", ".jpeg", ".gif", ".bmp"):
+            warn(f"logo {lp.name} is {lp.suffix or 'not an image'}; PowerPoint needs PNG or JPG. Export the logo as PNG.")
+        elif not lp.exists():
+            warn(f"logo not found: {lp}")
+        else:
+            BRAND[key] = str(lp)
+
+
+def is_dark(hex_str: str) -> bool:
+    h = hex_str.lstrip("#")
+    r, g, b = (int(h[i:i + 2], 16) / 255 for i in (0, 2, 4))
+    return 0.2126 * r + 0.7152 * g + 0.0722 * b < 0.45
+
+
+def place_logo(slide, c: "Canvas", palette: dict, logical: str) -> None:
+    """The brand logo on the built-in design: large on the cover, small in a fixed corner on
+    every other slide, using the on-dark variant on dark slides when there is one."""
+    if not BRAND["logo"] and not BRAND["logo_on_dark"]:
+        return
+    dark_bg = logical in ("section", "closing") and is_dark(palette["primary"]) or \
+        (logical == "title" and is_dark(palette["background"]))
+    path = (BRAND["logo_on_dark"] or BRAND["logo"]) if dark_bg else (BRAND["logo"] or BRAND["logo_on_dark"])
+    if logical == "title":
+        slide.shapes.add_picture(path, c.x(0.75), c.y(0.6), height=c.y(0.7))
+    elif logical == "closing":
+        pic = slide.shapes.add_picture(path, 0, c.h - c.y(1.25), height=c.y(0.6))
+        pic.left = int((c.w - pic.width) / 2)
+    else:
+        slide.shapes.add_picture(path, c.x(0.5), c.h - c.y(0.55), height=c.y(0.32))
+
+
+def build(spec_path: Path, out_path: Path, script_dir: Path, *, strict: bool, brand_ref=None) -> None:
     spec = json.loads(spec_path.read_text())
     spec_dir = spec_path.parent
+    brand, brand_dir = load_brand(brand_ref or spec.get("brand"), spec_dir)
+    if brand:
+        apply_brand(spec, brand, brand_dir, spec_dir)
     palette = resolve_palette(spec.get("palette"), script_dir)
 
     slides = spec.get("slides", [])
@@ -970,6 +1062,8 @@ def build(spec_path: Path, out_path: Path, script_dir: Path, *, strict: bool) ->
                 render_templated(slide, canvas, palette, slide_spec, ctx, logical)
             else:
                 RENDERERS[logical](slide, canvas, palette, slide_spec, ctx)
+                if not using_template:  # a template's masters already carry its logo
+                    place_logo(slide, canvas, palette, logical)
 
             if slide_spec.get("notes"):
                 set_notes(slide, slide_spec["notes"])
@@ -982,6 +1076,10 @@ def build(spec_path: Path, out_path: Path, script_dir: Path, *, strict: bool) ->
         prs.save(str(out_path))
 
     mode = "template" if using_template else "built-in design"
+    if brand:
+        mode += ", brand: " + ", ".join(x for x, on in (("colours", bool(brand.get("colors"))),
+                                                         ("logo", bool(BRAND["logo"] or BRAND["logo_on_dark"])),
+                                                         ("fonts", bool(BRAND["heading_font"] or BRAND["body_font"]))) if on)
     print(f"wrote {out_path} ({len(slides)} slides, {mode})")
     if WARNINGS:
         print(f"{len(WARNINGS)} warning(s) — see stderr; fix them before presenting")
@@ -995,6 +1093,9 @@ def main(argv) -> int:
                     help="Output .pptx path (default: alongside the spec)")
     ap.add_argument("--strict", action="store_true",
                     help="Fail on a missing/unsupported image instead of drawing a placeholder")
+    ap.add_argument("--brand", metavar="BRAND_JSON",
+                    help="brand.json (from the brand-kit skill): colours, template, logo, fonts. "
+                         "Fills anything the spec leaves out")
     ap.add_argument("--list-layouts", metavar="TEMPLATE",
                     help="Print a template's layout names and indices, then exit "
                          "(use them to write layout_map)")
@@ -1024,7 +1125,8 @@ def main(argv) -> int:
     out_path = (Path(args.output).expanduser().resolve()
                 if args.output else spec_path.with_suffix(".pptx"))
 
-    build(spec_path, out_path, Path(__file__).resolve().parent, strict=args.strict)
+    build(spec_path, out_path, Path(__file__).resolve().parent, strict=args.strict,
+          brand_ref=str(Path(args.brand).expanduser().resolve()) if args.brand else None)
     return 0
 
 

package/packs/{stakeholder-comms → design}/skills/deck-builder/templates/deck-spec.json

@@ -1,5 +1,5 @@
 {
-  "_comment": "Full deck-spec schema. The build_deck.py script consumes this. Top-level fields: title, audience, aspect, template, layout_map, palette, slide_numbers, slides[].",
+  "_comment": "Full deck-spec schema. The build_deck.py script consumes this. Top-level fields: title, audience, aspect, template, layout_map, palette, brand, slide_numbers, slides[].",
 
   "title": "ProjectX Migration — Board Update",
   "audience": "board",
@@ -22,6 +22,9 @@
     "closing": "Closing"
   },
 
+  "_brand_comment": "Path to a brand.json from the brand-kit skill, or the same object inline. It fills anything this spec leaves out: palette colours, template, logo files (logo.primary, logo.on_dark — PNG or JPG) and fonts (fonts.heading.family, fonts.body.family). --brand on the command line overrides it.",
+  "brand": "./brand/brand.json",
+
   "palette": {
     "primary": "#1A2A6C",
     "secondary": "#4A5A8C",

package/packs/design/skills/marketing-flyer/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: marketing-flyer
+description: Generate a print-ready, on-brand marketing flyer — event, launch, open day, offer, hiring — as one self-contained HTML file (Letter, A4, A5, or square and story sizes for social) that saves to PDF, built from the user's own logo, colours, fonts and content, with one call to action, a short headline, contrast checked, and no invented dates, prices or contact details. Use when the user wants a flyer, poster, one-pager, handout, leaflet or event announcement "in our branding", or says "make a flyer for…".
+---
+
+# marketing-flyer
+
+You make a flyer that looks like it came from the user's own team, because it's built from
+their brand: their logo, their colours, their fonts, their words. The output is one HTML file
+with the images embedded, sized for print, that saves to PDF from any browser. When a
+`brand.json` from [`brand-kit`](../brand-kit/SKILL.md) exists, use it, and the flyer will match
+the user's decks from [`deck-builder`](../deck-builder/SKILL.md).
+
+## How to respond
+
+1. **Ask for everything in one message.** Take what's already been given, and suggest
+   defaults so the user can reply "go".
+
+   > Before I build the flyer, send these. Anything you skip, I'll use the default shown:
+   > 1. **Brand:** a `brand.json` from brand-kit, *or* your logo file (and a white version for
+   >    dark backgrounds), brand colours as hex codes, and heading and body fonts.
+   >    *Default: no brand, which looks generic, so please send at least a logo and one colour.*
+   > 2. **What it's for, and who reads it:** an event, a launch, an offer, hiring, a service
+   > 3. **The words:** a headline (ten words or fewer), a one-line subhead, up to four key
+   >    points, and details such as date, time, place and price
+   > 4. **One call to action:** what the reader should do, and the web address, phone or email for it.
+   >    A QR code image too, if you have one.
+   > 5. **Images:** a photo for the top of the flyer, if any, with a line describing it
+   > 6. **Size:** `letter` · `a4` · `a5` · `square` (Instagram/LinkedIn) · `story` · and
+   >    portrait or landscape. *Default: letter, portrait.*
+   > 7. **Layout:** `hero` (photo across the top) · `split` (photo down one side) ·
+   >    `event` (a big date block) · `minimal`. *Default: event when there's a date, otherwise hero.*
+
+   **Content is the hard input.** Never invent a date, time, price, address, phone number,
+   web address or statistic. If the user gave only a topic, ask for the details. A flyer with
+   a wrong date is worse than no flyer.
+
+2. **Write the copy to fit a flyer.** Rewrite long text into the flyer's shape and show the
+   user what you changed:
+   - A headline of ten words or fewer that names the thing, such as "Free community health
+     fair", not "You're invited!".
+   - A subhead that says who it's for, or why it's worth coming.
+   - At most four points, each one line, so they can be read in passing.
+   - Exactly **one** call to action, worded as a verb ("Save your spot", "Call to book"). Two
+     calls to action means the reader does neither.
+
+   Use the brand's voice from `brand.json` when it has one: words to use, words to avoid.
+
+3. **Write the spec** in the shape of [`templates/flyer-spec.json`](templates/flyer-spec.json),
+   with paths relative to the spec file.
+
+4. **Build it.**
+
+   ```bash
+   # Claude Code
+   python3 "${CLAUDE_SKILL_DIR}/scripts/build_flyer.py" flyer-spec.json -o flyer.html --brand ./brand/brand.json --pdf flyer.pdf
+   # Other IDEs (from the skill folder)
+   python3 scripts/build_flyer.py flyer-spec.json -o flyer.html --brand ./brand/brand.json --pdf flyer.pdf
+   ```
+
+   `--pdf` and `--png` use a local Chrome or Chromium when one is installed. Without one, the
+   user opens `flyer.html` and prints it to PDF at 100% scale with margins set to none.
+   Use `--png` for the `square` and `story` sizes, which are posted as images.
+
+5. **Read the output and every warning.** The script prints three contrast figures: text,
+   the header band, and the call to action. It picks white or the brand's text colour on each
+   filled band, whichever reads better. It warns about a long headline, more than four
+   points, more than one call to action, a missing logo or image, and no brand. Fix what you
+   can, and report the rest to the user with what it means.
+
+6. **Tell the user how to check it before printing:** read every date, time and address
+   aloud against the source, check the web address works, and print one test copy.
+
+**Non-interactive runs** (subagent, CI, headless): missing *content* does not get a default.
+Emit `BLOCKED: need the flyer's details: <what is missing>` and build nothing. Missing brand
+falls back to defaults with an `[assumption]` line at the top; never make up a logo.
+
+## Useful references in this skill
+
+- [`reference.md`](reference.md) — sizes and print rules, layouts and when to use each, copy budgets, contrast
+- [`templates/flyer-spec.json`](templates/flyer-spec.json) — the spec, every field shown
+- [`scripts/build_flyer.py`](scripts/build_flyer.py) — the builder (stdlib only): HTML, plus PDF and PNG through headless Chrome
+- [`examples/community-health-fair.md`](examples/community-health-fair.md) — worked example: an email from the user becomes a flyer spec and a branded flyer
+
+## Quality bar
+
+- **It is in the user's brand:** their logo, their colours as hex codes, their fonts. Default colours only when the user has no brand material, and then said out loud.
+- **Every fact comes from the user.** Dates, times, places, prices and contact details are copied, not composed.
+- **One call to action,** worded as a verb, with the address or number that makes it actionable.
+- **A headline of ten words or fewer, at most four points.** Anything longer belongs on the linked page.
+- **Text is readable everywhere:** body text at least 4.5:1 against the background, and the script's band and call-to-action figures reported.
+- **The file is the whole flyer.** Images are embedded, with no links to local files that break when it's emailed.
+
+## When to use this skill
+
+- ✅ An event, a launch, an open day, an offer, a hiring drive, a service announcement
+- ✅ A one-page handout or leaflet in the company's branding
+- ✅ A square or story-sized image for social posts that matches the printed flyer
+
+## When NOT to use this skill
+
+- ❌ A slide deck; use `deck-builder`
+- ❌ A multi-page brochure or a report, which this doesn't lay out
+- ❌ Designing a brand from scratch; capture an existing one with `brand-kit`
+
+## Anti-patterns to avoid
+
+- ❌ **"You're invited!" as the headline.** Name the event, the offer or the product.
+- ❌ **Three buttons** ("Register", "Learn more", "Follow us"). Pick the one action that matters.
+- ❌ **Filling a missing date with "TBC"** or a plausible guess. Ask, or build nothing.
+- ❌ **White text on a pale accent** because the brand's buttons are white. The script flips it; don't override it.
+- ❌ **A paragraph of body copy.** No one reads a paragraph on a noticeboard.
+- ❌ **Sending the HTML with images linked from the user's disk.** Always build with the script, which embeds them.

package/packs/design/skills/marketing-flyer/evals/eval_queries.json

@@ -0,0 +1,30 @@
+[
+  {
+    "query": "Make a flyer for our open day in our brand colours",
+    "should_trigger": true
+  },
+  {
+    "query": "Design a one-page handout announcing the new clinic",
+    "should_trigger": true
+  },
+  {
+    "query": "I need a poster for the charity run, with our logo",
+    "should_trigger": true
+  },
+  {
+    "query": "Create an Instagram-sized announcement image that matches our flyer",
+    "should_trigger": true
+  },
+  {
+    "query": "Build the board deck as a pptx",
+    "should_trigger": false
+  },
+  {
+    "query": "Write the press release for the launch",
+    "should_trigger": false
+  },
+  {
+    "query": "Set up our brand colours and fonts so we can reuse them",
+    "should_trigger": false
+  }
+]

package/packs/design/skills/marketing-flyer/evals/evals.json

@@ -0,0 +1,18 @@
+{
+  "skill_name": "marketing-flyer",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Make a flyer for our community health fair using ./brand/brand.json. It's Saturday 14 November, 10am to 2pm, at the Riverside Park pavilion, free. There'll be blood pressure and glucose checks, flu shots with no appointment, a kids' corner and cooking demos. People should register at northwindhealth.example/fair. Letter size.",
+      "assertions": [
+        "Uses the supplied brand.json, so the flyer carries the brand logo and colours",
+        "The headline is ten words or fewer and names the event",
+        "There is exactly one call to action, worded as a verb, with northwindhealth.example/fair",
+        "The date, time, place and price match the prompt exactly; nothing is invented (no phone number, no extra dates)",
+        "No more than four points",
+        "Runs build_flyer.py and reports the contrast figures and any warnings",
+        "Picks the event layout, or explains choosing another, because the date is the key fact"
+      ]
+    }
+  ]
+}

package/packs/design/skills/marketing-flyer/examples/community-health-fair.md

@@ -0,0 +1,68 @@
+# Worked example — an email about a health fair becomes a branded flyer
+
+## Input given to the skill
+
+> Can you make a flyer for our community health fair? Use our brand kit in ./brand/. It's
+> Saturday 14 November, 10am to 2pm, at the Riverside Park pavilion, and it's free. We'll have
+> free blood pressure and glucose checks, flu shots (no appointment), a kids' corner and some
+> healthy cooking demos. Oh and a raffle. People should register at
+> northwindhealth.example/fair so we know numbers. Letter size please, we'll print it at the office.
+
+---
+
+**Copy, fitted to a flyer.** Here is what I changed from your email:
+
+- **Headline:** "Free community health fair" (5 words)
+- **Subhead:** "Checkups, flu shots and healthy cooking — for the whole family"
+- **Points (3):** free blood pressure and glucose checks · flu shots, no appointment needed ·
+  kids' corner and healthy cooking demos. *The raffle is left off: four points is the most a
+  flyer carries, and the other three bring people in. Say if you want it instead of the
+  cooking demos.*
+- **Call to action:** "Save your spot" → northwindhealth.example/fair
+- **Layout:** `event`, because the date is the fact people need first
+
+**Spec** (`flyer-spec.json`):
+
+```json
+{
+  "brand": "./brand/brand.json",
+  "size": "letter",
+  "layout": "event",
+  "headline": "Free community health fair",
+  "subhead": "Checkups, flu shots and healthy cooking — for the whole family",
+  "points": ["Free blood pressure and glucose checks", "Flu shots, no appointment needed", "Kids' corner and healthy cooking demos"],
+  "details": [
+    { "label": "When", "value": "Sat 14 Nov, 10am–2pm" },
+    { "label": "Where", "value": "Riverside Park pavilion" },
+    { "label": "Cost", "value": "Free" }
+  ],
+  "cta": { "text": "Save your spot", "url": "northwindhealth.example/fair" },
+  "image": { "path": "./riverside-park.png", "alt": "Families at Riverside Park" },
+  "footer": "© 2026 Northwind Health"
+}
+```
+
+**Build:**
+
+```
+$ python3 scripts/build_flyer.py flyer-spec.json -o community-health-fair.html --brand ./brand/brand.json --pdf community-health-fair.pdf
+wrote ./community-health-fair.html (event, letter; brand: yes; logo: yes)
+  contrast: text 14.8:1 · band 8.2:1 · call to action 7.2:1
+wrote ./community-health-fair.pdf
+```
+
+**The flyer:** Northwind's green band across the top with the white logo. A large amber date
+block reading *Sat 14 Nov, 10am–2pm* sits beside the Georgia headline. Below are the park
+photo, the three points with amber markers, Where and Cost, and an amber "Save your spot" panel
+with the web address in dark text, because white on that amber would be hard to read. The
+footer carries the website and the copyright line.
+
+**Before you print:** read the date, time and place aloud against your email, open
+northwindhealth.example/fair to check it works, and print one test copy.
+
+---
+
+**Why this is a good output:** every fact is copied from the email, and the one cut (the raffle)
+is named and offered back instead of silently dropped. There's one call to action. The layout
+puts the date first because that's what a passer-by needs. The contrast figures are reported,
+and the panel text uses the colour that reads.

package/packs/design/skills/marketing-flyer/manifest.json

@@ -0,0 +1,39 @@
+{
+  "name": "marketing-flyer",
+  "version": "0.1.0",
+  "description": "Generate a print-ready, on-brand marketing flyer — event, launch, open day, offer, hiring — as one self-contained HTML file (Letter, A4, A5, or square and story sizes for social) that saves to PDF, built from the user's own logo, colours, fonts and content, with one call to action, a short headline, contrast checked, and no invented dates, prices or contact details. Use when the user wants a flyer, poster, one-pager, handout, leaflet or event announcement \"in our branding\", or says \"make a flyer for…\".",
+  "entrypoint": "SKILL.md",
+  "deps": {
+    "npm": [],
+    "pip": []
+  },
+  "env": {
+    "required": [],
+    "optional": []
+  },
+  "related": [
+    "brand-kit",
+    "deck-builder"
+  ],
+  "handoff": [
+    {
+      "to": "brand-kit",
+      "when": "the user has brand material but no brand.json",
+      "purpose": "Capture the logo, colours and fonts once, so the flyer and later decks match.",
+      "fallback": "If brand-kit is absent, ask for the logo path and brand hex codes in the setup block and put them in the spec's brand object inline."
+    }
+  ],
+  "tags": [
+    "flyer",
+    "poster",
+    "marketing",
+    "print",
+    "pdf",
+    "brand",
+    "design"
+  ],
+  "model": {
+    "tier": "standard",
+    "rationale": "Writes short copy to fit and fills a spec for a deterministic builder. Bounded generation."
+  }
+}