deck-edit

name	deck-edit
description	Use when editing existing slides in deck.md — rewriting body text, swapping layout, toggling freeze/skip/ignore, fixing citations, reordering. The slide's `key` is preserved through every edit. Anything that creates new content (a new deck from a template, or a new slide that needs a fresh key) goes through `deck-new`.

deck edit skill

Modifying slides that already exist. New decks and new slides (anything that mints a key) belong to deck-new; this skill stays inside the bounds of slides that are already there.

Principles

1. The key is immutable

• Never rewrite a slide's key field
• Body rewrite, layout swap, freeze/skip/ignore changes, reordering — none of them touch the key
• The key is the stable identifier used in commit messages and conversation history; renaming it breaks the trail
• The full convention is in the Slide key convention section below

2. Only layout / body / flags change

Editable fields inside the config object (deck v1.24+, md/md.go):

field	type	purpose
layout	string	Layout name change. Always confirm with deck ls-layouts deck.md first — never copy a layout name from another slide as a "known good" (the template may have been swapped underneath you).
freeze	bool	true protects the whole slide from changes
ignore	bool	true excludes the slide from generation entirely (drafts etc.)
skip	bool	true generates the slide but skips it during playback

key is off-limits (Principle 1). Unknown fields are silently dropped by json.Unmarshal. The JSON itself must remain syntactically valid; an invalid object is not parsed as config and falls back to being treated as a speaker note.

3. Verify the result via PDF render after a change

After a layout change, a substantial body rewrite, or a swapped citation slide, verify before reporting completion:

deck apply deck.md
deck export deck.md -o /tmp/verify.pdf
pdftoppm -png -r 100 -f <N> -l <N> /tmp/verify.pdf /tmp/check
# Read /tmp/check-N.png

If deck apply --watch deck.md is running in the background, apply is automatic; otherwise run deck apply explicitly first — deck export reflects the Slides-side state, so unapplied local edits will not appear in the PDF.

A pure typo fix may skip verification; any visible change must be verified.

Workflow

1. Pin down the target slide by key — if the user says "the slide titled X" or similar, resolve to a key via grep first. The key is the referent in every subsequent message and commit ("move a7b5 after c9d2", "swap the quote on 7f31")
2. Read deck.md (understand the slide's current state)
3. If layout is changing, run deck ls-layouts deck.md to confirm what is available (or read .deck-state.json) — never guess
4. Edit (the key is not touched)
5. deck apply deck.md (automatic if --watch is running; explicit otherwise)
6. PDF-verify per Principle 3 if anything visible changed
7. Commit after the edit. The commit message names the slide by key — e.g. "rewrite body of <key>", "switch <key> to <new layout>"

Common edit patterns

• Typo fix: edit body → apply. PDF verification optional.
• Body rewrite: edit body → apply → PDF verify
• Layout change: ls-layouts → update the "layout" value in the config object → apply → PDF verify
• Toggle freeze / skip / ignore: add or change the field in the config object → apply
• Reorder: move the whole slide block (config-object comment + body + trailing --- separator) → apply → PDF verify

Frontmatter

---
presentationID: <Google Slides ID>
title: '<title>'
breaks: true
---

• breaks: true makes Markdown line breaks render as <br>. This skill set assumes breaks is on everywhere.
• presentationID is required; commands that take a DECK_FILE positional argument resolve it from the frontmatter.

CLI commands (v1.24 series)

The positional argument is DECK_FILE; presentationID comes from the frontmatter by default. Override with -i <id>.

• deck doctor — environment diagnostic (checks credentials.json location, etc.)
• deck new deck.md --title "<title>" — create a new presentation
• deck new deck.md --base <id> --title "<title>" — clone an existing presentation as the template (older --from is DEPRECATED)
• deck ls — list presentations
• deck ls-layouts deck.md — list available layouts
• deck apply deck.md — apply the local md to Slides (-vv for verbose; useful for full resync when order has drifted)
• deck apply --watch deck.md — watch mode (at most one process at a time — a second concurrent watcher is the typical cause of broken slide order)
• deck apply -p <page> deck.md — apply only the specified page
• deck export deck.md -o out.pdf — render the current Slides state to PDF (does not read the local md; run after apply)
• deck open deck.md — open the presentation in a browser

There is no --force / --reset flag. deck apply -vv is the de facto full resync.

Error handling

• duplicate page key %q at pages %d and %d (v1.24+): two slides share the same key. The usual cause is a key-minting miss during a fresh insertion. Re-mint the newer slide; do not change an existing slide's key.
• index out of range: slide count mismatch. Reduce, or add one at a time.
• object not found: a referenced object does not exist.
  1. Try a re-apply first — often transient.
  2. If it persists, rebuild from a minimal working state.
• State feels wrong: run deck apply -vv deck.md for a full sync. There is no .deck-state.json in normal operation — the truth lives on the Slides side.
• Runaway watcher: pgrep -fl "deck apply --watch" → pkill -f "deck apply --watch" to stop all → restart at most one.
• credentials.json NOT FOUND (from deck doctor): stop and ask the user — do not attempt to proceed.
• ls-layouts failure: stop and investigate. Selecting layouts without the canonical list is forbidden.

Slide key convention

Every slide carries a key field in its page-configuration object.

• Format: 4-hex string (e.g. a7b5, c9d2). The CLI treats the value as opaque (any string works); this skill set standardizes on 4-hex.
• Immutable. Once written, a key is never rewritten — moving, deleting, relayouting, or otherwise editing a slide preserves its key. Keys are the stable identifiers used in commit messages and conversation history; renaming one breaks the trail.
• Duplicates fail at parse time in deck v1.24+ (duplicate page key %q at pages %d and %d). A collision discovered at apply time is a production failure, not a soft warning.
• Conversation protocol: refer to slides by key, not by title fragment, body fragment, or page number. User-side: "move a7b5 after c9d2", "delete 7f31", "freeze through 5a90". Agent-side confirmations use keys too: "moved a7b5 after c9d2". When the user names a slide ambiguously, resolve to a key via grep and confirm before acting.

deck apply policy

• deck apply deck.md runs automatically — no user approval needed. The Slides-side state change is reversible by deck.md revert + apply.
• Keep a single deck apply --watch deck.md running in the background per editing session. The watcher auto-applies on every file change, so explicit apply becomes unnecessary in steady state. Start it at session open, restart if it dies.
• Only one watcher at a time. A second concurrent watcher is the typical cause of broken slide order. Detect and stop runaways with pgrep -fl "deck apply --watch" → pkill -f "deck apply --watch", then restart at most one.
• git push is a separate rule — apply does not authorize push.

See also

• deck-new — new decks (0→1) and new slides (n→n+1, includes key minting)