Keynote Skill
Quick Reference
| Task | Guide |
|---|---|
Read / analyze a .key deck | python scripts/keynote_tool.py inspect presentation.key --json |
| Dump text by slide | python scripts/keynote_tool.py dump-text presentation.key |
| Get slide count | python scripts/keynote_tool.py get-slide-count presentation.key |
| Read presenter notes | python scripts/keynote_tool.py get-notes presentation.key --json |
| List master layouts | python scripts/keynote_tool.py list-masters presentation.key --json |
| Edit existing Keynote deck | Read editing.md |
| Create deck from scratch | Read creation.md |
| List available themes | python scripts/keynote_tool.py list-themes |
| Export to PPTX / PDF | python scripts/keynote_tool.py export presentation.key --pptx out.pptx --pdf out.pdf |
| Render slide images | python scripts/keynote_tool.py render-images presentation.key --out-dir rendered |
| Render specific slides | python scripts/keynote_tool.py render-images presentation.key --out-dir rendered --slides 3,6-8 |
| Add a shape | python scripts/keynote_tool.py add-shape presentation.key --slide 4 --text "Kafka" --x 100 --y 200 --width 300 --height 55 |
| Delete shape(s) | python scripts/keynote_tool.py delete-shape presentation.key --slide 4 --shape 1 or --all |
| Delete image(s) | python scripts/keynote_tool.py delete-image presentation.key --slide 6 --all |
| Style a shape | python scripts/keynote_tool.py style-shape presentation.key --slide 4 --shape 1 --fill "#EE7F01" --border "#000000" |
Reading Content
# Inspect slide structure, layouts, and text item counts
python scripts/keynote_tool.py inspect presentation.key --json
# Dump text grouped by slide (includes layout names)
python scripts/keynote_tool.py dump-text presentation.key
# Quick slide count
python scripts/keynote_tool.py get-slide-count presentation.key
# Read presenter notes (all slides or specific)
python scripts/keynote_tool.py get-notes presentation.key --json
python scripts/keynote_tool.py get-notes presentation.key --slide 3
# List available master slide layouts (essential for template-based work)
python scripts/keynote_tool.py list-masters presentation.key --json
# Export for downstream tooling
python scripts/keynote_tool.py export presentation.key --pptx output.pptx --pdf output.pdfEditing Workflow
Read editing.md for full details.
- Inspect slide structure with
inspectanddump-text. - Apply targeted edits with
replace-text,set-text,format-text, or structural commands. - Export to
.pdf/.pptxand run visual/content QA.
Creating From Scratch
Read creation.md for full details.
Use when no template deck exists or when a new native .key deck is required. For template-based workflows (corporate templates), see the template section in creation.md.
Command Reference
| Command | Purpose |
|---|---|
inspect | Slide count, layout names, and text-item inventory |
dump-text | Human-readable text by slide with layout info |
get-slide-count | Quick slide count |
get-notes | Read presenter notes |
set-notes | Write presenter notes |
replace-text | Find/replace text across all text items |
set-text | Set text of a specific text item on a specific slide |
format-text | Set font, size, and/or color of a text item |
add-text-item | Create a new text box on a slide with optional formatting |
add-slide | Add a new slide (optional position and layout) |
delete-slide | Delete a slide by index |
add-image | Insert an image on a slide with optional position/size |
list-themes | List available Keynote themes |
list-masters | List master slide layouts in a document |
create | Create a new empty Keynote document |
export | Export .key to .pptx and/or .pdf |
add-shape | Create a shape (rectangle with text) on a slide |
delete-shape | Delete shape(s) from a slide |
delete-image | Delete image(s) from a slide |
style-shape | Apply fill/border color via GUI scripting (requires accessibility) |
render-images | Slide image rendering for QA (supports selective slides) |
Design Guidelines
Color Strategy
- Use 2-3 accent colors plus a neutral background.
- Pick colors from the Keynote theme palette for consistency.
- Ensure sufficient contrast between text and background (4.5:1 minimum).
Typography
| Element | Font Size | Weight |
|---|---|---|
| Slide title | 36-44 pt | Bold |
| Section header | 28-32 pt | Bold |
| Body text | 18-24 pt | Regular |
| Code blocks | 14-20 pt | Monospace (Menlo, SF Mono) |
| Captions / footnotes | 12-14 pt | Regular or Light |
- Limit each slide to 2 font families maximum.
- Use the theme's default fonts unless there is a specific reason to override.
- For code slides: use
format-text --font "Menlo" --color "#FFFFFF"on Code master layouts.
Layout
- Keep a 40-60 pt margin from all slide edges.
- Align elements to a consistent grid.
- Place one key idea per slide; avoid visual clutter.
- Use visual elements (images, shapes, charts) on most slides to maintain engagement.
QA (Required)
- Always export edited deck to
.pdfand/or.pptx. - Verify text content after edits (
dump-textormarkitdownon exported.pptx). - Render slide images and inspect overlap, clipping, and spacing.
- Use
--slidesto render only changed slides and conserve resources.
# Render all slides
python scripts/keynote_tool.py render-images presentation.key --out-dir rendered
# Render only specific slides (saves time and tokens)
python scripts/keynote_tool.py render-images presentation.key --out-dir rendered --slides 3,6-8Limitations
- Native
.keyediting requires macOS + Keynote.app. - Keynote automation is not truly headless; the app may still launch or briefly appear during operations.
- Script avoids forced app focus (
activate) to reduce UI interruption, but macOS may still surface windows. - Some master layouts have linked text items (e.g., Code layout links t1 and t3). Use
add-text-itemto create independent text boxes when needed. style-shapeuses GUI scripting via System Events and requires macOS accessibility permissions.inspectnow shows shape and image counts per slide.
Dependencies
- Python 3.10+
- macOS with
Keynote.app osascriptpdftoppm(optional, for image rendering)