Using power-pptx with Coding Agents

power-pptx was designed for programmatic generation — and that includes code written by AI coding agents. The package ships its own Claude Code skill: a curated cheat sheet, sixteen focused reference docs, and an explicit anti-patterns list of the mistakes LLMs most commonly make when generating decks.

Install the bundled skill

The skill files live inside the pip package. Install them into your local Claude Code skills directory with:

pip install power-pptx
python -m power_pptx.skill install

This copies SKILL.md and the references/ directory into~/.claude/skills/power-pptx/. Claude Code (and any compatible Claude Agent SDK harness) picks it up automatically the next time it starts.

Skill commands

# Print the skill source path inside the installed package
python -m power_pptx.skill path

# Install into a custom directory
python -m power_pptx.skill install /path/to/skills/power-pptx

# Refuse to overwrite an existing install
python -m power_pptx.skill install --no-overwrite

What your agent gets

Prompting patterns that work

Agents produce the best decks when you:

• Ask for the space-aware workflow explicitly — "use fit_text or TEXT_TO_FIT_SHAPE for runtime text, then slide.tidy() before save".
• Give content, not coordinates — "a four-step pipeline from Extract to Output" maps cleanly onto horizontal_pipeline(slide, bb, steps=[…]); pixel-level instructions fight the layout primitives.
• Request an audit — "end with a call to audit(prs).markdown() so I can see what the linter found".
• Pin the version in generated requirements files:power-pptx>=2.8.0 is the minimum that ships the BBox / add_text / add_arrow / diagrams / audit surface.

House rules the skill teaches

1. Always from power_pptx import Presentation — never another import path.
2. Default to space-aware patterns for any runtime-supplied text.
3. Reads should not mutate — unset effect properties return None; assign None to clear.
4. Use Inches / Pt / Cm helpers, never raw EMU integers.
5. Use Grid / Stack for placement when a slide has more than two shapes.
6. Prefer slide recipes for whole-slide layouts; drop to add_shape only when recipes don't fit.
7. Save once at the end — build in memory, then prs.save(...).

Anti-patterns the skill warns about

• Comparing wrapper objects with is — tf.paragraphsreturns fresh objects every call. Use set_text_preserving_format(new_text) for replace-text-keep-formatting.
• Expecting arrowheads from add_connector — it draws a bare line. Use slide.shapes.add_arrow(start, end, head="triangle").
• Sizing a diagram to a broken picture's bbox — usepicture.enclosing_container() then picture.replace_with(builder).
• Mutating shapes while iterating — process in reverse index order or capture shapes before iterating.
• Importing enums for every styling call — use hex strings and short-name kwargs: add_text(bb, text="…", color="#0B5CFF", align="center").
• Raw EMU integers — BBox.from_inches(1, 2, 8, 4),Inches(1), Pt(12).
• lint → auto_fix → lint loops — slide.tidy() is the one-call wrapper.

JSON spec authoring for agents

When an agent already has a content plan as JSON, from_spec turns it straight into a deck — with an optional built-in lint gate:

from power_pptx.compose import from_spec

prs = from_spec({
    "slides": [
        {"layout": "title", "title": "Q4 Review", "subtitle": "Engineering"},
        {"layout": "bullets", "title": "Highlights",
         "bullets": ["Shipped v2.10", "Lint pass clean", "Zero overflow"]},
    ],
    "lint": "raise",
})
prs.save("q4.pptx")

See Compose & Templates for the full spec schema, and Lint & Audit for the lint gate.