docx-from-template

A portable Agent Skill for producing a new delivery document whose structure and presentation are controlled by a reference .docx, .xlsx, or .xlsm. It works with Claude Code, Codex, Cursor, and other tools that support SKILL.md skills.

Professional-first routing

The skill uses professional tooling when it is available:

• .docx routes to the Documents skill and its Template Following workflow for full-page rendering, OOXML-aware inspection, generation, and render/diff QA.
• .xlsx routes to the Spreadsheets skill for artifact-tool import with SpreadsheetFile.importXlsx, structural inspection, sheet rendering, formula inspection, and .xlsx export with SpreadsheetFile.exportXlsx.
• .xlsm inspection or authoring requires tooling that explicitly advertises macro-preserving support for that operation. Ordinary .xlsx support is not evidence of XLSM/VBA safety.

Professional runtimes and tool paths come from workspace dependencies. Professional mode performs no pip install and never relies on a system/global Python package installation. If an applicable professional skill fails, the workflow reports or fixes that blocker instead of silently downgrading. A professional skill's own documented degraded mode remains valid, but the QA mode and missing renderer are disclosed and no render fidelity is claimed.

This route can account for page and section geometry, styles, headers/footers, relationships and content controls in Word, plus workbook visibility, used ranges, merges, frozen panes, styles, formulas, validation, conditional formatting, names, tables, drawings, charts, images, and print settings in Excel.

Local fallback and fidelity limits

When the applicable professional skill is unavailable, the bundled local fallback performs bounded structural inspection. Fallback is not equivalent to the professional Documents or Spreadsheets route: it does not render templates, and it cannot establish professional visual fidelity. Its JSON reports visual_rendered=false, warnings, unresolved evidence, and parser limits for disclosure during delivery.

The fallback structurally inspects .docx, .xlsx, and .xlsm. Its normalized JSON includes the fail-closed fields fallback_authoring_eligible, unsupported_features, and preserve_only_parts. It may author only simple .docx and .xlsx working copies when eligibility is true, both lists are empty, a no-op round-trip preserves the exact package-part set and content apart from the normalized volatile core-properties modified timestamp, and no evidence is truncated or incomplete; it then re-inspects the result. Missing eligibility evidence is a blocking result. This path still lacks professional visual fidelity.

For .xlsm, fallback is read-only structural inspection. When no explicitly advertised macro-preserving capability is available, modification and generation are blocked because macro/VBA preservation is unverified. SpreadsheetFile.exportXlsx must not be used to produce XLSM, and the workflow never promises to preserve only the macro parts while rewriting the rest of the package.

The fallback limits a source file to 128 MiB, each uncompressed package member to 32 MiB, and total uncompressed package content to 128 MiB. Use the professional route for oversized templates.

Install the skill

Clone or copy this repository into the tool's skill directory, keeping the directory name docx-from-template:

# Claude Code
git clone https://github.com/jingua1234/docx-from-template.git ~/.claude/skills/docx-from-template

# Codex
git clone https://github.com/jingua1234/docx-from-template.git ~/.codex/skills/docx-from-template

# Cursor
git clone https://github.com/jingua1234/docx-from-template.git ~/.cursor/skills/docx-from-template

Windows PowerShell example:

git clone https://github.com/jingua1234/docx-from-template.git "$env:USERPROFILE\.codex\skills\docx-from-template"

Copy SKILL.md, reference.md, and scripts/ together if you do not clone the repository.

Use the skill

Attach a template and ask for a new document, for example:

Use @delivery-template.docx as the reference template and create the current project's deployment document 按照格式.

The agent records template evidence, sources facts from the repository, edits a working copy without overwriting the reference, and reports the output path, deviations, unresolved items, and QA mode.

Inspect with the local fallback

Use the canonical CLI for manual structural inspection:

python scripts/inspect_template.py path/to/template.docx
python scripts/inspect_template.py path/to/template.xlsx --json-out path/to/inspection.json

From an installed skill, resolve the directory containing SKILL.md and invoke the script by its absolute path. Quote the skill, template, and output paths; SKILL.md includes POSIX and PowerShell examples.

--json-out writes the same normalized JSON printed to stdout. scripts/inspect_docx.py is retained as a legacy CLI and delegates to the canonical inspector.

Optional fallback dependencies

The professional route uses workspace dependencies and requires no pip install. Only the local fallback may require these optional packages:

python -m pip install python-docx openpyxl

The inspector reports install guidance when the dependency for the selected format is missing; it does not install packages automatically.

Repository contents

• SKILL.md — portable routing, evidence, generation, and QA instructions.
• reference.md — repository evidence guidance for common delivery documents.
• scripts/inspect_template.py — canonical local fallback inspector.
• scripts/inspect_docx.py — legacy compatibility entry point.

License

MIT