[New Skill]: creative/deck_builder — deterministic PPTX assembly from structured deck specs

[rosspeili]

Skill ID

creative/deck_builder

Category

Propose new category (describe below)

What should this skill do?

Propose new category (describe below)

Use the existing creative category (same as creative/bg_remover). Maintainer: will add creative to the issue template dropdown via another issue.

~

Problem

Agents and automation pipelines often need editable PowerPoint (.pptx) deliverables — pitch decks, status reports, training slides, QBR packs — but host LLMs cannot reliably produce valid OOXML by themselves. Commercial tools (Gamma, SlideSpeak, etc.) bundle narrative AI + design + export as opaque SaaS. Skillware needs a registry skill that does one job well: turn a validated, structured deck specification into a real .pptx file deterministically, while the agent owns narrative, research, and image acquisition.

Proposed capability

creative/deck_builder assembles professional presentations locally using python-pptx (and Pillow for image normalization). The skill:

• Accepts a deck_spec JSON document (slides, layout types, text, tables, chart data, image references, speaker notes, theme overrides).
• Exposes multiple actions (same pattern as dev_tools/issue_resolver): at minimum validate_spec, render, and inspect.
• Ships bundled .pptx templates and layout presets under the skill bundle (corporate, pitch, minimal dark/light) so output is visually consistent without requiring PowerPoint installed.
• Writes output to a caller-supplied output_path with path-safety checks (no traversal, parent dir creation).
• Returns structured JSON: success flag, slide count, output path, per-slide summary, warnings (truncated text, missing assets, fallback layout), and error codes.

Design principles (Skillware-aligned)

• Deterministic execute() — no LLM calls, no image generation APIs, no network I/O inside the skill. Narrative and Imagen/DALL·E/Gemini image work stay in the agent loop; the skill only assembles what it is given (paths, base64, or inline table/chart data).
• Schema-first — strict validation before render; agents can call validate_spec and fix errors without producing a broken file.
• Template + theme tokens — fonts, colors, margins, and master layouts live in bundled templates and optional theme block in deck_spec; not free-form HTML/CSS in v1.
• Composable with other skills — e.g. agent uses creative/bg_remover on logos, fetches stock images externally, then passes asset paths into deck_builder.
• Testable offline — bundle tests with fixture PNGs, fixture deck_spec JSON, golden checks (slide count, title text, file exists, no corrupt PPTX).

Non-goals (v1)

• Built-in AI slide copy or auto-outline generation
• Built-in image generation (Imagen, etc.)
• Animations, transitions, embedded video/audio
• Google Slides / Keynote export
• PptxGenJS / Node subprocess pipeline
• “One-click doc → beautiful deck” without agent-provided structure

Slide / layout types (v1 scope)

Full v1 should support a complete deck-building surface, not a toy demo:

Type	Purpose
title	Cover: title, subtitle, optional hero image
section	Section divider
bullets	Title + bullet list (max bullets/chars enforced)
two_column	Title + left/right blocks (text or bullets)
image	Full or half-bleed image with optional title
image_caption	Image + caption body
quote	Pull quote + attribution
table	Title + table from JSON rows/columns
chart	Title + bar/line/pie from JSON series (python-pptx chart APIs)
blank	Intentionally empty canvas for agent follow-up

Bundled deliverables (full skill, not MVP)

Per CONTRIBUTING new-skill checklist:

• skills/creative/deck_builder/ — manifest.yaml, skill.py, instructions.md, card.json, test_skill.py
• templates/ — at least 3 master .pptx templates + documented layout indices
• kb/ or schemas/ — JSON Schema for deck_spec (optional but recommended for validation action)
• docs/skills/deck_builder.md + catalog row in docs/skills/README.md
• examples/deck_builder_demo.py (local execute, fixture spec → sample deck)
• examples/README.md + docs/usage/agent_loops.md rows
• tests/fixtures/card_ui_schema/creative__deck_builder.json if output uses ui_schema
• python scripts/sync_extras.py entry → skillware[creative_deck_builder]
• CHANGELOG [Unreleased] entry on merge

Reference skills

• creative/bg_remover — local media transform, path validation, session-less deterministic execute
• dev_tools/issue_resolver — multi-action router, structured payloads, provenance-friendly outputs
• office/pdf_form_filler — document output skill (agent supplies semantics; skill assembles file)

Success criteria

An agent with no special plugins can: validate a 12-slide investor deck spec, render a .pptx using the pitch template, receive warnings for one missing optional image, open the file in PowerPoint/LibreOffice with editable text and notes, and pass pytest skills/creative/deck_builder/test_skill.py offline in CI.

Ideal Inputs & Outputs

Actions

action	Required params	Purpose
validate_spec (default)	deck_spec	Schema + business rules; no file write
render	deck_spec, output_path	Produce .pptx
inspect	input_path	Read existing .pptx; return slide manifest (titles, layout hints, notes presence)
list_templates	—	Return bundled template IDs, descriptions, aspect ratio

Optional params (all actions where relevant): template_id, theme, strict (fail on warnings vs continue).

---

deck_spec (core input object)

{
  "title": "Skillware Investor Overview",
  "template_id": "pitch_v1",
  "theme": {
    "accent_color": "#6E57E0",
    "font_heading": "Calibri",
    "font_body": "Calibri"
  },
  "metadata": {
    "author": "ARPA HLS",
    "subject": "Series A materials"
  },
  "slides": [
    {
      "type": "title",
      "title": "Skillware",
      "subtitle": "Deterministic skills for agent runtimes",
      "image": { "path": "/tmp/logo.png" }
    },
    {
      "type": "bullets",
      "title": "Why now",
      "bullets": [
        "Agents need callable capabilities, not monolithic prompts",
        "Registry + loader + constitution model scales across providers"
      ],
      "speaker_notes": "Keep to 60 seconds."
    },
    {
      "type": "chart",
      "title": "Registry growth",
      "chart": {
        "kind": "bar",
        "categories": ["Q1", "Q2", "Q3"],
        "series": [{ "name": "Skills", "values": [8, 12, 16] }]
      }
    },
    {
      "type": "image_caption",
      "title": "Architecture",
      "image": { "base64": "<PNG bytes>", "mime_type": "image/png" },
      "body": "Host ↔ Loader ↔ Bundled skills"
    }
  ]
}

Images: path (preferred) or base64 + mime_type. Skill normalizes with Pillow (resize max dimension, reject empty/oversized files).

---

Output: validate_spec (status ready)

{
  "success": true,
  "action": "validate_spec",
  "valid": true,
  "template_id": "pitch_v1",
  "slide_count": 4,
  "warnings": [
    { "code": "BULLET_TRUNCATED", "slide_index": 1, "message": "Bullet 3 exceeded 120 chars; will truncate on render." }
  ],
  "errors": []
}

Output: render (status ready)

{
  "success": true,
  "action": "render",
  "output_path": "/tmp/skillware_pitch.pptx",
  "template_id": "pitch_v1",
  "slide_count": 4,
  "file_size_bytes": 284000,
  "slides": [
    { "index": 0, "type": "title", "title": "Skillware" },
    { "index": 1, "type": "bullets", "title": "Why now" }
  ],
  "warnings": [],
  "error_code": null
}

Output: errors (examples)

error_code	When
INVALID_SPEC	Schema violation, unknown slide type, empty deck
TEMPLATE_NOT_FOUND	Bad template_id
ASSET_NOT_FOUND	Image path missing
ASSET_INVALID	Corrupt image, unsupported format, over size limit
OUTPUT_PATH_UNSAFE	Traversal or invalid output_path
RENDER_FAILED	python-pptx failure
INSPECT_FAILED	Cannot read input_path as pptx

Output: inspect

{
  "success": true,
  "action": "inspect",
  "slide_count": 4,
  "slides": [
    { "index": 0, "layout_name": "Title Slide", "title": "Skillware", "has_notes": false }
  ]
}

Target runtime

Model agnostic (all supported adapters)

External APIs & env vars (if any)

None required.

creative/deck_builder is fully offline for execute(). No API keys in the skill manifest.

Optional runtime deps (declared in manifest.yaml requirements, exposed as pip install "skillware[creative_deck_builder]"):

• python-pptx — OOXML generation
• Pillow — image decode, resize, format validation

Agent/host responsibilities (outside this skill):

• LLM for narrative and outline → produces deck_spec
• Image APIs (Imagen, DALL·E, etc.) or local assets → paths/base64 passed into deck_spec
• User filesystem permissions for output_path

Constitution (draft):

1. LOCAL_ASSEMBLY: Never call network APIs or LLMs from execute().
2. DETERMINISTIC: Same valid deck_spec + template → reproducible slide structure and text content.
3. EDITABLE_OUTPUT: Produce standard .pptx editable in PowerPoint/LibreOffice; do not rasterize whole slides unless explicitly requested in a future version.
4. FAIL_CLOSED: Validate before render; reject unsafe paths and invalid assets.
5. PRIVACY: Do not persist deck content beyond the caller's output_path.

[alex12138356]

python-pptx is the right tool here. I can build the deck_builder skill with validate_spec/render/inspect/list_templates, three bundled templates, path-safe output, and offline tests. Happy to take this one.

[rosspeili]

Hey @alex12138356, welcome, and thanks for picking this up. Assigned to you.

Your plan lines up with the issue. <3

Direction tips

• Start from templates/python_skill/ and mirror creative/bg_remover (path validation, deterministic execute(), no network) plus dev_tools/issue_resolver (action dispatch) and office/pdf_form_filler (document assembly pattern).
• Ship the full bundle in one PR per the issue checklist: manifest, skill.py, instructions.md, card.json, test_skill.py, templates/ (≥3 .pptx masters), docs, example, sync_extras.py → creative_deck_builder, CHANGELOG under [Unreleased].
• Keep v1 scope tight: all slide types in the table, but no LLM/image APIs inside the skill, agent supplies deck_spec + asset paths/base64 only.
• Default action validate_spec, render only after validation passes (you can reuse same validator for both).

Tips

• Document template layout indices in instructions.md so agents pick the right master slides.
• Reuse path/traversal patterns from bg_remover, add a 12-slide fixture spec matching the success criteria in the issue.
• After adding deps, run python scripts/sync_extras.py and pytest skills/creative/deck_builder/test_skill.py locally before opening the PR.

Open a draft PR early if you want a scope check, happy to review incrementally. Ping here if anything in the spec is ambiguous before you go deep on chart layouts.