DocCraft

---

name: doccraft

description: Create complete, source-grounded professional documents from existing materials, outlines, or templates, then generate, edit, review, or redline the final .docx files. Use when Codex needs to turn PDFs, DOCX, TXT, Markdown, or mixed project sources into proposals, technical方案, implementation plans, construction schemes, reports,申报材料, and other formal long-form deliverables with structured drafting, Word formatting, and review-ready document workflows.

---

# DocCraft

Overview

Use this skill in two layers:

1. Build grounded text from source materials and a target framework.

2. If needed, create or revise the final `.docx` deliverable.

Keep Markdown or plain text as the working source of truth until the wording and structure are stable. Move into DOCX creation, formatting, tracked changes, or comments only after the content is sufficiently mature.

This skill vendors the DOCX capability locally. Do not assume a separate `$docx` skill is installed.

Some upload targets reject bundled OOXML schema files such as `.xsd`. When preparing a publishable package, use the packaged upload-safe variant from this skill. That variant keeps document generation and editing workflows, but omits the strict schema-validation bundle.

When the final deliverable is a Word document, always determine the format authority before finalization:

1. User-provided template or existing target document.

2. Explicit written formatting requirements from the user.

3. An accepted sample deliverable in the same domain.

4. The default format profile in this skill.

Workflow Decision Tree

A. Build a new document from existing materials

Use the source-grounded text workflow:

1. Normalize the task inputs.

2. Build a source manifest.

3. Create section briefs from the target outline.

4. Draft section files.

5. Run document-level consistency review.

6. Assemble the final Markdown or text output.

B. Read, create, or edit a Word document

Use the DOCX workflows in this skill:

1. Read existing `.docx` content with `pandoc` when text extraction is enough.

2. Create a new `.docx` from scratch only after fully reading [docx-js.md](docx-js.md).

3. Edit or redline existing `.docx` files only after fully reading [ooxml.md](ooxml.md).

4. Default to tracked changes or comments for government, legal, academic, commercial, or third-party documents.

C. Do both

Split the work into phases:

1. Draft and stabilize text first.

2. Freeze the source-backed wording.

3. Move into `.docx` generation or `.docx` editing.

Do not mix heavy content generation and low-level OOXML editing in the same pass unless the task is trivial.

Source-Grounded Text Workflow

1. Normalize the inputs

Confirm these four inputs before drafting:

If any input is missing, infer the minimum safe default and state the assumption in the working notes, not in the final deliverable.

If the output contract includes `.docx`, also determine the format authority early. Read [references/word-format-profile.md](references/word-format-profile.md) and use [scripts/init_format_profile.py](scripts/init_format_profile.py) when a format profile needs to be captured or confirmed.

If the task is to produce a formal, complete Word deliverable, capture a delivery brief before drafting. Read [references/word-delivery-brief.md](references/word-delivery-brief.md) and use [scripts/init_delivery_brief.py](scripts/init_delivery_brief.py) to record what the user must specify and what still needs confirmation.

2. Build a source manifest

Before writing, create a manifest of the available materials. Read [references/source-manifest.md](references/source-manifest.md) when the corpus has more than a few files.

Use [scripts/build_manifest.py](scripts/build_manifest.py) to generate a first-pass inventory. Then enrich or trim it manually as needed.

The manifest should separate:

3. Create section briefs

Do not draft directly from a large corpus into the final chapters. First create a section brief for each target section.

Read [references/section-briefs.md](references/section-briefs.md) when building the planning layer. Use [scripts/plan_sections.py](scripts/plan_sections.py) to bootstrap the outline into brief stubs.

Each section brief should contain at least:

For large projects, section briefs are the shared contract between multiple agents.

4. Draft sections

Read [references/drafting-rules.md](references/drafting-rules.md) before drafting.

Draft against the section brief, not against the whole corpus. This keeps the writing grounded and reduces repetition.

Rules:

5. Run consistency review

Read [references/consistency-review.md](references/consistency-review.md) before merging the full document.

Run a full-pass review for:

6. Assemble the output

Use [scripts/assemble_markdown.py](scripts/assemble_markdown.py) to merge ordered chapter files into a single Markdown draft when needed.

Keep a clear distinction between:

Default Execution Pattern

Single-agent mode

Default to a single agent when:

Multi-agent mode

Use multiple agents only when:

In multi-agent mode, create these shared artifacts before splitting work:

1. Source manifest.

2. Section brief pack.

3. Glossary or terminology list if naming is fragile.

4. Shared writing rules.

Do not let agents improvise different naming systems, evidence rules, or section boundaries.

DOCX Workflows

Read or analyze `.docx`

If only the text is needed, convert the file with:

pandoc --track-changes=all path-to-file.docx -o output.md

If structure, comments, media, or tracked changes matter, unpack the OOXML package and inspect the XML.

Create a new `.docx`

Before writing any code, fully read [docx-js.md](docx-js.md) without truncation.

Use the bundled `docx` JavaScript workflow when:

Before final DOCX generation, lock the format profile. If no authoritative template exists, use the default profile in [references/word-format-profile.md](references/word-format-profile.md).

Before final DOCX generation, also resolve the delivery brief items that affect document completeness, review mode, and output packaging.

Before final DOCX generation, run [scripts/resolve_word_job.py](scripts/resolve_word_job.py) or follow [references/word-assembly-plan.md](references/word-assembly-plan.md) to determine whether the Word job is actually ready for delivery, which package components will be generated, and which blockers remain.

When the job is ready, generate the file with [scripts/generate_docx_from_markdown.cjs](scripts/generate_docx_from_markdown.cjs). Feed it the merged Markdown body, the delivery brief JSON, and the format profile JSON.

Edit an existing `.docx`

Before editing, fully read [ooxml.md](ooxml.md) without truncation.

Use the bundled OOXML workflow when:

Redline and review mode

Default to tracked changes or comments when editing:

Use the bundled local resources in this skill:

If the upload-safe package excluded the OOXML `.xsd` schema set, treat strict schema validation as unavailable and continue with unpack, edit, and repack workflows only.

Format confirmation rule

Do not ask the user to confirm formatting too early if the task is still in the text-drafting phase. Draft the content first unless formatting decisions would change the structure materially.

Ask the user to confirm the format before final Word delivery when any of these are true:

Do not ask for confirmation when:

When confirmation is needed, present the resolved format profile, not an open-ended question. Default to the profile in [references/word-format-profile.md](references/word-format-profile.md) if the user does not override it.

Delivery-brief rule

For a complete Word deliverable, separate user inputs into two buckets.

The user must specify these before drafting:

The user must confirm these before final Word delivery:

If these items are unclear, proceed with text drafting only when safe defaults will not invalidate the content. Do not finalize the Word deliverable until the unresolved delivery-brief items are closed.

Word assembly rule

Treat final Word generation as a gated assembly step, not just a file export.

Before assembly, resolve:

If the job is not ready, stop at Markdown or internal DOCX draft output and surface the blockers explicitly.

Resource Map

Non-Negotiable Rules