word-documents
Use when creating, reading, or editing Word documents (.docx). Covers document generation with styles and structure, extracting content, find-and-replace, tracked changes, and templates. Trigger on "generate a word document", "find and replace in this docx", "fill this word templ
Install
npx skills add https://github.com/nimadorostkar/Claude-Skills-collection/tree/main/skills/documents/word-documents
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install nimadorostkar-claude-skills-collection@llmmart
git clone https://github.com/nimadorostkar/Claude-Skills-collection.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole nimadorostkar/claude-skills-collection collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
Word Documents
Purpose
Produce and manipulate .docx files programmatically, with real styles and structure rather than a wall of manually formatted paragraphs.
When to Use
- Generating a report, memo, letter, or contract as a Word document.
- Extracting text, tables, or comments from an existing
.docx. - Performing find-and-replace across a document while preserving formatting.
- Filling a template with data.
- Working with tracked changes or comments.
Capabilities
- Document generation with headings, tables, images, headers, and footers.
- Style application and modification.
- Content extraction, including tables and embedded objects.
- Find-and-replace preserving runs and formatting.
- Template filling.
- Tracked changes and comments.
Inputs
- The content and its structure.
- A template or style reference, if the output must match a house style.
- The source document, when reading or editing.
Outputs
- A valid
.docxwith a proper style hierarchy. - Extracted content in a structured form.
- An edited document that preserves the formatting it should preserve.
Workflow
- Use styles, never direct formatting — A heading is
Heading 1, not 18pt bold. Styles produce a navigable document, a working table of contents, and a document that can be restyled in one operation. - Start from a template when the house style matters — Load the organization's
.dotxor a reference.docxand write into its styles rather than recreating them. - Structure before content — Headings, then the body. The outline is what makes a long document usable.
- Preserve formatting when editing — A naive find-and-replace on the XML destroys runs. Replace within runs, and handle text split across runs.
- Verify the output — Open it. A
.docxthat a library writes without error can still be malformed in ways Word will complain about.
Best Practices
- Direct formatting (bold, a font size, a colour applied by hand) makes a document unmaintainable. Every visual property should come from a style.
- Text in Word is stored in runs, and a single sentence is frequently split across several. A replace that only handles single-run text will silently miss matches where formatting changes mid-word.
- Tables need a table style, or they render with no borders and are unreadable when printed.
- Images need explicit dimensions. Without them, Word inserts at native resolution, which is usually enormous.
- A table of contents field must be marked for update, and Word will prompt the user on open. This is expected behavior, not a bug.
- For a document that will be edited by humans, keep the structure simple. Deeply nested tables and text boxes are fragile.
Examples
Generating a structured document:
from docx import Document
from docx.shared import Pt, Inches
from docx.enum.text import WD_ALIGN_PARAGRAPH
# Start from the house template so styles already exist and match.
doc = Document("templates/report-template.docx")
doc.add_heading("Quarterly Operations Review", level=0) # Title style
p = doc.add_paragraph()
p.alignment = WD_ALIGN_PARAGRAPH.CENTER
run = p.add_run("Q2 2026")
run.italic = True
doc.add_heading("Summary", level=1)
doc.add_paragraph(
"Availability met the 99.9% target in each month of the quarter. "
"Two incidents exceeded the 30-minute recovery objective; both are covered below."
)
doc.add_heading("Incidents", level=1)
table = doc.add_table(rows=1, cols=4)
table.style = "Light Grid Accent 1" # a real table style, not hand-drawn borders
for cell, heading in zip(table.rows[0].cells, ["Date", "Duration", "Impact", "Cause"]):
cell.paragraphs[0].add_run(heading).bold = True
for incident in incidents:
row = table.add_row().cells
row[0].text = incident.date.isoformat()
row[1].text = f"{incident.minutes} min"
row[2].text = incident.impact
row[3].text = incident.cause
doc.add_page_break()
doc.save("output/q2-review.docx")
Find-and-replace that survives split runs:
def replace_text(paragraph, old: str, new: str) -> None:
"""Word splits text across runs at formatting boundaries. A naive
run-by-run replace misses any match that spans a boundary — which is
most of them, in a real document."""
full_text = "".join(run.text for run in paragraph.runs)
if old not in full_text:
return
replaced = full_text.replace(old, new)
# Write the result into the first run and clear the rest, preserving the
# first run's formatting for the whole paragraph.
paragraph.runs[0].text = replaced
for run in paragraph.runs[1:]:
run.text = ""
Notes
- The split-run problem is the most common source of "my find-and-replace only worked sometimes". A placeholder like
{{name}}is frequently stored as{{,nam,e}}across three runs because of an autocorrect or a spellcheck boundary. .dotxtemplates preserve styles, headers, footers, and page setup. Loading one is nearly always better than building a document's styling from scratch.- If the output will be converted to PDF, verify the conversion — fonts that are not embedded will be substituted, and the layout will shift.
Files (claude-skills-collection)
-
SKILL.md 5.6 KB
--- name: word-documents description: Use when creating, reading, or editing Word documents (.docx). Covers document generation with styles and structure, extracting content, find-and-replace, tracked changes, and templates. Trigger on "generate a word document", "find and replace in this docx", "fill this word template", "accept the tracked changes". Do not use for converting a docx to Markdown or PDF — see the document-conversion skill. metadata: category: documents version: 1.0.0 tags: [docx, word, documents, templates, reports] --- # Word Documents ## Purpose Produce and manipulate `.docx` files programmatically, with real styles and structure rather than a wall of manually formatted paragraphs. ## When to Use - Generating a report, memo, letter, or contract as a Word document. - Extracting text, tables, or comments from an existing `.docx`. - Performing find-and-replace across a document while preserving formatting. - Filling a template with data. - Working with tracked changes or comments. ## Capabilities - Document generation with headings, tables, images, headers, and footers. - Style application and modification. - Content extraction, including tables and embedded objects. - Find-and-replace preserving runs and formatting. - Template filling. - Tracked changes and comments. ## Inputs - The content and its structure. - A template or style reference, if the output must match a house style. - The source document, when reading or editing. ## Outputs - A valid `.docx` with a proper style hierarchy. - Extracted content in a structured form. - An edited document that preserves the formatting it should preserve. ## Workflow 1. **Use styles, never direct formatting** — A heading is `Heading 1`, not 18pt bold. Styles produce a navigable document, a working table of contents, and a document that can be restyled in one operation. 2. **Start from a template when the house style matters** — Load the organization's `.dotx` or a reference `.docx` and write into its styles rather than recreating them. 3. **Structure before content** — Headings, then the body. The outline is what makes a long document usable. 4. **Preserve formatting when editing** — A naive find-and-replace on the XML destroys runs. Replace within runs, and handle text split across runs. 5. **Verify the output** — Open it. A `.docx` that a library writes without error can still be malformed in ways Word will complain about. ## Best Practices - Direct formatting (bold, a font size, a colour applied by hand) makes a document unmaintainable. Every visual property should come from a style. - Text in Word is stored in runs, and a single sentence is frequently split across several. A replace that only handles single-run text will silently miss matches where formatting changes mid-word. - Tables need a table style, or they render with no borders and are unreadable when printed. - Images need explicit dimensions. Without them, Word inserts at native resolution, which is usually enormous. - A table of contents field must be marked for update, and Word will prompt the user on open. This is expected behavior, not a bug. - For a document that will be edited by humans, keep the structure simple. Deeply nested tables and text boxes are fragile. ## Examples **Generating a structured document:** ```python from docx import Document from docx.shared import Pt, Inches from docx.enum.text import WD_ALIGN_PARAGRAPH # Start from the house template so styles already exist and match. doc = Document("templates/report-template.docx") doc.add_heading("Quarterly Operations Review", level=0) # Title style p = doc.add_paragraph() p.alignment = WD_ALIGN_PARAGRAPH.CENTER run = p.add_run("Q2 2026") run.italic = True doc.add_heading("Summary", level=1) doc.add_paragraph( "Availability met the 99.9% target in each month of the quarter. " "Two incidents exceeded the 30-minute recovery objective; both are covered below." ) doc.add_heading("Incidents", level=1) table = doc.add_table(rows=1, cols=4) table.style = "Light Grid Accent 1" # a real table style, not hand-drawn borders for cell, heading in zip(table.rows[0].cells, ["Date", "Duration", "Impact", "Cause"]): cell.paragraphs[0].add_run(heading).bold = True for incident in incidents: row = table.add_row().cells row[0].text = incident.date.isoformat() row[1].text = f"{incident.minutes} min" row[2].text = incident.impact row[3].text = incident.cause doc.add_page_break() doc.save("output/q2-review.docx") ``` **Find-and-replace that survives split runs:** ```python def replace_text(paragraph, old: str, new: str) -> None: """Word splits text across runs at formatting boundaries. A naive run-by-run replace misses any match that spans a boundary — which is most of them, in a real document.""" full_text = "".join(run.text for run in paragraph.runs) if old not in full_text: return replaced = full_text.replace(old, new) # Write the result into the first run and clear the rest, preserving the # first run's formatting for the whole paragraph. paragraph.runs[0].text = replaced for run in paragraph.runs[1:]: run.text = "" ``` ## Notes - The split-run problem is the most common source of "my find-and-replace only worked sometimes". A placeholder like `{{name}}` is frequently stored as `{{`, `nam`, `e}}` across three runs because of an autocorrect or a spellcheck boundary. - `.dotx` templates preserve styles, headers, footers, and page setup. Loading one is nearly always better than building a document's styling from scratch. - If the output will be converted to PDF, verify the conversion — fonts that are not embedded will be substituted, and the layout will shift.
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.