mirror of
https://github.com/magnus919/agent-skills.git
synced 2026-09-18 23:16:38 +03:00
c49666e29a
* feat(skill): add documents family skill (PDF / Word / Excel / PowerPoint) One family skill for PDF, Word (.docx), Excel (.xlsx), and PowerPoint (.pptx) per the family-skill rule (epub precedent): shared workflow in SKILL.md (scope, content model, template, render, validate, deliver) with per-format load-on-demand references, generation templates per format, a stdlib validation script (--json, structural sanity + render check with graceful degradation), one fixture per format, a unittest suite, six output-quality eval cases spanning all four formats, a human README, the README.md index entry, and regenerated catalogs. Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com> * fix(skill): dispatch PDF renderer args per binary in documents validation The render check passed pdftoppm-only flags (-png/-r/-f/-l) to mutool and ghostscript, which reject them, so a machine with only mutool or gs would false-FAIL valid PDFs. Dispatch per-renderer argument sets (pdftoppm -png; mutool draw -o; gs -sDEVICE=png16m) and cover the dispatch with a unit test. Also: count PDF pages via the /Count page-tree fallback (page objects can hide in compressed ObjStm streams), drop the stale "unsupported input" exit-2 claim from the docstring, and stop labeling skipped files with a FAIL check. Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com> * style(skill): drop redundant local tempfile import in renderer dispatch test Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com> --------- Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
93 lines
3.6 KiB
Markdown
93 lines
3.6 KiB
Markdown
# PowerPoint (.pptx) — Generation & Validation Reference
|
|
|
|
> **Last Updated:** 2026-08-03
|
|
|
|
Load this reference when the target format is **PowerPoint** — generating a
|
|
.pptx deck, modifying one, or validating a presentation artifact. It
|
|
complements the shared workflow in `SKILL.md`; this file is the
|
|
PowerPoint-specific detail for steps 3-5 (template, render, validate).
|
|
|
|
## PPTX fundamentals
|
|
|
|
A .pptx file is an **OPC ZIP archive**:
|
|
|
|
- **`[Content_Types].xml`** — content types for presentation and slide parts.
|
|
- **`_rels/.rels`** — package relationships; points at `ppt/presentation.xml`.
|
|
- **`ppt/presentation.xml`** — the deck: `<p:sldIdLst>` lists slide IDs; the
|
|
relationships file `ppt/_rels/presentation.xml.rels` maps each `r:id` to a
|
|
slide part. Also carries slide size (`<p:sldSz cx cy/>`).
|
|
- **`ppt/slides/slideN.xml`** — each slide: `<p:cSld>` with `<p:spTree>`
|
|
(the shape tree). Text boxes are `<p:sp>` shapes whose `<p:txBody>` holds
|
|
`<a:p>` paragraphs with `<a:r>` runs and `<a:t>` text.
|
|
- **`ppt/notesSlides/notesSlideN.xml`** — speaker notes.
|
|
- **`ppt/media/`** — embedded images.
|
|
|
|
The validation script checks the ZIP container, `[Content_Types].xml`,
|
|
`ppt/presentation.xml`, at least one `ppt/slides/slideN.xml`, and their XML
|
|
well-formedness.
|
|
|
|
## Generation paths
|
|
|
|
### python-pptx (recommended)
|
|
|
|
`pip install python-pptx`, then build from the slide outline:
|
|
|
|
```python
|
|
from pptx import Presentation
|
|
prs = Presentation()
|
|
slide = prs.slides.add_slide(prs.slide_layouts[1]) # title + content
|
|
slide.shapes.title.text = "Q3 Results"
|
|
slide.placeholders[1].text = "Revenue up 12%\nMargins stable"
|
|
prs.save("deck.pptx")
|
|
```
|
|
|
|
Drive the content from the slide outline (title + bullets + notes per slide);
|
|
the layout choice is separate from the content.
|
|
|
|
### Raw OPC construction (small, dependency-free artifacts)
|
|
|
|
For tiny decks, write the OOXML package directly with stdlib `zipfile` + XML:
|
|
`[Content_Types].xml`, `_rels/.rels`, `ppt/presentation.xml`,
|
|
`ppt/_rels/presentation.xml.rels`, and `ppt/slides/slide1.xml`. This is what
|
|
the bundled fixture `fixtures/sample.pptx` does. Keep the
|
|
`xmlns:p="http://schemas.openxmlformats.org/presentationml/2006/main"`
|
|
namespace and remember that every slide ID in `sldIdLst` needs a matching
|
|
relationship.
|
|
|
|
## Validation specifics
|
|
|
|
```bash
|
|
python3 scripts/validate-documents.py --json deck.pptx
|
|
python3 scripts/validate-documents.py --render-check --json deck.pptx
|
|
```
|
|
|
|
Structural checks the script runs for PPTX:
|
|
|
|
- **ZIP container** — `PK..` magic; the file is a real archive.
|
|
- **Content types** — `[Content_Types].xml` present.
|
|
- **Presentation part** — `ppt/presentation.xml` present and well-formed XML.
|
|
- **Slides** — at least one `ppt/slides/slideN.xml` present.
|
|
- **Text content** — informational check for `<a:t>` text markers.
|
|
|
|
The render check converts the deck to PDF via LibreOffice and reports
|
|
`unavailable` when LibreOffice is not installed.
|
|
|
|
## Output-quality checklist for PowerPoint
|
|
|
|
Before delivery, verify:
|
|
|
|
- **Slide IDs resolve** — every `<p:sldId>` in `sldIdLst` maps through
|
|
`presentation.xml.rels` to a real slide part.
|
|
- **Text fits** — no text boxes overflowing their shapes; keep bullets short.
|
|
- **Images are embedded** — media parts exist in `ppt/media/` and are
|
|
referenced by relationship.
|
|
- **Notes present where required** — speaker notes are part of the deck for
|
|
presentation use.
|
|
- **Slide size is intentional** — `sldSz` matches the intended aspect ratio
|
|
(16:9 vs 4:3).
|
|
- **Reading order** — shapes in `spTree` appear in a sensible order for screen
|
|
readers and tabbing.
|
|
|
|
See [references/output-quality.md](output-quality.md) for the cross-format
|
|
version of this checklist.
|