Agent skill

Word DOCX Toolkit

by TokenRhythm in TokenRhythm/opensquilla

Inspects, edits in place or creates Word .docx files with bundled Python scripts, keeping existing styles intact when content changes.

Apache-2.0Auto-check passedDocuments & Office

Install Word DOCX Toolkit

skills CLI
$ npx skills add TokenRhythm/opensquilla --skill docx -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install TokenRhythm/opensquilla docx --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/TokenRhythm/opensquilla.git skills-src && mkdir -p .claude/skills && cp -r skills-src/src/opensquilla/skills/bundled/docx .claude/skills/docx && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
docx
GitHub stars
7.1k
Token cost
~1.7k tokens
SKILL.md length
644 words
Files
7 (incl. scripts, references)
Skills in repo
8
Repo updated
First seen
Licence
Apache-2.0

At a glance

Inspects, edits in place or creates Word .docx files with bundled Python scripts, keeping existing styles intact when content changes.

  • Reading the text, tables and styles of an existing Word document
  • SKILL.md covers Decide the path first, Path A: Inspect, Path B: Edit in place and Path C: Create from scratch, plus 3 more sections
  • Runs Python scripts from its folder; calls python
  • Filling placeholders in a .docx while keeping its formatting

What it does

The skill treats a .docx as an OOXML zip and has the agent choose one of three paths up front: inspect an existing file, edit it in place, or create a new document from a brief. Inspection runs scripts/inspect_docx.py to dump paragraphs, tables and styles as stable JSON, which can be compared before and after an edit to confirm that a round trip kept everything.

For edits, edit_docx.py applies a JSON list of operations such as replace_run and replace_text at the run level, so fonts and theme settings survive, and a placeholder spread over several runs is collapsed into the first. Changes that python-docx handles poorly, such as page layout, numbering and tracked changes, are made by unzipping the file, patching word/document.xml and related parts and repacking. The folder also has create_docx.py, export_markdown_docx.py, a python-docx reference and a third-party notices file. When you hand over a document and ask for changes, the agent edits it rather than starting fresh.

When your agent uses it

  • Reading the text, tables and styles of an existing Word document
  • Filling placeholders in a .docx while keeping its formatting
  • Creating a new Word document from a brief
  • Reviewing or changing tracked changes in a .docx

Example prompts

  • “Replace the client name and date in proposal.docx but keep all the formatting.”
  • “Show me the structure of contract.docx: headings, tables and styles.”
  • “Create a two-page project brief as a Word document from these notes.”

Requirements

  • Python with python-docx

What it can do on your machine

Read from SKILL.md and the folder at commit 4494195. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Ships 4 files in scripts/ (Python), which the agent can run.

    Shell commands in SKILL.md call:

    • python

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Word DOCX Toolkit loads about 1.7k tokens when it runs, and up to ~2.5k if it reads all its reference files. Until then it costs about 46 tokens; SKILL.md has 644 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~46
When it runs · the whole SKILL.md, loaded when a task matches
~1.7k
With references · SKILL.md plus every file in references/, read only if the agent opens them
~2.5k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); the scripts in this folder are not scanned.

SKILL.md

The full file from TokenRhythm/opensquilla at commit 4494195, republished under its Apache-2.0 licence (© TokenRhythm). 644 words, ~1,744 tokens.

Download SKILL.mdSave it as .claude/skills/docx/SKILL.md (or your agent's skills folder). This skill also uses 6 other files; get the full folder from GitHub.
name
docx
description
Read, inspect, edit, or create Microsoft Word `.docx` documents, including structured text extraction, style-preserving edits, tracked-change review, and generation from a brief.
visibility
public
invocation
direct
description_zh
读取、编辑或创建Microsoft Word .docx 文件。当用户提到Word文档、.docx文件、合同、报告、简报、备忘录,或要求提取文本、修改现有文档、根据简报生成文档或审查修订记录时触发。支持三种执行路径:文本与结构提取、按run就地编辑(保留样式)、用python-docx从零创建;处理python-do…
homepage
https://python-docx.readthedocs.io/
provenance.origin
clawhub-mit0
provenance.license
MIT-0
provenance.upstream_url
https://clawhub.ai/word-docx
provenance.maintained_by
OpenSquilla

docx

Work with Microsoft Word .docx files. The format is OOXML — a zip container holding XML parts (word/document.xml, styles.xml, numbering.xml, headers, footers, relationships). Treat structure as primary; rendered text is a view.

Decide the path first

Pick one path up front. The right path depends only on what is on disk before you start.

You haveGoalPath
Existing .docxRead text/structureA. Inspect
Existing .docxModify content while keeping stylesB. Edit-in-place
Nothing or a briefBuild a new docC. Create from scratch

If the user hands you a doc and asks for changes, default to path B and treat the input as the visual style baseline. Only choose path C when the user says "start fresh" or there is no input.


Path A: Inspect

Dump structure as JSON for inspection without mutating anything.

bash
python {baseDir}/scripts/inspect_docx.py /path/to/doc.docx

Output schema:

json
{
  "paragraphs": [{"index": 0, "text": "...", "style": "Heading 1"}, ...],
  "tables": [[["row0,col0", "row0,col1"], ...], ...],
  "sections": 1,
  "has_tracked_changes": false
}

Use this whenever you need to see what is in the doc before deciding how to edit. The output is stable and machine-readable — diff two inspect outputs to verify a round-trip preserved everything you intended.


Path B: Edit in place

Two sub-strategies; pick by how invasive the edit is.

B1. Run-level text replacement (preferred)

When the change is "swap this string" or "fill these placeholders": mutate runs in place. This preserves all theme/style/font settings.

bash
python {baseDir}/scripts/edit_docx.py input.docx ops.json --out output.docx

ops.json is a list of operations:

json
[
  {"op": "replace_run", "para": 0, "run": 0, "text": "Q3 Review"},
  {"op": "replace_text", "find": "{{CLIENT}}", "with": "Acme Corp"}
]

Edit at the run level, not the paragraph level — replacing whole paragraph text drops formatting. If a placeholder spans multiple runs (often happens when the original template applied bold/italic mid-word), the helper script collapses runs into the first one and clears the rest.

B2. Structural edits (sections / page layout / numbering)

python-docx exposes paragraphs, tables, and runs but has limited support for page layout, numbering definitions, and tracked changes. For those, unzip the .docx, patch word/document.xml and adjacent parts, and repack:

bash
mkdir _unpacked && (cd _unpacked && unzip -q ../input.docx)
# edit _unpacked/word/document.xml
(cd _unpacked && zip -q -r ../output.docx . -x "*.DS_Store")

Rules when patching XML:

  • Use defusedxml.ElementTree or lxml, not stdlib xml.etree.ElementTree. ET drops or rewrites namespace prefixes (w:, r:) in ways Word refuses to load.
  • Preserve xml:space="preserve" on <w:t> elements that hold leading or trailing whitespace.
  • [Content_Types].xml must list every part type. Removing a header without also removing its override entry yields a "repair" prompt in Word.
  • Numbering definitions live in numbering.xml; bullet/number changes must patch the numbering ID, not just the visible text.

When done, validate by opening in LibreOffice headless before declaring success — silent failures are common.


Show full SKILL.md (257 more words)Show less

Path C: Create from scratch

For a simple Markdown source, run the export script with the Markdown on stdin:

bash
python {baseDir}/scripts/export_markdown_docx.py --out out.docx < draft.md

For structured content, use a JSON specification:

bash
python {baseDir}/scripts/create_docx.py spec.json --out out.docx

spec.json describes content declaratively:

json
{
  "metadata": {"title": "Q3 Review", "author": "Wei E."},
  "body": [
    {"kind": "heading", "level": 1, "text": "Q3 Review"},
    {"kind": "paragraph", "text": "Revenue +18% YoY."},
    {"kind": "table", "rows": [["Metric", "Value"], ["Revenue", "$2.1M"]]}
  ]
}

For programmatic use call python-docx directly:

python
from docx import Document
doc = Document()
doc.add_heading("Q3 Review", level=1)
doc.add_paragraph("Revenue +18% YoY.")
table = doc.add_table(rows=2, cols=2)
table.rows[0].cells[0].text = "Metric"
doc.save("out.docx")

See references/python_docx.md for paragraphs, styles, numbering, tables, headers/footers, and section breaks.


Tracked changes

Tracked changes are stored in word/document.xml as <w:ins> and <w:del> elements. python-docx does not expose them as first-class objects — the inspect helper sets has_tracked_changes: true when any w:ins or w:del element is found, and you must resolve them by patching XML directly. Treat docs with tracked changes as read-only until reviewers accept or reject the revisions.


Common pitfalls

SymptomCauseFix
Word reports "needs repair"Removed a header part but left override in [Content_Types].xmlStrip the override entry too
Text replacement drops bold/italicReplaced paragraph.text instead of editing runsUse op: replace_run
Numbering restarts unexpectedlyEdited a list item across two abstractNum definitionsPatch numbering.xml; rebuild numbering IDs
Smart-quote characters render as garbageXML read with stdlib ET dropped namespacesSwitch to defusedxml or lxml
Long string overflowsCell width is fixed in the templateEither shorten or compute auto-fit before save

Boundaries

  • This skill is for .docx (OOXML WordprocessingML). It does not handle .doc (legacy binary) or Google Docs. Convert via LibreOffice or Word export first.
  • Do not run macro-enabled .docm / VBA. The runtime sandbox does not execute embedded code, and security scanners flag mixed content.
  • For PDF generation from a .docx, hand off to LibreOffice headless or a separate PDF skill. This skill stops at .docx.

© TokenRhythm, Apache-2.0. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 6 other files (scripts, references) in src/opensquilla/skills/bundled/docx of TokenRhythm/opensquilla.

  • SKILL.md
  • THIRD_PARTY_NOTICES.md
  • references/python_docx.md
  • scripts/create_docx.py
  • scripts/edit_docx.py
  • scripts/export_markdown_docx.py
  • scripts/inspect_docx.py

Open the folder on GitHubat commit 4494195

Compare with similar skills

Word DOCX Toolkit next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Word DOCX Toolkit compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Word DOCX Toolkit this skillTokenRhythm/opensquilla7.1k—~1.7kAutomated safety check: PassApache-2.0
Word Document Reader and WriterHKUDS/DeepTutor41k—~2.5kAutomated safety check: PassApache-2.0
Markdown to Word Convertercat-xierluo/SuitAgent206—~559Automated safety check: PassMIT
Word Document Creation And Editingpipeshub-ai/pipeshub-ai3.8k—~1.3kAutomated safety check: PassApache-2.0
DOCXLeastBit/Claude_skills_zh-CN588—~1.3kAutomated safety check: NotesProprietary
Office DOCXsingula-ai/alego1091 repos~1.5kAutomated safety check: PassMIT

Similar skills

  • Reads, creates and edits Word .docx files with python-docx, and drops to raw OOXML for tracked changes, comments and byte-exact edits.

    41k GitHub stars~2.5k tokensUpdated 3 days ago
    Documents & OfficeAuto-check passed
  • Markdown to Word Converter

    cat-xierluo/SuitAgent

    Converts Markdown files into Word documents formatted to Chinese typesetting conventions, with presets for academic, legal, report and book layouts.

    206 GitHub stars~559 tokensUpdated 1 mo ago
    Documents & OfficeAuto-check passed
  • Word Document Creation And Editing

    pipeshub-ai/pipeshub-ai

    Routes a Word document request to the right approach: a TypeScript library for new files, XML editing for existing ones, and plain reading only.

    3.8k GitHub stars~1.3k tokensUpdated today
    Documents & OfficeAuto-check passed
  • DOCX

    LeastBit/Claude_skills_zh-CN

    全面的文档创建、编辑和分析功能,支持修订追踪、批注、格式保留和文本提取。当 Claude 需要处理专业文档(.docx 文件)时使用:(1) 创建新文档,(2) 修改或编辑内容,(3) 处理修订追踪,(4) 添加批注,或其他任何文档任务

    588 GitHub stars~1.3k tokensUpdated 8 mo ago
    Documents & OfficeAuto-check: notes
  • Office DOCX

    singula-ai/alego

    Create, read, edit, and check Word documents (.docx), including reports, letters, and formatted tables.

    109 GitHub starsUsed in 1 repo~1.5k tokens
    Documents & OfficeAuto-check passed
  • Read DOCX Review

    daymade/claude-code-skills

    读取 Word/WPS 审阅后的 docx,把批注(comments)与修订(track changes)提取成可逐条裁决的 markdown 对账表或 JSON。触发场景:对方批注完的合同/协议/书稿/报告回来了要读意见;「提取 docx 批注」「审阅意见对账」「读一下修订」「谁批了什么、批在哪」;WPS 云文档/Word 在线协作…

    1.4k GitHub stars~993 tokensUpdated today
    Documents & OfficeAuto-check passed

More from TokenRhythm/opensquilla

All 8 skills in this repo
  • Deep Research Workflow

    TokenRhythm/opensquilla

    Runs multi-round research in three stages with a persisted state file, evidence tracking and a long-form report with per-claim citations.

    7.1k GitHub stars~1.3k tokensUpdated 2 days ago
    Auto-check passed
  • PDF Toolkit

    TokenRhythm/opensquilla

    Deterministic PDF operations through bundled scripts: extract text and tables, merge files or page ranges, split by range, fill form fields and build PDFs from data.

    7.1k GitHub stars~1.9k tokensUpdated 2 days ago
    Auto-check passed
  • HTML Coder

    TokenRhythm/opensquilla

    Guides semantic, accessible HTML work: pages, forms, media and HTML5 APIs, plus how to deliver a runnable webpage project with a preview.

    7.1k GitHub stars~1.4k tokensUpdated 2 days ago
    Auto-check passed
  • PowerPoint Reader and Builder

    TokenRhythm/opensquilla

    Reads, edits in place, or creates PowerPoint .pptx decks, picking one of three paths based on what tools and files are available.

    7.1k GitHub stars~3.8k tokensUpdated 2 days ago
    Auto-check: notes
  • Excel Workbook Editor

    TokenRhythm/opensquilla

    Inspects, edits in place or creates Microsoft Excel .xlsx workbooks with openpyxl, treating each cell as a typed number, string, datetime or formula value.

    7.1k GitHub stars~1.6k tokensUpdated 2 days ago
    Auto-check passed
  • Sub-Agent Delegation

    TokenRhythm/opensquilla

    Hands a self-contained coding task to Codex, Claude Code, OpenCode or Pi as a non-interactive background process, using OpenSquilla's exec_command and process tools.

    7.1k GitHub stars~3k tokensUpdated 2 days ago
    Auto-check passed

Questions about Word DOCX Toolkit

What does Word DOCX Toolkit do?

Inspects, edits in place or creates Word .docx files with bundled Python scripts, keeping existing styles intact when content changes. docx as an OOXML zip and has the agent choose one of three paths up front: inspect an existing file, edit it in place, or create a new document from a brief.py to dump paragraphs, tables and styles as stable JSON, which can be compared before and after an edit to confirm that a round trip kept everything.

When should I use Word DOCX Toolkit?

Word DOCX Toolkit fits situations like: reading the text, tables and styles of an existing Word document; filling placeholders in a .docx while keeping its formatting; creating a new Word document from a brief; reviewing or changing tracked changes in a .docx.

How do I install Word DOCX Toolkit in Claude Code?

Run `npx skills add TokenRhythm/opensquilla --skill docx -a claude-code`. Or copy the skill folder (src/opensquilla/skills/bundled/docx in TokenRhythm/opensquilla) into .claude/skills/docx in your project. Claude Code loads it when a task matches its description.

How do I install Word DOCX Toolkit in Codex?

Run `npx skills add TokenRhythm/opensquilla --skill docx -a codex`. Or copy the skill folder (src/opensquilla/skills/bundled/docx in TokenRhythm/opensquilla) into .agents/skills/docx in your project. Codex loads it when a task matches its description.

Can I use Word DOCX Toolkit in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add TokenRhythm/opensquilla --skill docx -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/docx, .gemini/skills/docx, .github/skills/docx and .opencode/skills/docx in your project.

What does Word DOCX Toolkit need to run?

Going by SKILL.md and its folder, Word DOCX Toolkit needs Python for the scripts in its folder and the command-line tools its instructions call (python). Our summary lists: Python with python-docx.

Does Word DOCX Toolkit access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is Word DOCX Toolkit safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. The check reads SKILL.md only: the scripts in the folder are not scanned, so read them before running anything.

What licence does Word DOCX Toolkit use?

Word DOCX Toolkit is published under the Apache-2.0 licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Word DOCX Toolkit use?

About 1.7k tokens (SKILL.md is roughly 7k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full. Its references folder adds about 741 tokens, read only when the agent opens those files.

What are the alternatives to Word DOCX Toolkit?

Skills that share tags, products or a category with Word DOCX Toolkit: Word Document Reader and Writer (HKUDS/DeepTutor, 41k stars), Markdown to Word Converter (cat-xierluo/SuitAgent, 206 stars), Word Document Creation And Editing (pipeshub-ai/pipeshub-ai, 3.8k stars) and DOCX (LeastBit/Claude_skills_zh-CN, 588 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Word DOCX Toolkit?

TokenRhythm (a GitHub organization) maintains it in TokenRhythm/opensquilla, which has 7,087 GitHub stars. The repository holds 8 skills in this directory. The repository was last updated on October 4, 2026.

Source: TokenRhythm/opensquilla on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.