Skip to content
Back to search

keynote-skill

MarketplaceWorks with Claude CodeGitHub

Claude skill for Apple Keynote (.key) files

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/ronin-gw--keynote-skill/badge.svg)](/listings/ronin-gw--keynote-skill)

HTML

<a href="/listings/ronin-gw--keynote-skill"><img src="/api/listings/ronin-gw--keynote-skill/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Install it as a Claude Code plugin. In Claude Code:

/plugin marketplace add ronin-gw/keynote-skill
/plugin install keynote@keynote-skill

Then install the Python dependencies (the plugin does not install them):

pip install keynote-parser Pillow

Update later with `/plugin marketplace update keynote-skill`. Rendering and structural changes need macOS with Keynote installed.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 14 lines
  1. {
  2. "name": "keynote-skill",
  3. "owner": {
  4. "name": "Hayato Anzawa"
  5. },
  6. "description": "Claude skill for Apple Keynote (.key) files",
  7. "plugins": [
  8. {
  9. "name": "keynote",
  10. "source": "./",
  11. "description": "Read, create and edit Apple Keynote (.key) files directly, without converting to pptx (macOS)."
  12. }
  13. ]
  14. }
README.md · README · 133 lines
  1. # keynote-skill
  2. [日本語](README-jp.md)
  3. A Claude skill for reading, creating and editing Apple Keynote (`.key`) files **directly, without converting to pptx**.
  4. It aims to be the Keynote counterpart of the [pptx skill in anthropics/skills](https://github.com/anthropics/skills/tree/main/skills/pptx). Requires macOS.
  5. ## Which skill to use: this one or Apple's
  6. Apple publishes [creator-studio-doc-format](https://github.com/apple/creator-studio-doc-format), a library and skill for the [Keynote Interchange Format](https://developer.apple.com/documentation/keynoteinterchangeformat) (`.keyx`).
  7. The two work on different files and complement each other.
  8. | You want to… | Use |
  9. |---|---|
  10. | Read or edit a `.key` you already have | **this skill** |
  11. | See the slides (PNG / JPEG / PDF) and check the layout | **this skill** |
  12. | Keep transitions, builds, comments and skipped slides while editing | **this skill** |
  13. | Convert a `.pptx` to Keynote, or merge decks | **this skill** |
  14. | Look at a `.keyx` and have the AI review it | **this skill** (rendering only, Keynote 16 or later) |
  15. | Read the content of, create or edit a `.keyx` | Apple's |
  16. | Generate a deck without Keynote (Linux, CI, a server) | Apple's |
  17. | Text hyperlinks, groups, movies and audio, table formulas, layout (master) edits | Apple's |
  18. - **This skill works on the `.key` itself.** Nothing is exported or converted, so whatever the skill does not touch stays as it was. It needs macOS, and Keynote for rendering and structural changes.
  19. - **Apple's skill works on `.keyx`**, an official JSON format that Keynote 16 or later exports (File > Export To) and opens. It needs no Keynote and runs anywhere, but it cannot render, and `.keyx` 1.0 beta leaves out transitions and builds, comments, Skip Slide, passwords and [more](https://developer.apple.com/documentation/keynoteinterchangeformat/keynote-interchange-format-release-notes). Exporting an existing deck to `.keyx` drops them.
  20. - **The two can be used together.** Apple's skill has no way to see its output; this one renders a `.keyx` with Keynote, so an AI can write a `.keyx` with Apple's library and then review the result as images:
  21. ```bash
  22. python3 <skill dir>/scripts/key_render.py deck.keyx qa/ --jpeg
  23. ```
  24. Keynote 16 or later is picked automatically for a `.keyx` (older versions cannot open one). If none is installed, the script says so and does not hand the file to Keynote. Slide images, `--grid` and `--pdf` work; the other scripts read `.key` only.
  25. - **Which one lasts.** `.keyx` is a documented format that Apple maintains. This skill reads an undocumented format through [keynote-parser](https://github.com/psobot/keynote-parser) and can break when Keynote changes it. Where Apple's skill covers your job, prefer it.
  26. ## How it works
  27. A `.key` file holds `Index/*.iwa` files (Snappy-compressed Protobuf). The skill uses two routes:
  28. | Route | What it does | Keynote app |
  29. |---|---|---|
  30. | **The file, directly** (`keynote_lib.py`) | All reading (tables as displayed, formatting can be read too); rewriting text and notes; position and size; fill, outline, shape type (arrows etc.), shadow, alignment, font, line spacing, bullets (levels, turning a text box into a bulleted list), table cell padding, background color; showing or hiding the title and slide number; chart data, type, colors, legend, axis range, value labels and per-bar colors | Not needed |
  31. | **AppleScript** (`keynote_app.py`) | Rendering (images, PDF); adding, duplicating, deleting and moving slides and objects; creating tables, images and charts; writing table cells; importing PowerPoint files | Required |
  32. AppleScript cannot change things like fill colors or text alignment, while editing the file directly is risky for structural changes such as adding slides, so the skill combines the two.
  33. Direct edits give the edited object its own derived style, so other objects sharing the same theme style are not affected.
  34. Unknown fields are kept as Protobuf, and `.iwa` files that were not changed are written back byte for byte.
  35. ## Scripts
  36. | Script | Purpose |
  37. |---|---|
  38. | `key_text.py` | Prints the content as Markdown / JSON (titles, bullets, tables, chart data, image names, notes) |
  39. | `key_render.py` | Exports slides to PNG/JPEG/PDF; also makes thumbnail sheets and layout sheets. Renders `.keyx` files too (Keynote 16 or later) |
  40. | `key_build.py` | Builds a new deck from a JSON spec (from a theme, or using an existing deck as a template) |
  41. | `key_edit.py` | Applies text replacements and style / position changes directly to the `.key` (optionally to all slides at once) |
  42. | `key_merge.py` | Brings slides from other decks in, still editable (merging decks; the source files are not modified) |
  43. | `key_import.py` | Imports a `.pptx` as a Keynote document, restores PowerPoint-equivalent line spacing, and reports what was lost (charts, fonts) |
  44. | `key_check.py` | Structural check of an edited file (`--open` checks that Keynote really opens it; `--layout` also finds objects off the slide and overlapping text) |
  45. | `keynote_app.py` | Detects the installed Keynote apps, runs AppleScript, lists installed font names |
  46. | `keynote_lib.py` | The Python library underlying all of the above |
  47. See [`skills/keynote/SKILL.md`](skills/keynote/SKILL.md), the task guides in [`skills/keynote/references/`](skills/keynote/references/) and each script's `--help` for details.
  48. ## Installation
  49. Install it as a Claude Code plugin. In Claude Code:
  50. ```
  51. /plugin marketplace add ronin-gw/keynote-skill
  52. /plugin install keynote@keynote-skill
  53. ```
  54. Then install the Python dependencies (the plugin does not install them):
  55. ```bash
  56. pip install keynote-parser Pillow
  57. ```
  58. Update later with `/plugin marketplace update keynote-skill`.
  59. Rendering and structural changes need macOS with Keynote installed.
  60. ## macOS permissions
  61. The scripts drive Keynote from the command line with AppleScript, so macOS asks for consent the first time. The prompt names the app the commands run under — your terminal (Terminal, iTerm2, …) or Claude Code — not this skill.
  62. | Prompt / setting | Needed? | What it is used for |
  63. |---|---|---|
  64. | **Automation → Keynote** ("… wants access to control Keynote") | Required for rendering, building, structural edits and .pptx import | Opening decks, exporting slide images, adding slides and objects, saving. Reading a deck and direct edits (`key_text.py`, `key_edit.py`) do not use Keynote and need no permission |
  65. | **Automation → System Events** ("… wants access to control System Events") | Optional | Only `keynote_app.py info` and Keynote timeout errors use it, to see whether Keynote is showing a dialog |
  66. | **Accessibility** (macOS asks on first use) | Optional | Together with the System Events permission, lets the same check read the dialog's text and button names |
  67. - **Why the optional pair exists**: a dialog left open in Keynote (for example "… can't be opened") stalls every command that drives it, and without these permissions the scripts cannot tell you why. With them, `info` prints the dialog's text so you know what to dismiss.
  68. - **The check only reads.** It lists Keynote's dialog windows and their text. The scripts never click buttons, type keys, or read any other app's windows.
  69. - **Declining is safe.** Without the optional permissions everything else works; `info` prints one line, `dialogs not checked: no permission`, instead of the dialog text. That line is not an error.
  70. - **Not used at all**: Screen Recording, Full Disk Access, Contacts, Camera, Microphone. If something asks for those while you use this skill, it is not this skill.
  71. - **The app name in the prompt can look unfamiliar.** When the commands are run by Claude Code, macOS may show Claude Code's version number (for example `2.1.327`) instead of "Claude Code". That is still the app asking on this skill's behalf.
  72. - **If you declined a prompt**, macOS does not ask again: the scripts keep reporting `dialogs not checked` (or, for Keynote itself, fail with a "not authorized" error) until you switch the entry on under System Settings → Privacy & Security → Automation / Accessibility. Meanwhile you can still run `python3 <skill dir>/scripts/keynote_app.py info` from a terminal that has the permission to see a dialog.
  73. - To withdraw a permission, switch it off under System Settings → Privacy & Security → Automation (or Accessibility).
  74. ## Keynote versions
  75. - Keynote 15.x (Keynote Creator Studio, `com.apple.Keynote`) and 14.x or earlier (`com.apple.iWork.Keynote`) can be installed side by side as separate apps. Their names collide, so the scripts always address the app by bundle ID.
  76. - **Saving in 15.x silently upgrades the file format to 26.x, after which older Keynote versions can no longer open the deck.** For an existing deck, the scripts therefore pick the oldest installed Keynote that can open it (override with `--app 16` / `--app 14` or the `KEYNOTE_APP` environment variable). Direct edits never change the file format.
  77. - **A `.keyx` file is opened by Keynote 16 or later only.** For one, the scripts pick the oldest installed Keynote that is 16 or later, and refuse the file up front when there is none or when `--app` / `KEYNOTE_APP` names an older one.
  78. - Tested with Keynote 15.4 (format 26.4.0) and Keynote 13.2 (format 13.2.1) on macOS 27.2, plus reading decks created in 2018. Rendering `.keyx` files was checked with Keynote 16.0.
  79. - Decoding uses [keynote-parser](https://github.com/psobot/keynote-parser) (officially supporting up to 14.5). Files from 15.4 contain a few unknown fields; they have been confirmed to survive a round trip unchanged.
  80. ## Not supported
  81. Builds (object animations), hyperlinks, grouping, movies and audio, comments, applying layout (master) changes to existing slides, reading password-protected decks directly, and the Keynote '09 format.
  82. Reading the content of, creating and editing `.keyx` files is also out of scope (only rendering is supported); text hyperlinks, groups, movies and audio can be authored in `.keyx` with Apple's skill.
  83. ## Tests
  84. ```bash
  85. pytest tests # tests that read and write files
  86. KEYNOTE_TESTS=1 pytest tests # also run the tests that drive the Keynote app
  87. ```
  88. The sample decks used by the tests are not included in the repository (they contain Apple theme artwork).
  89. On the first run they are built automatically from `tests/fixtures/spec.json` with the installed Keynote and saved in `tests/fixtures/` (ignored by Git). Later runs do not need Keynote.
  90. - A deck is built for Keynote 15 or later and for 14.x or earlier. If only one of them is installed, the tests for the other are skipped.
  91. - Without Keynote, all tests that need a deck are skipped.
  92. ## Trademarks
  93. Keynote, macOS and AppleScript are trademarks of Apple Inc. PowerPoint is a trademark of Microsoft Corporation.
  94. This is an independent project and is not affiliated with, or endorsed by, Apple Inc.
  95. ## License
  96. [MIT](LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.