skilldrop-cli 0.16.3__py3-none-any.whl

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

@@ -0,0 +1,40 @@
+{
+  "skill_name": "deck-builder",
+  "evals": [
+    {
+      "id": 1,
+      "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"
+      ]
+    }
+  ]
+}

skilldrop_cli/data/packs/design/skills/deck-builder/examples/exec-board-update.md

@@ -0,0 +1,108 @@
+# Example: Quarterly board update for a migration project
+
+**Prompt the user gave:** *"Build me a board update deck for our migration project. We're 60% through, on track for Q1 close, $2.4M annualised infra savings so far, but we discovered two services need a schema rewrite and we now have a multi-region regulatory requirement. We're asking for a $620k budget overrun. Use corporate-blue palette."*
+
+## Step 1 — Audience archetype lookup
+
+Board update → use `audience-profile.board` archetype:
+
+- **Slide count target:** 8–12
+- **Bullet density:** ≤ 3 bullets/slide, ≤ 6 words/bullet
+- **Required sections:** Cover, TL;DR, Strategic context, Financials, Risks, Ask
+- **Tone:** Outcomes-led, business-first, big numbers welcome
+- **Layouts to favour:** `big_number` (for the $2.4M and the $620k), `quote` (for credibility), `two_column` (for scope changes)
+
+## Step 2 — Build the deck spec
+
+```json
+{
+  "title": "ProjectX Migration — Board Update",
+  "audience": "board",
+  "palette": "corporate-blue",
+
+  "slides": [
+    {
+      "layout": "title",
+      "title": "ProjectX Migration",
+      "subtitle": "Board update — Q3 FY26",
+      "presenter": "John Doe",
+      "date": "2026-09-15",
+      "notes": "Open with: 'We're 60% through, on track, and asking for an overrun. Here's why it's still a good deal.'"
+    },
+    {
+      "layout": "content",
+      "title": "60% complete, zero customer incidents, on track for Q1 close",
+      "bullets": [
+        "8 of 14 services cut over",
+        "p99 latency down 22% on migrated services",
+        "Two services moved to phase 3 — schema rewrite"
+      ],
+      "notes": "Lead with zero incidents. Boards remember that more than any other number on this slide."
+    },
+    {
+      "layout": "big_number",
+      "title": "Annualised infra savings already realised",
+      "number": "$2.4M",
+      "caption": "From the 8 migrated services. Projected $5.8M at completion.",
+      "notes": "Pause. Let the number land. Don't rush to the next slide."
+    },
+    {
+      "layout": "two_column",
+      "title": "What changed since the original plan",
+      "left": {
+        "title": "Original scope",
+        "bullets": ["14 services migrated", "Single-region active", "Legacy DB decommissioned"]
+      },
+      "right": {
+        "title": "Discovered in flight",
+        "bullets": ["Schema rewrite for 2 services", "Multi-region (EU regulator)", "Auth refactor coupling"]
+      },
+      "notes": "Multi-region is a regulator change, not a planning miss. Say so explicitly."
+    },
+    {
+      "layout": "quote",
+      "quote": "The migration went smoother than any I've seen in 20 years.",
+      "attribution": "VP Engineering, post phase-2 cut-over",
+      "notes": "Optional, but de-risks the perception that we're behind."
+    },
+    {
+      "layout": "content",
+      "title": "Top 3 risks for the remaining 40%",
+      "bullets": [
+        "Schema rewrite: 6 weeks, dry-runs underway",
+        "Auth refactor coupling: increases coordination overhead",
+        "Holiday freeze: -4 calendar weeks"
+      ],
+      "notes": "Don't soften the risks. Boards trust presenters who name them."
+    },
+    {
+      "layout": "big_number",
+      "title": "Budget overrun we're requesting",
+      "number": "$620k",
+      "caption": "Covers schema rewrite + multi-region buildout. Payback: < 8 months.",
+      "notes": "Position the overrun against the $5.8M projected savings — net positive within the same fiscal year."
+    },
+    {
+      "layout": "closing",
+      "title": "Approval requested: $620k FY26 budget overrun",
+      "subtitle": "Decision needed by 2026-10-01 to keep Q1 close",
+      "notes": "Land here. Take questions. Don't add a thank-you slide."
+    }
+  ]
+}
+```
+
+## Step 3 — Generate
+
+```bash
+python3 scripts/build_deck.py /tmp/board-update.json -o ./out/board-update.pptx
+```
+
+## Step 4 — Hand-off to the user
+
+> Generated `out/board-update.pptx` — 8 slides, corporate-blue palette. Two notes before you present:
+>
+> 1. **Verify the speaker notes** — I wrote them based on the content you gave me. Read through and adjust your phrasing.
+> 2. **Replace the slide 5 quote** — I used a placeholder attribution. If you have the actual quote (and clearance to use it), paste it in slide 5.
+>
+> Want me to also produce an exec-summary one-pager from the same content?

skilldrop_cli/data/packs/design/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.

skilldrop_cli/data/packs/design/skills/deck-builder/manifest.json

@@ -0,0 +1,18 @@
+{
+  "name": "deck-builder",
+  "version": "0.3.1",
+  "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": ["brand-kit", "audience-profile", "slide-outliner", "doc-critique"],
+  "install": {
+    "pip": "python3 -m pip install -r requirements.txt"
+  },
+  "tags": ["powerpoint", "pptx", "deck", "presentation", "template", "charts", "stakeholder-communication"],
+  "permissions": {"network": [], "commands": [], "files": "named-paths", "notes": "Needs the python-pptx package (declared in deps)."},
+  "model": { "tier": "standard", "rationale": "Shapes content, maps a brand template's layouts, and runs a script. Judgment, not hard reasoning." }
+}

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

@@ -0,0 +1,180 @@
+# deck-builder — design reference
+
+## Color palette principles
+
+A presentation palette needs five roles. If the user gives you fewer than five colors, derive the missing ones following these rules:
+
+| Role | Where it's used | Picking rule |
+|---|---|---|
+| **primary** | Title bars, section dividers, big-number captions | The user's brand colour, or the dominant colour in their material |
+| **secondary** | Sparingly — second-tier emphasis, alt charts | Analogous or complementary to primary; ~30° apart on the wheel |
+| **accent** | Highlight bars, the actual big numbers, quote bars | High-saturation pop colour; should NOT match background or primary |
+| **background** | Slide background | Near-white (#FFFFFF or #F8F9FA) for most decks; near-black for dark-mode decks |
+| **text** | Body text, bullet text | ≥ 4.5:1 contrast against background. Default `#222222` on white, `#EAEAEA` on dark |
+
+### Hard rules
+
+- **Contrast ≥ 4.5:1** between text and background (WCAG AA). If the user-supplied palette fails this, *substitute* and explain — don't ship an unreadable deck.
+- **Never put primary text on primary background** — use white-on-primary or vice versa for title bars/section slides.
+- **Accent appears on ≤ 20% of slides.** It's a pop colour, not a body colour.
+
+### Preset palettes
+
+These are bundled in [`templates/palettes.json`](templates/palettes.json) and selectable by name:
+
+| Name | When to use |
+|---|---|
+| `corporate-blue` | Default for B2B / enterprise audiences when no brand colour is given |
+| `monochrome` | When the deck needs to feel restrained / when content is sensitive |
+| `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
+
+The biggest deck-design mistake is "everything is a bulleted content slide". Use this mapping to pick the right layout for the content:
+
+| Content shape | Right layout | Wrong layout |
+|---|---|---|
+| One key takeaway you want to land | `big_number` | `content` (gets lost in bullets) |
+| 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" |
+
+## Per-audience density rules
+
+How many bullets a slide can carry without falling apart, by audience:
+
+| Audience | Bullets / slide | Words / bullet | Slide-title style |
+|---|---|---|---|
+| `exec` | 3 max | ≤ 8 | Assertion ("Postgres meets latency target") |
+| `board` | 3 max | ≤ 6 | Outcome ("$24M ARR protected by Q3") |
+| `technical` | 5–6 | ≤ 14 | Descriptive ok ("Migration approach") |
+| `sales` | 3–4 | ≤ 10 | Benefit-led ("Cut close time by 40%") |
+| `internal` | 4–5 | ≤ 12 | Topic ok ("Q3 priorities") |
+| `investor` | 3–4 | ≤ 10 | Assertion + number where possible |
+| `partner` | 3–4 | ≤ 10 | Mutual benefit ("Joint customers see X") |
+| `customer` | 3–4 | ≤ 12 | Outcome for them ("You'll save…") |
+
+## Slide-count budgets
+
+| Audience / format | Slide count target | Hard upper bound |
+|---|---|---|
+| `exec` quick update (5 min) | 5 | 8 |
+| `exec` decision review (15 min) | 8–10 | 12 |
+| `board` quarterly (20 min) | 10 | 15 |
+| `technical` design review (30 min) | 12–15 | 20 |
+| `sales` first pitch (15 min) | 8 | 12 |
+| `investor` Series-style | 10–12 | 15 |
+| `internal` team alignment | 5–8 | 10 |
+
+If the user's content can't fit in the upper bound, *say so* — recommend splitting into two decks rather than cramming.
+
+## Speaker notes patterns
+
+Every slide should have notes. The pattern that works:
+
+1. **Hook sentence** — what the presenter opens with on this slide.
+2. **Key emphasis** — which bullet/number to dwell on.
+3. **Transition** — one sentence that flows into the next slide.
+
+Speaker notes should be *what's not on the slide*, not a redundant copy.
+
+## Common gotchas
+
+- **Don't centre body text.** Centred bullets are harder to scan. Reserve centring for `big_number`, `quote`, and `title`/`closing` slides.
+- **Don't underline links** — coloured-and-bold is the modern convention.
+- **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.

skilldrop_cli/data/packs/design/skills/deck-builder/requirements.txt

@@ -0,0 +1,3 @@
+# Pinned, not ranged: an open range lets a future release install itself unreviewed.
+# python-pptx 1.0.2 requires Python >= 3.8.
+python-pptx==1.0.2