mirror of https://github.com/magnus919/agent-skills.git synced 2026-09-12 12:06:29 +03:00

Files

T

c49666e29a feat(skill): add documents family skill (PDF / Word / Excel / PowerPoint) (#262 )

* 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>

2026-08-03 17:36:00 -04:00

3.6 KiB

Raw Permalink Blame History

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:

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

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 for the cross-format version of this checklist.

3.6 KiB Raw Permalink Blame History