日本語

Fill Image Slots on an Existing Deck

Working directory: the slide-forge root — ${CLAUDE_PLUGIN_ROOT} when running from an installed plugin, /path/to/slide-forge on a local clone.

Important

• Prefer the spec path when the deck is still being generated. If the deck comes from a slide-forge deck spec, add an aiImage figure with x/y/w/h omitted and regenerate — build_deck.py puts it in the slot. That keeps the spec the source of truth, which is the repo's standing rule (see slide-qa: fixes happen in the source, not the artifact). This skill is for decks that have no spec behind them, or for adding imagery to a deck that already exists and must keep its URL.
• This writes to a live deck. Take a version snapshot first and report the revision ID: .venv/bin/python scripts/snapshot_version.py <URL>
• Always --dry-run first and show the user which slides and frames will be filled, with the prompt each one will use, before generating anything.
• Slots that already hold a picture are never touched. Replacing an existing picture is out of scope — delete it by hand first if that is the intent.
• GEMINI_API_KEY is required and the image model has zero free-tier quota; the key must belong to a billing-enabled project (references/images.md).
• Image generation can be switched off for the whole toolkit (imageGeneration: false in config/settings.json). Check it before proposing this skill — .venv/bin/python scripts/settings.py --show. When it is off, fill_image_slots.py stops before reading the deck; either the user turns it on or the frames stay empty (references/settings.md).
• Verify with thumbnails afterwards. A clean API response cannot show a picture whose subject got cropped. Hand off to the slide-qa skill.

Quick Reference

How a frame is found

Same three sources as template registration (references/template-schema.md):

1. a PICTURE-family placeholder on the slide (PICTURE / CLIP_ART / DIAGRAM / MEDIA / OBJECT / SLIDE_IMAGE)
2. an empty image element on the slide — it renders as nothing, so it is a slot, not a decoration
3. otherwise the layout's imageSlots, largest frame first

Sources 1 and 2 are declarations — the template says a picture belongs there. The third kind of frame imageSlots can hold, one inferred from other slides placing pictures in the same spot, is excluded by default: on a real deck that inference matches the body area of ordinary content slides, and filling it everywhere would bury the deck in pictures. Measured on a 78-slide template, the default finds 0 fillable frames where the inference offers 39. Opt in per run with --include-inferred when you actually want that.

Frames on the slide itself win over the layout's, because a slide that carries its own placeholder is more specific than the layout it was made from. The survey lists layout frames largest-first; frames found on the slide come in the order the slide stores them, so read the --dry-run output rather than assuming an order when picking --slot.

A picture is layered over the frame, not poured into it. An empty PICTURE placeholder is not consumed — the image is created at the frame's coordinates and the placeholder stays underneath. It renders as nothing, but it is still there in the editor. The spec path (build_deck.py) behaves the same way.

Pass --template templates/<id>.json when the deck was generated from a registered template — its verified roles and palette are then used. Without it the deck is analyzed on the fly, so the skill works on any deck.

What gets drawn

The prompt defaults to the slide's title — its TITLE placeholder, or the topmost text if it has none — so a divider titled "Chapter 1: Rebuilding the Data Platform" asks for a picture about that. Body text is deliberately excluded: a slide's bullets read as "① Verify ② Distribute ③ Reflect" and make a poor drawing instruction. Override per run with --prompt. A slide with no text at all is skipped with a message rather than guessed at — pass --prompt for those.

The picture is generated for the frame's shape: the closest aspect ratio the model supports, plus a prompt instruction naming the edges and percentage the fill will crop, so the subject survives. It is then placed with fit="cover", exactly filling the frame. Details in references/images.md.

Generation is cached by (model, style, aspect, full prompt), so re-running does not redraw or re-bill; --force overrides.

Flow

1. Snapshot — snapshot_version.py <URL>; keep the revision ID for the report.
2. Survey — fill_image_slots.py <URL> --dry-run. Show the user the slide numbers, frames, and prompts. If everything is "already has a picture" or no frames exist, say so and stop — do not invent frames.
3. Confirm subjects. The auto-derived prompts come from slide text and are often literal. Offer to set --prompt per slide when the subject reads badly as a picture (long body text, numbers, product names).
4. Fill — run without --dry-run. Each placement prints the chosen aspect ratio and the composition note.
5. QA — invoke the slide-qa skill on the deck URL and check the pictures are not cropped through their subject and do not fight the layout's text.
6. Report — slides filled, the style used, the snapshot revision ID, and the deck URL.

Troubleshooting