---
name: "docx-to-clean-markdown-converter"
description: "Convert Microsoft Word .docx files into clean, readable Markdown without messy inline styles."
metadata:
  author: "Michael Searle"
  version: "1.0.0"
  runtime_compatibility:
    - "codex"
    - "claude-code"
    - "cursor"
    - "windsurf"
triggers:
  - "convert docx to markdown"
  - "extract text from docx without formatting"
  - "clean word document to gfm"
permissions:
  fs_read: true
  fs_write: "workspace"
  shell_exec: false
  net_access: false
---

# Docx to Clean Semantic Markdown Converter

Extracts document content from Word files using mammoth.js or docx2txt, translating headings, lists, tables, and images into clean GitHub-Flavored Markdown (GFM).

## When to Invoke
Invoke this skill whenever you need to:
- convert docx to markdown
- extract text from docx without formatting
- clean word document to gfm

## Execution SOP & Rules
1. Use mammoth.convertToMarkdown({ path: "doc.docx" }) in Node or mammoth CLI in terminal.
2. Provide custom style mappings to preserve specific corporate styles (e.g. b[style-name='Emphasis'] => em).
3. Sanitize generated Markdown tables to ensure consistent pipe formatting.
4. Verify extracted image links and remove orphaned blank lines.

## Verification Checklist
- Run local linting, syntax validation, and type-checks before reporting completion.
- Ensure all created or modified files adhere to workspace boundaries and avoid uncommitted secrets.
- Verify tests or build commands exit cleanly with return code 0.