DeckCraft

DeckCraft is a free, open-source clean-room take on Microsoft PowerPoint (storytold Crafting Apps). An agent drives it through an MCP server (deckcraft-cli mcp) or one-shot CLI commands. It opens and saves .pptx, and exports PDF (slides, notes pages, handouts), PNG/JPEG, animated GIF and text or RTF outlines. This skill is tested against DeckCraft 0.15.1.

When to Use

Use it for slides:

• pitch decks, quarterly reviews, lectures, training, status briefings, kickoff decks
• turning an outline or report into a deck, with charts, tables and speaker notes
• editing an existing .pptx: retheme, fix text, add notes/transitions, export PDF handouts or slide PNGs

Pick a different Crafting App when:

Setup

1. If tools named mcp_deckcraft_* are available, use them. This is the preferred way.
2. Otherwise check for the CLI with deckcraft-cli --version. If it's missing, load the storytold-install skill and run its setup deckcraft. Then ask the user to start a new session or run /reload-mcp.
3. Until the MCP tools appear, use the CLI one-shots (see CLI).

The server is headless by default (in-process engine, no window). Everything works except screenshot and the ui.* methods of call_app. For the user to watch live: deckcraft --control 7990, then deckcraft-cli mcp --connect 7990 (a port or host:port). --sample starts on the built-in sample deck. Optional --automation-read-root DIR / --automation-write-root DIR confine every file the server reads and writes (paths stay absolute; outside them you get automation path rejected: outside the write roots <DIR>, <DIR>: <path>). Repeat either flag to allow more folders. A root left out grants none of that access, and they conflict with --connect. Bare mcp is unconfined. The server also exposes two MCP resources: document (same as inspect_document) and commands (the full command list).

Mental Model

• Slides are built from layouts (title, titleAndContent, sectionHeader, twoContent, comparison, titleOnly, blank, contentWithCaption, pictureWithCaption). A layout gives placeholders (title, body obj, subtitle…) that inherit the theme's fonts and positions. Fill them with set_text {id, text}.
• Coordinates are points, y down. A 16:9 slide is 960 × 540. Boxes are [x, y, w, h]. Title placeholders sit at about [60, 29, 840, 104], the body at [60, 144, 840, 343]; keep free-placed content inside y ≥ 140.
• Shape ids are numbers. Every creating tool returns {id}; inspect_slide lists every shape's id, kind, placeholder type, box and text. Formatting commands act on the selection (select {ids}) or on ids. A wrong id in ids is refused (invalid parameters for `shape.fill`: no such shape); it no longer falls back to the selection.
• Tool arguments are checked (add_shape: unknown argument "rect" (expected: fill, h, line, preset, text, w, x, y)), but unknown keys inside run_command params are still ignored silently.
• There's a current slide. add_slide inserts after it and makes the new slide current; go_to_slide {index} switches. Shape tools (add_shape, insert_chart…) act on the current slide. Slide indexes are 0-based.
• Theme colours (accent1..accent6, tx1, bg1) work anywhere a colour does, so a retheme recolours them.
• Every action is a command (331). run_command {command, params} runs one, batch runs several.

Tools (Hermes names them mcp_deckcraft_<tool>)

Commands you'll use most

• Start: file.new {template} opens a 5-slide starter deck (Briefing, Lesson, Pitch, Field Notes, Quarterly, Evening Talk; file.templates lists them). slide.reuseList {path} lists another deck's slides; slide.reuse {path, slides?} copies them in.
• Slides: slide.notes {text, index?}, slide.layout {layout}, slide.duplicate, slide.move {from, to}, slide.delete {index}, slide.hide, slide.fromOutline {text}, section.add {name, at}, slide.actions {index?} (lists click/hover actions and links without running them).
• Design: design.theme {name}, design.colors {name | colors}, design.fonts {name | major, minor}, design.background {color | gradient | style, index?, all?}, design.headerFooter {slideNumber, footer, footerText, hideOnTitle}, design.slideSize {preset | w, h, orientation?}, design.effects {name}, design.variant {index}.
• Text (on selection): format.size {size}, format.bold, format.color {color}, format.font {family}, format.align {align}, format.bullets {on, char?}, format.numbering {on, scheme?}, format.paragraph {spaceAfter…}, format.autofit {mode}.
• Shapes: shape.fill {color | gradient | transparency | background:true} (a group formats its members), shape.line {color, width, dash, tail}, shape.effects {shadow: "outer"}, shape.setBounds {x, y, w, h, ids}, shape.connect {from, to, preset?}, arrange.align {edge, to?}, arrange.distribute, arrange.group.
• SmartArt & icons: insert.smartArt {kind, items} (items with leading tabs are sub-points) → {id}; smartArt.layout {kind}, smartArt.style {style}, smartArt.colors {colors}, smartArt.nodes / smartArt.setNodes, smartArt.fromText / toText. insert.icon {name, rect?} adds a Lucide icon as stroked shapes (shape.line recolours it).
• Charts & tables: chart.options {title, legend, dataLabels, gridlines, textColor}, chart.data, chart.type, table.style {style: "medium2-accent1"…}, table.options {headerRow, bandedRows…}, table.cellFill {color, cells}, table.merge, table.borders {which, color?, width?}, table.cellAlign {anchor?, align?} (vertical and horizontal).
• Motion: transition.set {kind, option?, duration?}, transition.applyAll, animation.add {effect, ids, start?}, animation.options {textBuild: "byParagraph", index}, animation.painter {id} + animation.painterApply {ids} (copy a sequence). Motion path of your own: animation.add {effect:"customPath", path:[[0,0],[200,-60],[400,0]], ids} (points are offsets from the shape, in pt).
• Files: file.export {path, format: "pdf", layout?: slides|notes|handouts, perPage?} (same as the export tool), file.properties {title, author…}, file.info (path, format, dirty, slide/hidden/section counts, properties).
• Selection Pane: selection.select {ids} (reaches into groups), selection.hideAll / selection.showAll, shape.visible {visible, ids}, shape.lock {locked?, ids} (no locked = toggle), arrange.reorder {id, index}.
• Text across the deck: text.find {text} → matches, text.replace {text, with} → {replaced} (slides, tables, notes), font.replace {from, to}.
• Pictures: picture.removeBackground, picture.style {style}, picture.recolor {preset}, picture.crop, picture.compress.
• Other: insert.hyperlink {url | slide, text?}, shape.action {action, slide? | url?}, insert.zoom {kind}, format.rtl {on} (right-to-left paragraphs), media.gifPlay {id, play?} (animated GIFs play in the show), review.accessibility, review.spelling (Hunspell when installed), review.compare {path} + review.accept / review.reject, format.languageAll {lang} (proofing language of every text).

Procedure

1. Plan one message per slide, the layout for each, and where charts/tables/pictures go. Pick a theme (DeckCraft, Harbor, Ember, Meadow, Nocturne, Paper, Coral Reef, Slate).
2. Build slide by slide: add_slide {layout, title} → inspect_slide for the placeholder ids → set_text / insert_* → slide.notes.
3. Style with theme colours, then transitions (transition.set + transition.applyAll) and a few animations.
4. Look: render_slide every slide. Check overlap with the title, overflow, contrast, empty placeholders.
5. Save .pptx, then export PDF/PNGs. Absolute paths; the PNG output folder must exist.

Recipe: 5-slide review deck (tested)

new_presentation {theme:"Harbor"}
set_text {id:258, text:"Northwind Q3 Review"} · set_text {id:259, text:"Leadership update - October 2026"}
run_command design.background {color:"#12384D", index:0}
select {ids:[258,259]} → run_command format.color {color:"#FFFFFF"}
run_command slide.notes {text:"Welcome. Twenty minutes, questions at the end.", index:0}

add_slide {layout:"titleAndContent", title:"Highlights"}  → inspect_slide → body placeholder id (here 262)
set_text {id:262, text:"Revenue up 12% quarter on quarter\nTwo new markets\n\tPorto\n\tWarsaw\nChurn down to 2.1%"}
run_command animation.add {effect:"fade", ids:[262]} → run_command animation.options {textBuild:"byParagraph", index:0}

add_slide {layout:"titleOnly", title:"Revenue by region"}
run_command insert.chart {type:"column", rect:[80,140,800,370], categories:["North","South","East"],
                          series:[{name:"Q2", values:[420,310,280]}, {name:"Q3", values:[470,355,300]}]}
      (same with the tool: insert_chart {type, categories, series, x:80, y:140, w:800, h:370})
run_command chart.options {title:null, dataLabels:true, legend:"b"}

add_slide {layout:"titleOnly", title:"Team"}
insert_table {rows:3, cols:2, x:80, y:150, w:800, h:150, data:[["Name","Role"],["Ana","Lead"],["Raj","QA"]]}
run_command table.style {style:"medium2-accent2"}

add_slide {layout:"twoContent", title:"Product snapshot"}       → placeholders 271 (left), 272 (right)
set_text {id:271, text:"Faster sync engine\nOffline mode\n\tiOS and Android"}
insert_picture {path:"/abs/chart.png", x:488, y:170, w:412, h:206} → run_command edit.delete {ids:[272]}

run_command design.headerFooter {slideNumber:true, footer:true, footerText:"Northwind - Confidential", hideOnTitle:true}
run_command transition.set {kind:"fade", duration:600} → run_command transition.applyAll
render_slide {slide:i, scale:0.6} for each slide  → look, fix
save_presentation {path:"/abs/deck.pptx"}
export {path:"/abs/deck.pdf"}                                          (format from the extension)
export {path:"/abs/deck-notes.pdf", format:"pdf", layout:"notes"}      (or layout:"handouts", perPage:6)
export {path:"/abs/png/slide.png", format:"png", all:true, scale:1}   → png/slide1.png … (folder must exist)
export {path:"/abs/deck.gif", width:"small", secondsPerSlide:2}        → {frames, width, height}
export {path:"/abs/deck.rtf"}                                          (outline as RTF; .txt with format:"outline")

Recipe: diagram slide with shapes (tested)

add_slide {layout:"blank"}
add_shape {preset:"roundRect", x:60,  y:60, w:260, h:140, fill:"accent1", line:"none", text:"Plan"}
add_shape {preset:"roundRect", x:350, y:60, w:260, h:140, fill:"accent2", line:"none", text:"Build"}
add_shape {preset:"roundRect", x:640, y:60, w:260, h:140, fill:"#F78154", line:"none", text:"Ship"}
add_text_box {x:60, y:300, w:840, text:"Three phases, one team.", size:40, align:"center", color:"#12384D"}
select {ids:[<the three ids>]} → run_command format.size {size:28} → run_command format.bold
run_command shape.connect {from:<id A>, to:<id B>, preset:"straightConnector1"}   ← glued connector → {id}
run_command shape.line {color:"tx1", width:2.5, tail:"triangle", ids:[<connector id>]}  (default line is thin and pale)
select {ids:[…]} → run_command shape.effects {shadow:"outer"}
render_slide {scale:0.6}                                   (moving a box later drags its connector along)

Recipe: process diagram with SmartArt and an icon (tested)

add_slide {layout:"titleOnly", title:"How it works"}
run_command insert.smartArt {kind:"process", items:["Sign up","Connect","\tBank","\tCards","Save"]}   → {id}
run_command smartArt.nodes                → [{text, level}]: Bank and Cards are level 1 under Connect
run_command smartArt.style {style:"polished"} · smartArt.colors {colors:"colorful"} · smartArt.layout {kind:"chevron"}
run_command insert.icon {name:"lightbulb", rect:[860,30,60,60]} → shape.line {color:"accent1", width:3}
render_slide {scale:0.6}

Recipe: edit an existing deck (tested)

open_presentation {path:"/abs/deck.pptx"} → inspect_document          (slide titles, notes, transitions)
run_command slide.notes {text:"…", index:0} · go_to_slide {index:1} → inspect_slide → set_text {id, text}
run_command design.theme {name:"Slate"}                                (accent fills and fonts follow; hex colours stay)
save_presentation {path:"/abs/deck-v2.pptx"}                           (notes, animations, transitions survive)

Recipe: morph between two slides (tested)

Morph animates shapes that share a name between a slide and the one before it. Duplicate, then change.

add_slide {layout:"blank"} → add_shape {preset:"ellipse", x:80, y:200, w:140, h:140, fill:"accent1", line:"none"}
add_text_box {x:80, y:40, w:800, text:"Step 1: start small", size:40}
run_command slide.duplicate          → the copy becomes current; its shapes get new ids, same names (inspect_slide)
run_command shape.setBounds {x:600, y:160, w:280, h:280, ids:[<copied ellipse>]} · shape.fill {color:"accent2", ids:[…]}
set_text {id:<copied text box>, text:"Step 2: grow"}
run_command transition.set {kind:"morph", option:"objects", index:<copy index>}    (words / characters morph text)
save_presentation {path:"/abs/morph.pptx"}       (writes p159:morph with a fade fallback for old viewers)

render_slide shows the end states only. To see the motion headlessly, render frames of the transition into a slide (--slide is 0-based, --t is 0..1 of the duration): deckcraft-cli render-transition /abs/morph.pptx --slide 1 --t 0.25,0.5,0.75 --width 480 /abs/m.png → m-t0.250.png … (tested: the circle sits halfway, colour blended).

Recipe: reuse slides and add a motion path (tested)

new_presentation {}
run_command slide.reuseList {path:"/abs/deck.pptx"}           → {name, slides:[{index, title, hidden}]}
run_command slide.reuse {path:"/abs/deck.pptx", slides:[2,3]} → {ids, slides:2}  (they take this deck's theme)
go_to_slide {index:1} → inspect_slide → the shape to move
run_command animation.add {effect:"customPath", path:[[0,0],[200,-60],[400,0]], ids:[<id>]}
                                                              → {count, path:"M 0 0 L 0.208333 -0.111111 L 0.416667 0 E"}

Formats

• Open: .pptx .deckcraft, and an .rtf outline (one slide per top-level paragraph). Save: .pptx .deckcraft. Export: PDF (slides, notes, handouts with perPage 1/2/3/4/6/9), PNG/JPEG (one slide or all; PNG optionally without the background), animated GIF, outline as text (format: "outline"; .txt/.md from the CLI) or RTF (.rtf).
• PDF has a selectable text layer (textLayer: false turns it off); dpi (36-600, default 200) sets the resolution of slide artwork. deckcraft-cli convert deck.pptx deck.pdf does it without MCP.
• From PowerPoint files DeckCraft draws WMF/EMF/EMF+ pictures, WordArt warps and combo charts, and since 0.8.0 Office 2016 charts (waterfall, funnel, treemap, sunburst, histogram, box and whisker), trendlines, error bars, SmartArt and 3-D effects. Comments, embedded fonts and sections survive a .pptx round trip (per the release notes).

CLI (no MCP needed)

deckcraft-cli info deck.pptx                          # JSON: slides, layouts, theme, notes
deckcraft-cli render deck.pptx /abs/outdir --all --scale 0.5   # outdir/slide-01.png … (OUT is a folder with --all)
deckcraft-cli render deck.pptx slide3.png --slide 2            # --slide is 0-based; --edit shows placeholder prompts
deckcraft-cli render deck.pptx logo.png --slide 2 --transparent   # RGBA, slide background left out
deckcraft-cli convert deck.pptx deck.pdf                       # or .pptx .deckcraft .md/.txt/.rtf (outline) .png .gif; others refused
deckcraft-cli run --cmd 'file.new={"theme":"Ember"}' \
  --cmd 'slide.fromOutline={"text":"Agenda\n\tWhy now\n\tPlan\nRisks\n\tBudget"}' --save /abs/o.pptx --export /abs/o.pdf
deckcraft-cli commands [FILTER]  ·  deckcraft-cli describe shape.fill     # one command's params
deckcraft-cli render --sample /abs/sample.png --slide 1        # built-in sample deck, handy for a test picture
deckcraft-cli render-transition deck.pptx --slide 1 --t 0,0.5,1 --width 480 /abs/tr.png  # tr-t0.000.png … frames of the transition into slide 1
deckcraft-cli run --in deck.pptx --export /abs/d.gif --export-params '{"width":"small","secondsPerSlide":3}'
deckcraft-cli run --cmd-file cmds.txt --save /abs/o.pptx --print   # one `id={json}` per line, # comments; no shell quoting
deckcraft-cli app [--port PORT] COMMAND [JSON]                 # run a command in a running desktop app
deckcraft-cli help [SUBCOMMAND]                                # usage for one subcommand (also SUBCOMMAND --help)

Pitfalls

• A chart without a box lands over the title: insert_chart with no x, y, w, h (and insert.chart with no rect) puts it at [144, 81, 672, 378], even on a content layout (it doesn't fill the placeholder). Always pass the box, or move it with shape.setBounds {x, y, w, h, ids}.
• A chart without title shows "Chart Title". Pass title, or chart.options {title:null} to remove it.
• An unknown chart type is not an error: insert_chart {type:"bogus"} makes a clustered column chart. Use the names in insert.chart (column, bar, line, pie, doughnut, area, scatter, stackedColumn…) and check with inspect_slide.
• Placeholders you don't fill stay on the slide. Delete unused ones (edit.delete {ids}) after putting a picture or chart in their place, or use titleOnly/blank layouts.
• animation.options without index fails: invalid parameters for `animation`: no animation to change (select an animated object or give `index`). animation.add {ids} doesn't select the shape. Use index (0-based on the current slide) or select first.
• export {all:true} writes <stem>1.png, <stem>2.png… and fails if the folder doesn't exist: …/slide1.png: No such file or directory (os error 2) (Windows: The system cannot find the path specified. (os error 3)).
• The export tool refuses transparentBackground (export: unknown argument "transparentBackground" (expected: all, dpi, …)); use run_command file.export {path, slide, transparentBackground:true} or deckcraft-cli render … --transparent.
• The outline (format:"outline", .rtf, .md) also lists footer text and the slide-number field (‹#›) under each slide that shows them.
• (seen in 0.8.0, not re-checked) pdftotext reads a slide-number field as < and joins bullet lines (Revenue up 12% quarter on quarter Two new markets) in DeckCraft PDFs. The visible PDF is fine. For a text check use export {format:"outline"} or inspect_document.
• shape.connect with a wrong id says both shapes need connection sites (lines and groups have none) rather than "not found". Check ids with inspect_slide.
• export to a path with an unknown extension and no format silently writes a native .deckcraft (zip) under that name. Give format or a known extension. (A bad format is refused: unknown format `tiff` .)
• SmartArt text sits centred in its boxes, but after a .pptx save and reopen it sits at the top of each box.
• deckcraft-cli run --cmd file.new makes a second document ({"document":1}; the run starts with one); the active (new) one is saved. slide.fromOutline appends after the existing empty title slide; add --cmd 'slide.delete={"index":0}'.
• Text inside add_shape shapes comes out small; size it with select + format.size.
• Use theme colours (accent1..accent6) for anything that should follow a retheme. Hex fills and text colours stay put when you run design.theme (and inspect_slide reports both as resolved hex, so you can't tell them apart later).
• Errors are explicit, e.g. unknown command `shape.fil` , invalid parameters for `slide.layout`: no layout "bogus" , invalid parameters for `slide.go`: no slide 99 (go_to_slide too), invalid parameters for `shape.fill`: no such shape. Look ids up with list_commands {filter} or deckcraft-cli describe ID; don't invent them.
• UI-only tools fail headless: screenshot: it needs the desktop app: start `deckcraft --control 7979` and run the MCP server with `deckcraft-cli mcp --connect 7979`. Use render_slide to see a slide headlessly. call_app ui.click (and other UI actions) fail with ui.click: it needs the desktop app: …; call_app ui.inspect answers {headless: true, tool}.

Verification

• inspect_document: slide count, titles, layouts, notes, transition, animations per slide.
• render_slide every slide and look before reporting done.
• deckcraft-cli info out.pptx reopens the saved file; export {format:"outline"} gives a quick text check.

References

Grep these rather than reading them whole:

• ${HERMES_SKILL_DIR}/references/commands.md: all 331 commands with params, menu place and shortcut (grep -n 'chart[.]' ${HERMES_SKILL_DIR}/references/commands.md).
• ${HERMES_SKILL_DIR}/references/catalogs.md: themes, colour/font/effect schemes, starter decks, 183 shape presets, 49 transitions, 107 animation effects, 70 icons, picture styles (grep -n 'morph' ${HERMES_SKILL_DIR}/references/catalogs.md).
• Upstream docs: https://github.com/storytold/deckcraft/tree/main/docs (mcp.md, control-protocol.md).