Communitygithub.com

slidepatch

Restyle editable PowerPoint content using a reference slide or PPTX template while preserving text, numbers, embedded pictures and native chart data. Supports automatic template selection, layout, pagination and chart font/color matching, including covers, contents and section pages. Also converts standalone formulas into native PowerPoint equations using reviewed plans. Includes environment checks and native editing verification. Requires Windows and desktop Microsoft PowerPoint; chart verification also requires Excel.

What is slidepatch?

slidepatch is a Claude Code agent skill that restyle editable PowerPoint content using a reference slide or PPTX template while preserving text, numbers, embedded pictures and native chart data. Supports automatic template selection, layout, pagination and chart font/color matching, including covers, contents and section pages. Also converts standalone formulas into native PowerPoint equations using reviewed plans. Includes environment checks and native editing verification. Requires Windows and desktop Microsoft PowerPoint; chart verification also requires Excel.

Works with~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/ChenYueqi2024/SlidePatch/tree/HEAD/skills/slidepatch

Ask in your favorite AI

Open a new chat with this agent skill pre-loaded.

Documentation

What does slidepatch do?

Use the scripts bundled with this skill. Resolve their paths relative to this file, regardless of the host agent's working directory. The host needs local command execution and image viewing; this skill has no DSH-specific APIs or model API keys.

For a new installation, run python <skill>/scripts/slidepatch.py doctor (add --charts for chart migration or --equations for equation conversion). This checks dependencies and Office registration without opening applications. A ready result is not a substitute for native verification.

Native equation conversion

For requests to convert standalone formula text, pictures or MathType/OLE equations into native PowerPoint equations, use inspect-equations and convert-equations. Read references/equations.md for the plan, transcription and verification contract. This mode needs Pandoc in addition to Windows/PowerPoint; other modes do not require Pandoc. It preserves the deck's layout, page count and unspecified objects, uses no template, and does not re-convert existing native equations. Explicit whole-object LaTeX produces candidates; the Agent reviews and transcribes pictures and cached OLE previews without activating OLE or parsing MathType binaries. Leave unclear objects intact and report them. Template migration currently rejects native equations to prevent loss of mathematical structure; do not treat conversion as automatic support for migrating the resulting equations.

Whole-deck migration and pagination

For a request to migrate the entire presentation or allow pagination, prefer migrate. Read references/batch.md for the coverage contract and evidence format.

python <skill>/scripts/slidepatch.py migrate <source.pptx> --template <template.pptx> --output <new-output.pptx> --evidence <fresh-evidence-directory>

The engine visits every source slide in order. It identifies cover, contents, numbered section and ordinary content pages; prefers the matching template page type; and reuses native template backgrounds, graphics and layouts. A contents page can use a content-page style when there is no dedicated contents template. Review the classification and fallback in plan.json; this is geometric/typographic inference, not unrestricted image understanding.

Preserve template font family, size, weight and color. Native text measurements determine capacity. Keep complete groups together when possible; balance text volume among equally short whole-group page partitions. If a single group is too large, split at body-object, paragraph or sentence boundaries, preserving exact character slices. Oversized-group continuation pages align content at the top. Titles, group headings and footers repeat as explicit context; body slices must reconstruct the source exactly once and in order. Never rewrite source numbers or silently renumber a table of contents. A sentence that cannot fit without changing template typography causes the entire operation to fail.

This mode supports ordinary editable text, supported source text placeholders and embedded pictures/native charts with clear structure. The source-placeholder limits are in references/plan.md. For media pages, read references/media.md: images and their crops remain native, charts retain embedded workbooks, and associated captions stay with their assets during layout and pagination. Media pages use content templates. Non-text decorations, unsupported placeholders, groups, animations, external links and ambiguous structures remain unsupported. Failure on any page prevents publication of the whole output; never deliver a partial deck. Every generated page is reopened, rendered, checked against its template font/background, and actually edited and saved in a separate proof copy. Output is published only after all page, text and media checks pass.

Review every after-N.png, especially cover/section titles, contents-page fallback and pagination boundaries. Read the per-page checks and editability page list in report.json. Deliver the verified PPTX, preview and a short source-to-output page summary. State that repeated context is intentional when pages were split. Originals remain unchanged.

Same-file mode (plan v1)

  • Input is an existing .pptx; source and reference are different slides in that file with the same design and layout and hidden master graphics.
  • Source: ordinary shapes, lines and horizontal text boxes. Reference: these plus decorative pictures. No groups, placeholders, charts, SmartArt, animations, transitions, hyperlinks or rotated objects on either selected slide.
  • Every source text object maps to exactly one reference text object, and vice versa. The source's non-text shapes must be explicitly identified as decorations to replace. Stop for clarification if an object could contain meaningful visual evidence.
  • The operation replaces the source slide's local objects with native copies of the reference objects and fills them with exact source strings. It adopts the reference typography, including changes to emphasis; it does not promise preservation of the source's character formatting.
  • No content summarization, page splitting, automatic font shrinking, or image-to-editable reconstruction. If the selected slides don't fit these limits, explain the specific limitation instead of rebuilding the deck through an unrelated tool.

Separate-template mode (plan v2)

Use apply-template for a source slide and a template in separate PPTX files. This mode produces one new slide in the template's dimensions; it does not rewrite the source deck or include the other template slides. Choose v1 when the user requires preserving the source deck's other slides.

Inspect both files, including inherited layout/master graphics now listed under inheritance. View the actual previews and choose a content page rather than assuming slide 2 is a suitable template. Preserve branding and decorations. Explicitly classify every local template object as kept decoration or removed sample content; do not retain unrelated template photos as evidence for the source content.

Create one placement per source text object. A placement names an ordinary text-bearing template shape as a style donor and gives bounds in points. The same donor can serve multiple placements, so source and template text counts may differ. The engine duplicates native objects inside the template, preserving its layout/master and theme. Text comes directly from the source; plans contain no replacement strings. Font shrinking and content rewriting remain unsupported.

Source restrictions from v1 apply except that v2 also accepts the supported source text placeholders. Empty safe text slots are explicitly recorded as discarded; active inherited source text causes rejection rather than being silently omitted. Style donors must be ordinary unrotated horizontal text shapes, not placeholders/groups. Template layout/master decorations remain native, including inherited pictures and unused layout placeholders. Retained local decorations must have no text. Plans record which objects are removed; automatic planning can propose these decisions, while the Agent reviews their meaning.

Automatic layout (preferred for separate templates)

For a text-only source with a clear title and body text, including supported source text placeholders, first run:

python <skill>/scripts/slidepatch.py plan-template <source.pptx> --template <template.pptx> --source-slide 1 --out <fresh-planning-directory>

This generates a normal v2 plan.json without manually supplied target page, shape IDs or coordinates. selection.json records inferred source roles, candidate template pages, geometry-based decoration decisions, candidate layouts, fit measurements and rejection reasons. Status planned means a plan exists, not that a PPTX has passed final verification.

The planner uses font hierarchy and spatial proximity to associate headings and bodies; it does not use shape names or template page numbers. It requires a distinct top title, recognizes short-font bottom footers, and supports grouped rows/columns or unheaded paragraphs. It searches row, stacked, two-column and three-column layouts, using PowerPoint's native text bounds with the original template font sizes. Text wraps; no string rewriting or font shrinking occurs. Candidate boxes must not overlap one another or retained decorations. Full-page backgrounds and unused layout placeholders are excluded from obstacle checks.

Read selection.json, view source.png and the selected template-N.png, and check that the role associations and sample-picture removal make sense. Automatic picture classification uses geometry and nearby captions, not image understanding. Do not claim universal semantic matching. For an unambiguous result, proceed directly to apply-template with the generated plan and then review the rendered output. The user does not need to supply coordinates or approve routine choices already covered by their request.

If single-page planning rejects ambiguous roles, uncertain decorations, unsupported objects or over-capacity content, read the recorded reason. When pagination is authorized, use migrate. Otherwise inspect the actual objects before using a reviewed explicit v2 plan. Never silently omit content, shrink fonts or change the authorized page scope. Sources with pictures, non-text decorations, mixed/unclear hierarchy, charts or groups still need an explicit or unsupported-content workflow.

Run

Install requirements.txt into a Python 3.10+ virtual environment. Use that interpreter for every command. Desktop PowerPoint must be usable in the logged-in Windows session. First inspect:

python <skill>/scripts/slidepatch.py inspect <source.pptx> --out <fresh-inspection-directory>

Read inventory.json and view both relevant slide-N.png previews. Match content roles using the real objects and appearance. Never infer shape IDs from their order or reconstruct the protected text from memory.

For same-file mode, create a JSON plan using the schema in references/plan.md. For separate templates, prefer plan-template; use a hand-reviewed v2 plan when automatic inference is unsuitable. Copy hashes and IDs from current inventories. Preserve the user's intended scope. A clear authorized request with an unambiguous mapping can proceed; ask only when a material content ambiguity cannot be resolved from the files.

python <skill>/scripts/slidepatch.py apply <source.pptx> --plan <plan.json> --output <new-output.pptx> --evidence <fresh-evidence-directory>

For a separate template, inspect it as well, then use a v2 plan:

python <skill>/scripts/slidepatch.py inspect <template.pptx> --out <fresh-template-inspection>
python <skill>/scripts/slidepatch.py apply-template <source.pptx> --template <template.pptx> --plan <v2-plan.json> --output <new-output.pptx> --evidence <fresh-evidence-directory>

The engine stages the edited deck, reopens and renders it in PowerPoint, compares exact text objects and numbers, checks non-target slides, and tests a real text edit and shape move on a separate proof copy. It publishes the output only after these checks pass. It never calls PowerPoint Quit or closes unrelated presentations. Native copy/paste uses the system clipboard.

Template mode instead checks the one-slide result, both original hashes, all local source strings, saved native objects, and identical rendered decoration layers before/after. Existing decorative bleed is allowed; new content must fit. It uses native Duplicate without the clipboard. The PPTX can still contain unused template layouts, masters or media; this prototype does not sanitize hidden package assets.

Review and deliver

Read report.json; exit status and report must both indicate success. View before-<source>.png, before-<reference>.png and after-<source>.png. Check that the styling matches and there is no clipping, unintended overlap or incorrect reading order. Geometry checks do not replace visual review.

For template mode, view source-before.png, template-before.png, after-1.png, plus template-shell.png and output-shell.png. Check the new composition against the template's visual language; matching text strings alone is insufficient.

Deliver the new PPTX with a preview and a concise summary of the checks and scope. editability-proof.pptx deliberately contains an edit marker and is evidence, not the final deliverable. If any check fails, report the problem; never present a staged or proof file as the final deck. Choose fresh paths on retries, keeping failure evidence available.

Related Skills