Agent Skills

1---
2name: "doc"
3description: "Use when the task involves reading, creating, or editing `.docx` documents, especially when formatting or layout fidelity matters; prefer `python-docx` plus the bundled `scripts/render_docx.py` for visual checks."
4---
5 
6 
7# DOCX Skill
8 
9## When to use
10- Read or review DOCX content where layout matters (tables, diagrams, pagination).
11- Create or edit DOCX files with professional formatting.
12- Validate visual layout before delivery.
13 
14## Workflow
151. Prefer visual review (layout, tables, diagrams).
16   - If `soffice` and `pdftoppm` are available, convert DOCX -> PDF -> PNGs.
17   - Or use `scripts/render_docx.py` (requires `pdf2image` and Poppler).
18   - If these tools are missing, install them or ask the user to review rendered pages locally.
192. Use `python-docx` for edits and structured creation (headings, styles, tables, lists).
203. After each meaningful change, re-render and inspect the pages.
214. If visual review is not possible, extract text with `python-docx` as a fallback and call out layout risk.
225. Keep intermediate outputs organized and clean up after final approval.
23 
24## Temp and output conventions
25- Use `tmp/docs/` for intermediate files; delete when done.
26- Write final artifacts under `output/doc/` when working in this repo.
27- Keep filenames stable and descriptive.
28 
29## Dependencies (install if missing)
30Prefer `uv` for dependency management.
31 
32Python packages:
33```
34uv pip install python-docx pdf2image
35```
36If `uv` is unavailable:
37```
38python3 -m pip install python-docx pdf2image
39```
40System tools (for rendering):
41```
42# macOS (Homebrew)
43brew install libreoffice poppler
44 
45# Ubuntu/Debian
46sudo apt-get install -y libreoffice poppler-utils
47```
48 
49If installation isn't possible in this environment, tell the user which dependency is missing and how to install it locally.
50 
51## Environment
52No required environment variables.
53 
54## Rendering commands
55DOCX -> PDF:
56```
57soffice -env:UserInstallation=file:///tmp/lo_profile_$$ --headless --convert-to pdf --outdir $OUTDIR $INPUT_DOCX
58```
59 
60PDF -> PNGs:
61```
62pdftoppm -png $OUTDIR/$BASENAME.pdf $OUTDIR/$BASENAME
63```
64 
65Bundled helper:
66```
67python3 scripts/render_docx.py /path/to/file.docx --output_dir /tmp/docx_pages
68```
69 
70## Quality expectations
71- Deliver a client-ready document: consistent typography, spacing, margins, and clear hierarchy.
72- Avoid formatting defects: clipped/overlapping text, broken tables, unreadable characters, or default-template styling.
73- Charts, tables, and visuals must be legible in rendered pages with correct alignment.
74- Use ASCII hyphens only. Avoid U+2011 (non-breaking hyphen) and other Unicode dashes.
75- Citations and references must be human-readable; never leave tool tokens or placeholder strings.
76 
77## Final checks
78- Re-render and inspect every page at 100% zoom before final delivery.
79- Fix any spacing, alignment, or pagination issues and repeat the render loop.
80- Confirm there are no leftovers (temp files, duplicate renders) unless the user asks to keep them.
81