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.7 KiB

Raw Permalink Blame History

Word (.docx) — Generation & Validation Reference

Last Updated: 2026-08-03

Load this reference when the target format is Word — generating an editable .docx, modifying one, or validating a Word artifact. It complements the shared workflow in SKILL.md; this file is the Word-specific detail for steps 3-5 (template, render, validate).

DOCX fundamentals

A .docx file is an OPC (Open Packaging Conventions) ZIP archive:

[Content_Types].xml — declares the content type of every part.
_rels/.rels — package relationships; points at the main document part.
word/document.xml — the document body: w:p (paragraphs) containing w:r (runs) containing w:t (text); w:tbl for tables; w:sectPr for section properties.
word/styles.xml — named styles (w:style with w:styleId); the document references them with w:pStyle/w:rStyle.
word/media/ — embedded images referenced via relationships in word/_rels/document.xml.rels.
word/header*.xml / word/footer*.xml — headers and footers.
docProps/core.xml — metadata (title, author, dates).

Content lives in word/document.xml; everything else supports it. The validation script checks the ZIP container, [Content_Types].xml, the word/document.xml part, and its XML well-formedness.

Generation paths

python-docx (recommended for prose documents)

pip install python-docx, then build from the content model:

from docx import Document
doc = Document()
doc.add_heading(title, level=0)
for heading, body in sections:
    doc.add_heading(heading, level=1)
    doc.add_paragraph(body)
doc.save("report.docx")

Use styles (add_heading applies built-in heading styles) rather than manual formatting so the document stays navigable and re-styleable.

Pandoc (markdown → docx)

pandoc report.md -o report.docx produces clean, style-based output and is ideal when the content model is markdown. Use a reference doc (--reference-doc) to control styles.

Raw OPC construction (small, dependency-free artifacts)

For tiny or highly controlled documents, write the OOXML package directly with stdlib zipfile + XML: [Content_Types].xml, _rels/.rels, word/document.xml, and optional word/styles.xml. This is what the bundled fixture fixtures/sample.docx does. Keep the XML namespaced correctly (xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main").

Validation specifics

python3 scripts/validate-documents.py --json brief.docx
python3 scripts/validate-documents.py --render-check --json brief.docx

Structural checks the script runs for DOCX:

ZIP container — PK.. magic; the file is a real archive.
Content types — [Content_Types].xml present.
Main part — word/document.xml present and well-formed XML.
Text content — informational check for w:t text markers.

The render check converts the file to PDF via LibreOffice (--headless --convert-to pdf) and reports unavailable when LibreOffice is not installed.

Output-quality checklist for Word

Before delivery, verify:

Styles, not ad-hoc formatting — headings use heading styles so the navigation pane and TOC work.
Tables are real tables — w:tbl structure, not tab-separated text.
Images are embedded — media parts exist and are referenced, not hot-linked.
No unresolved fields — update or remove stale TOC/field placeholders.
Spellable, openable text — text is in w:t runs, not encoded oddly.
Header/footer present when required — page numbers, document title.

See references/output-quality.md for the cross-format version of this checklist.

3.7 KiB Raw Permalink Blame History