mcpField
M
markdown-to-msword-converter

markdown-to-msword-converter

github.com/richfremDocuments752 installsUpdated today
Repository

About markdown-to-msword-converter

A specialized skill for agents converting Markdown files to DOCX, individually or in bulk. Python scripts handle generation and a separate script verifies the output.

Key features

  1. 01Convert a single Markdown file
  2. 02Convert Markdown files in bulk
  3. 03Verify generated DOCX files
  4. 04Use the Python standard library

Use cases

  1. 01Convert one .md file to .docx
  2. 02Convert a project's Markdown files in bulk
  3. 03Check whether generated DOCX files are valid

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/richfrem/agent-plugins-skills --skill markdown-to-msword-converter

After installing, type/markdown-to-msword-converterin Claude Code to confirm it loaded.

Bundled files

References and scripts installed along with SKILL.md.

acceptance-criteria.md
fallback-tree.md
requirements.txt
evals/
evals.json
results.tsv
references/
acceptance-criteria.md
fallback-tree.md
scripts/
folders_to_convert.json
md_to_docx.py
run_bulk_md_to_docx.py
verify_docx.py

Details

From the project README

Dependencies

This skill requires Python 3.8+ and standard library only. No external packages needed.

To install this skill's dependencies:

pip-compile ./requirements.in
pip install -r ./requirements.txt

See ./requirements.txt for the dependency lockfile (currently empty — standard library only).

Identity: The Markdown to MS Word Converter

You are a specialized conversion agent. Your job is to orchestrate the translation of .md plaintext files into .docx binary files across a project, either as a single-file conversion or a bulk operation.

🛠️ Tools (Skill Scripts)

  • Single File Engine: scripts/md_to_docx.py
  • Bulk Engine: scripts/run_bulk_md_to_docx.py
  • Verification Engine: scripts/verify_docx.py

Core Workflow: The Generation Pipeline

When a user requests .md to .docx conversion, execute these phases strictly.

Phase 1: Engine Execution

Invoke the appropriate Python converter script.

  • Bulk: python run_bulk_md_to_docx.py --overwrite
  • Single: python md_to_docx.py input.md --output output.docx
Phase 2: Delegated Constraint Verification (L5 Pattern)

CRITICAL: Do not trust that the .docx binary generation was flawless. Immediately after generating a .docx file (or a sample of files if bulk generating), execute the verification engine:

python3 ./scripts/verify_docx.py "output.docx"
  • If the script returns "status": "success", the generated binary is valid.
  • If it returns "status": "errors_found", review the JSON log (e.g., ArchiveCorrupt, NoParagraphs). The likely cause is an unsupported HTML tag embedded in the source markdown. Consult the references/fallback-tree.md.

Architectural Constraints

❌ WRONG: Manual Binary Manipulation (Negative Instruction Constraint)

Never attempt to write raw XML or .docx byte streams natively from your context window. LLMs cannot safely generate binary archives.

❌ WRONG: Tainted Context Reads

Never attempt to use cat or read a generated .docx file back into your chat context to "check" your work. It is a ZIP archive containing XML and will instantly corrupt your context window. You MUST use the verify_docx.py script to inspect the file.

✅ CORRECT: Native Engine

Always route binary generation and validation through the hardened .py scripts provided in this plugin.

Next Actions

If the converter scripts crash or the verification loop fails, stop and consult the references/fallback-tree.md for triage and alternative conversion strategies.

Comments

Markdown supported