skilldrop-cli 0.11.9 → 0.12.1

package/skills/deck-builder/evals/eval_queries.json

@@ -1,34 +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": "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": "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 }
 ]

package/skills/deck-builder/evals/evals.json

@@ -6,12 +6,35 @@
       "prompt": "Build a .pptx from this content for an exec audience, using our brand palette (navy/white).",
       "assertions": [
         "A real .pptx file is produced, not an outline",
+        "Audience, format and design are confirmed in a single setup block rather than as a trickle of separate questions",
         "The title slide carries a real title, subtitle, presenter, and date — never left blank",
         "Section dividers appear sparingly, at most one every 4-5 content slides",
         "Big-number layouts use only numbers the user supplied; no statistic is invented for emphasis",
         "Bullet density matches the stated audience rather than a fixed default",
         "The requested palette is applied rather than the default theme"
       ]
+    },
+    {
+      "id": 2,
+      "prompt": "Build the Q3 QBR deck on our corporate template at ~/brand/acme-master.potx — 25 minutes, live, partner audience.",
+      "assertions": [
+        "The template's layouts are listed with --list-layouts before the spec is written, rather than layout names being guessed",
+        "The spec sets `template` and a `layout_map` covering at least title, section, content and closing",
+        "A palette is still collected, because the template does not colour charts, tables or big numbers",
+        "`aspect` is not fought with — the template's own slide size is accepted and stated",
+        "Slide count is derived from the 25-minute budget at roughly 2 minutes per slide"
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "Here are our renewal rates for the last three quarters (88%, 91%, 94%) and the SLA table from the contract. Put them in the deck.",
+      "assertions": [
+        "The three comparable figures become a `chart` slide, not a bullet list",
+        "The chart carries a `takeaway` sentence and a `source`",
+        "The SLA data becomes a `table` slide rather than aligned bullets",
+        "No figure appears that the user did not supply",
+        "Any build warning (missing image, short series) is reported to the user with its path rather than left in the file"
+      ]
     }
   ]
 }

package/skills/deck-builder/examples/templated-brand-deck.md

@@ -0,0 +1,148 @@
+# Example: Q3 partner QBR on the company's own PowerPoint template
+
+**Prompt the user gave:** *"Make the Q3 QBR deck for Northwind. Use our corporate template at
+`~/brand/acme-master.potx` — it's mandatory, marketing rejects anything else. 25 minutes, live,
+with the partner's CTO and two of their architects in the room. Renewal rate went 88 → 91 → 94%
+over the last three quarters, ticket volume is down 31%, and we want to land the co-sell
+expansion ask. Brand colours are #0B3D6B and #E8A33D."*
+
+## Step 1 — Setup block, answered in one pass
+
+| Input | Value | How it was resolved |
+|---|---|---|
+| Content | Renewal trend, ticket volume, expansion ask | Supplied |
+| Audience | `partner` | Stated ("partner's CTO and architects") |
+| Format | Live, 25 min → 12–14 slides | Stated; slide count derived at ~2 min/slide |
+| Aspect | From the template | `aspect` ignored — the `.potx` is 16:9 |
+| Design | `~/brand/acme-master.potx` + brand hexes | Template for chrome, palette for charts |
+| Embeds | Renewal trend (chart), SLA table | Three comparable figures ⇒ chart, not bullets |
+
+The palette is still collected: the template does not colour charts, tables or big numbers.
+`primary: #0B3D6B`, `accent: #E8A33D`; `secondary`, `background` and `text` derived per
+[`reference.md`](../reference.md#color-palette-principles) and called out to the user.
+
+## Step 2 — Read the template's layouts before writing the spec
+
+```bash
+python3 "${CLAUDE_SKILL_DIR}/scripts/build_deck.py" --list-layouts ~/brand/acme-master.potx
+```
+
+```
+acme-master.potx — slide size 13.33in x 7.50in
+  [0] Acme Cover
+  [1] Acme Section Break
+  [2] Acme Title and Body
+  [3] Acme Two Column
+  [4] Acme Statement
+  [5] Acme Full Bleed Image
+  [6] Blank
+```
+
+The names are the template's, not PowerPoint's defaults — which is exactly why the map is read
+from the file rather than guessed.
+
+## Step 3 — The deck spec
+
+```json
+{
+  "title": "Northwind QBR — Q3 FY26",
+  "audience": "partner",
+  "template": "~/brand/acme-master.potx",
+  "layout_map": {
+    "title": "Acme Cover",
+    "section": "Acme Section Break",
+    "content": "Acme Title and Body",
+    "two_column": "Acme Two Column",
+    "big_number": "Acme Statement",
+    "quote": "Acme Statement",
+    "chart": "Acme Statement",
+    "table": "Acme Statement",
+    "image": "Acme Full Bleed Image",
+    "closing": "Acme Statement"
+  },
+  "palette": {
+    "primary": "#0B3D6B",
+    "secondary": "#4A6E94",
+    "accent": "#E8A33D",
+    "background": "#FFFFFF",
+    "text": "#222222"
+  },
+  "slides": [
+    {
+      "layout": "title",
+      "title": "Northwind × Acme — Q3 business review",
+      "subtitle": "Renewals, service quality, and the FY27 co-sell ask",
+      "presenter": "Jane Roe, Partner Director",
+      "date": "2026-09-30",
+      "notes": "Thank them for the quarter before the first slide. Name the ask now so it isn't a surprise at slide 12."
+    },
+    {
+      "layout": "chart",
+      "title": "Renewal rate has climbed every quarter this year",
+      "takeaway": "Three consecutive quarters of improvement — the joint success plan is what changed.",
+      "chart": {
+        "type": "line",
+        "categories": ["Q1 FY26", "Q2 FY26", "Q3 FY26"],
+        "series": [{ "name": "Renewal rate (%)", "values": [88, 91, 94] }],
+        "number_format": "0\"%\""
+      },
+      "source": "Northwind CS dashboard, 30 Sep 2026",
+      "notes": "Let them claim the win — ask their CTO what drove Q2. The answer is usually the thing to double down on in FY27."
+    },
+    {
+      "layout": "big_number",
+      "title": "Support load is down as adoption is up",
+      "number": "-31%",
+      "caption": "Ticket volume vs. Q3 FY25, on 2.4× the seat count",
+      "notes": "The pairing is the point: more users, fewer tickets. Pause after saying it."
+    },
+    {
+      "layout": "table",
+      "title": "SLA performance against contract",
+      "columns": ["Metric", "Contracted", "Q3 actual", "Status"],
+      "rows": [
+        ["Availability", "99.9%", "99.97%", "Met"],
+        ["P1 response", "15 min", "9 min", "Met"],
+        ["P1 resolution", "4 hrs", "3h 10m", "Met"],
+        ["Change failure", "< 5%", "6.2%", "Missed"]
+      ],
+      "caption": "Change-failure remediation plan on the next slide.",
+      "notes": "Do not skip the missed row. Naming it before they do is what makes the other three credible."
+    },
+    {
+      "layout": "closing",
+      "title": "Ask: co-sell motion for FY27, two named accounts each",
+      "subtitle": "Kick-off 15 Oct, joint pipeline review monthly",
+      "notes": "Land on the ask. Get the kick-off date agreed in the room, not in follow-up email."
+    }
+  ]
+}
+```
+
+*(Abridged — the full deck is 13 slides; the four above are the ones that show the new layouts.)*
+
+## Step 4 — Build
+
+```bash
+python3 "${CLAUDE_SKILL_DIR}/scripts/build_deck.py" /tmp/northwind-qbr.json -o ./out/northwind-qbr.pptx
+```
+
+```
+template: dropped 2 sample slide(s), kept masters and layouts
+wrote ./out/northwind-qbr.pptx (13 slides, template)
+```
+
+No warnings, so nothing to report. Had the SLA table's diagram been an `.svg`, the build would
+have drawn a placeholder box and warned — which gets reported to the user with the path, not
+quietly shipped.
+
+## What the template bought
+
+| Without the template | With it |
+|---|---|
+| Calibri, generated-looking cover | Acme's typeface, cover, and logo on every slide |
+| Palette-coloured title bars | The master's own chrome |
+| Marketing sends it back | Passes brand review unchanged |
+
+The palette still did real work: the line chart, the `-31%`, and the table header are brand
+colours because `palette` was collected *alongside* the template, not instead of it.

package/skills/deck-builder/manifest.json

@@ -1,17 +1,17 @@
 {
   "name": "deck-builder",
-  "version": "0.1.0",
-  "description": "Generate a real PowerPoint (.pptx) file from content, target audience, and a color palette. Produces structurally-appropriate decks (slide count, density, layout choice) tuned for the audience — execs, technical reviewers, sales prospects, investors, internal teams. Use when the user wants an actual editable .pptx, not just an outline.",
+  "version": "0.2.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": {
     "npm": [],
     "pip": ["python-pptx==1.0.2"]
   },
   "env": { "required": [], "optional": [] },
-  "related": ["audience-profile", "slide-outliner"],
+  "related": ["audience-profile", "slide-outliner", "doc-critique"],
   "install": {
     "pip": "python3 -m pip install -r requirements.txt"
   },
-  "tags": ["powerpoint", "pptx", "deck", "presentation", "stakeholder-communication"],
-  "model": { "tier": "standard", "rationale": "Generates pptx content + runs a script. Content shaping, not hard reasoning." }
+  "tags": ["powerpoint", "pptx", "deck", "presentation", "template", "charts", "stakeholder-communication"],
+  "model": { "tier": "standard", "rationale": "Shapes content, maps a brand template's layouts, and runs a script. Judgment, not hard reasoning." }
 }

package/skills/deck-builder/reference.md

@@ -29,6 +29,8 @@ These are bundled in [`templates/palettes.json`](templates/palettes.json) and se
 | `vibrant` | Internal / sales / pitch decks — energetic |
 | `dark-mode` | Engineering audiences who prefer dark, or for live demos |
 | `editorial` | Long-form / read-ahead decks with lots of text |
+| `forest` | Calm, nature-leaning — sustainability, long-horizon programmes |
+| `sunset` | Warm, narrative-leaning — story-first sales and internal decks |
 
 ## Layout → content matching
 
@@ -40,6 +42,9 @@ The biggest deck-design mistake is "everything is a bulleted content slide". Use
 | A list of 2–6 related points | `content` | `two_column` (over-engineered) |
 | A comparison (us vs. them, before vs. after) | `two_column` | `content` with sub-bullets |
 | A pithy customer / SME quote | `quote` | `content` ("Customer says…") |
+| 3+ comparable figures over time or category | `chart` | `content` with numbers in bullets |
+| Row-and-column data, ≤ 12 rows | `table` | `two_column` faked with aligned bullets |
+| An architecture / flow / screenshot | `image` | describing the diagram in prose |
 | A topic break / new section | `section` | another title slide |
 | First slide | `title` | jumping straight into `content` |
 | Final slide with The Ask | `closing` | `content` titled "Thank you" |
@@ -90,3 +95,86 @@ Speaker notes should be *what's not on the slide*, not a redundant copy.
 - **Don't use both italic and bold** in the same sentence for emphasis.
 - **Don't mix serif and sans-serif** unless you really know what you're doing.
 - **Slide numbers** — include them for decks > 10 slides; omit for short decks.
+
+## Brand templates
+
+A template is inherited, not imitated: `template` points the build at a `.pptx` or `.potx`, and
+the deck is generated on that file's masters, theme fonts, theme colours, logos and slide size.
+Sample slides shipped inside the template are dropped; its layouts are kept.
+
+### The layout map
+
+`layout_map` binds each logical layout to one of the template's layout names (or its index).
+Discover them with `--list-layouts`. Matching is exact name first, then case-insensitive, then
+substring — so `"content": "Title and Content"` and `"content": "title and content"` both hit.
+
+| Logical layout | What to map it to | If unmapped |
+|---|---|---|
+| `title` | The template's title/cover layout | Built-in cover — **loses the brand**, always map it |
+| `section` | Section header / divider | Built-in divider — always map it |
+| `content` | Title and content / title and bullets | Built-in — always map it |
+| `two_column` | Two content / comparison | Built-in two-column; acceptable |
+| `closing` | Closing / thank-you / title-only | Built-in — always map it |
+| `image` | Picture with caption (best), else title-only | Image drawn into the content area |
+| `big_number`, `quote`, `table`, `chart` | Title-only | Drawn into the claimed content area; fine |
+
+Placeholders are filled, not replaced — the run keeps the template's font, so the deck inherits
+the brand's typography instead of Calibri. Placeholders left unfilled are deleted, so no
+"Click to add text" ghosts survive. For `big_number`, `quote`, `table`, `chart` and `image`, the
+largest empty body (or picture) placeholder is claimed for its rectangle and removed, so custom
+content lands where the template intended content to go.
+
+### Template gotchas
+
+- **Slide size comes from the template.** `aspect` is ignored, with a warning. A 4:3 corporate
+  master produces a 4:3 deck — tell the user rather than silently letting it look cramped.
+- **Charts and tables are drawn, not templated.** They take palette colours, not theme colours.
+  Supply brand hexes alongside the template so they match.
+- **Slide numbers:** if the template's master already stamps them, the script does not add its
+  own.
+- **A template that fails to open** is a hard error, never a silent fall-back to the built-in
+  design — a deck that quietly lost its branding is worse than a failed build.
+
+## Charts
+
+`chart` types: `column`, `bar`, `line`, `stacked_column`, `stacked_bar`, `pie`, `doughnut`.
+
+| Question the slide answers | Type |
+|---|---|
+| How does this compare across categories? | `column` (≤ 7 categories) or `bar` (longer labels) |
+| How has this moved over time? | `line` |
+| What is the mix of a whole? | `pie`, and only with ≤ 5 slices |
+| How does the mix change across categories? | `stacked_column` |
+
+### Hard rules
+
+- **Every chart carries a `takeaway`** — the sentence the audience should leave with, above the
+  plot. A chart without one makes the audience do the analysis live.
+- **Every chart carries a `source`.** No source means the number is unverifiable, which on a
+  board deck means it is indefensible.
+- **Never chart invented numbers.** If the user supplied three figures, chart three figures.
+  A forecast is labelled a forecast, in the series name.
+- **`null` is the right value for a gap.** Padding a short series with zeroes draws a cliff that
+  didn't happen.
+- **Pie charts cap at 5 slices.** More than that, use `bar` sorted descending.
+- **One chart per slide.** Two charts is two slides, or a `two_column` with the takeaway split.
+
+## Tables
+
+- **≤ 12 data rows.** Past that it belongs in the appendix or an attached spreadsheet.
+- **≤ 5 columns** at 16:9, ≤ 4 at 4:3. Wider than that and the font drops below readable.
+- **Put the column the audience cares about last or first**, never buried in the middle.
+- **Cells are values, not sentences.** A table cell running to two lines means the content is
+  prose and wants a `content` slide.
+- Font size auto-shrinks past 7 and past 10 rows; header row takes `primary`, body rows zebra
+  against `#F2F4F8`.
+
+## Images
+
+- **Raster only.** `python-pptx` reads PNG/JPG/GIF/BMP/TIFF. SVG, EMF and PDF raise on import —
+  export to PNG at 2× the slide size before building.
+- **Relative paths resolve against the spec file**, not the working directory.
+- `position: "left"` / `"right"` pairs the image with bullets on the other half;
+  `"full"` (default) gives it the whole content area.
+- A missing or unreadable image draws a bordered placeholder box naming the file, and warns.
+  That box is a build artefact, never a deliverable — resolve it before the deck is presented.