A reusable agent skill for producing a full set of software-delivery documents from a requirements spec, a folder of Word templates, and a codebase — with Visio-editable diagrams.
English | 简体中文
Engineering-delivery projects (defense, gov-tech, enterprise software) ship dozens of Word documents: task books, quality plans, configuration plans, SRS, design specs, review records, inspection checklists. Each comes as a .doc/.docx template that must be filled in place — cover tables, headers, revision history, tables-of-contents and section layouts preserved — and each needs diagrams that the customer may later edit in Visio.
Doing this by hand is slow and error-prone: identifiers drift, dates contradict the milestone plan, the project name leaks into the system-name field, and half the diagrams end up as unstyled screenshots.
This skill packages the whole pipeline — reconnaissance, template filling, diagram generation, and consistency checking — into scripts plus procedural knowledge that any SKILL.md-compatible agent can follow.
- In-place template filling — preserves styles, cover tables, headers/footers, TOC fields and section properties. No "rebuild from scratch" look.
- Dual-format diagrams — every figure is emitted as PNG (for embedding) and
.vsdx(editable in Visio), covering use case, class, activity, sequence, deployment, package, and ER diagrams. - Deterministic output — project/system names, document identifiers (
RK-XXXX-015), versions and milestone-derived dates are normalized across the whole document set and verified by a scan. - Form-document toolkit — label-based cell filling, vertical-merge handling, checkbox marking (
☑ / ☐), reviewer rosters, revision-record tables. - Cross-platform conversion —
.doc ↔ .docxvia Microsoft Word COM on Windows, or LibreOffice (soffice) on macOS/Linux. - Battle-tested — built while producing a real 32-document delivery package; every pitfall found along the way is documented in
references/pitfalls.md.
| Harness | Mechanism | Install target |
|---|---|---|
| WorkBuddy | native skills | ~/.workbuddy/skills/delivery-doc-writer/ |
| Claude Code | Agent Skills | ~/.claude/skills/delivery-doc-writer/ |
| Codex CLI | skills dir + custom prompt | ~/.codex/skills/… + ~/.codex/prompts/delivery-doc-writer.md |
| opencode | skills dir + command | ~/.config/opencode/skills/… + ~/.config/opencode/command/delivery-doc-writer.md |
| DeepSeek Harness / others | self-contained bundle prompt | dist/delivery-doc-writer.bundle.md |
| Any SKILL.md agent | copy the folder | wherever the harness loads skills |
git clone https://github.com/hanbingmomo/delivery-doc-writer.git
cd delivery-doc-writer
python install.py --list # show resolved paths
python install.py --target claude # Claude Code (user scope)
python install.py --target codex # Codex CLI
python install.py --target opencode # opencode
python install.py --target deepseek # bundle prompt for prompt-only harnesses
python install.py --target all # everythingUse --project to install into the current repository (.claude/skills, .codex/skills, …), --dest to override the location, and --dry-run to preview.
# Claude Code
mkdir -p ~/.claude/skills && cp -r delivery-doc-writer ~/.claude/skills/
# WorkBuddy
mkdir -p ~/.workbuddy/skills && cp -r delivery-doc-writer ~/.workbuddy/skills/For harnesses without a skills directory, generate the single-file prompt and paste it into the system prompt / custom-instruction slot:
python install.py --target generic --dest ./dist
# → ./dist/delivery-doc-writer.bundle.mdpip install python-docx Pillow openpyxl xlrd- Windows: Microsoft Word recommended (Word COM drives
.docconversion and field refresh). LibreOffice works as a fallback. - macOS / Linux: LibreOffice (
sofficeonPATH) for.docconversion. Native.docxwork needs no office suite.
Drop this into a conversation with your agent:
Here is a delivery directory of Word templates, a requirements spec, and the codebase at
./server. Fill in every document, generate the use-case/class/activity/sequence/deployment diagrams as Visio files kept in the document folder, and keep all dates consistent with the milestone sheet in the document list.
The agent will then:
- Back up and recon — copy the template tree to
*-bak/, dump every template's structure (headings, tables, headers), inspect file signatures (.docfiles often carry a.docxextension). - Build a toolkit — reuse
scripts/doc_kit.py, overridePROJmetadata for the project. - Generate in stages — form documents via label/table filling, narrative documents via cover-preserving rebuild, one build script per stage.
- Draw diagrams —
scripts/diagram_lib.pyemits PNG +.vsdx; sources stay inVisio图源/next to the documents. - Verify — scan every file for stale names, placeholder text, wrong versions and out-of-range dates; fix and re-run until clean.
delivery-doc-writer/
├── SKILL.md # skill entry: triggers, 6-stage workflow, tool table
├── install.py # multi-harness installer / bundle generator
├── references/
│ ├── workflow.md # form vs. narrative docs, diagrams, traceability, script layout
│ └── pitfalls.md # 12 hard-won lessons (OLE2, COM zombies, vMerge, headers, dates…)
└── scripts/
├── doc_kit.py # core: replace, cover/table fill, rebuild, portable .doc conversion
├── diagram_lib.py # Diagram class → PNG + VSDX
├── convert_doc.py # batch .doc ↔ .docx (Word COM or LibreOffice)
├── dump_struct.py # template structure dump for reconnaissance
├── make_req_diagrams.py # 6 requirements-stage diagram examples
└── make_design_diagrams.py # 8 design-stage diagram examples
import sys; sys.path.insert(0, 'delivery-doc-writer/scripts')
import doc_kit
doc_kit.PROJ.update({'project': 'My Project', 'name': 'My Subsystem',
'code': 'XCSY2606008C', 'prefix': 'RK-XCSY2606008C-'})
from docx import Document
d = Document('templates/15-software-requirements-spec.docx')
doc_kit.fill_cover_header_table(d, 0) # 文件编号 / 版本 / 密级
doc_kit.set_by_label(d, '评审结论', '通过') # label-based cell fill
doc_kit.mark_choices(d) # "是 否" → "☑是 ☐否"
doc_kit.save_docx(d, 'out/15-software-requirements-spec.docx')from diagram_lib import Diagram
d = Diagram(11, 8.5) # inches
d.node(2.0, 6.5, 2.6, 0.9, 'Dashboard UI', kind='module')
d.node(6.0, 6.5, 2.6, 0.9, 'API Gateway', kind='usecase')
d.edge([(3.3, 6.5), (4.7, 6.5)], text='HTTPS')
d.render_png('fig1.png', scale=200) # embed in Word
d.render_vsdx('fig1.vsdx') # editable in Visio- Templates are read from a backup tree only. Writing results next to the templates causes compounding edits on the second run — the single most expensive bug encountered.
- File signatures beat extensions.
d0cf11e0= legacy OLE2.doc,504b0304=.docxZIP.python-docxrefuses OLE2. - Vertical merges (
w:vMerge) return duplicated cell references; unmerge before row-wise filling. - Header identifiers must be replaced through a dedicated header/footer pass, otherwise a body replacement for
项目编号：silently rewrites the document number in the header. - Dates live in the milestone sheet, not in prose. Convert Excel serial numbers with the workbook's date mode, then verify every rendered date falls inside the milestone window.
Full details: references/pitfalls.md.
Does it work without Microsoft Word?
Yes for .docx. .doc conversion needs Word (Windows) or LibreOffice (all platforms). Writing .doc output itself requires one of them.
Are the diagram scripts specific to one project?
make_req_diagrams.py and make_design_diagrams.py are worked examples with real content. Copy them as a starting point and replace the nodes/edges — the Diagram API and layout heuristics are generic.
Where do the .vsdx files come from?
diagram_lib writes VSDX from a template by substituting shape XML — no Visio installation required to generate, only to edit.
Can it handle Chinese/Japanese/Korean text?
Yes. The renderer uses a CJK-capable font stack; specify a font via Diagram(font=...) if your environment lacks the default.
Issues and PRs welcome. If you hit a template quirk not covered in references/pitfalls.md, a short reproducible note (template shape, symptom, fix) is the most valuable contribution.