mirror of
https://github.com/magnus919/agent-skills.git
synced 2026-09-19 23:46:28 +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>
94 lines
3.7 KiB
Markdown
94 lines
3.7 KiB
Markdown
# 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:
|
|
|
|
```python
|
|
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
|
|
|
|
```bash
|
|
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](output-quality.md) for the cross-format
|
|
version of this checklist.
|