Markitdown
ImCa0/just-laws
Convert files and office documents to Markdown. An agent skill from ImCa0/just-laws.
Converts Word .docx files to Markdown with a bundled script before analysis, extracting embedded images and handling whole folders alongside the PDF and Excel converters.
Install Word to Markdown Converter
$ npx skills add github/awesome-copilot --skill convert-word-to-md -a claude-codeProject install by default; add -g for ~/.claude/skills/.
$ gh skill install github/awesome-copilot convert-word-to-md --agent claude-codeProject scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).
$ git clone --depth 1 https://github.com/github/awesome-copilot.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills/convert-word-to-md .claude/skills/convert-word-to-md && rm -rf skills-srcUse ~/.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/
Install the "convert-word-to-md" agent skill from https://github.com/github/awesome-copilot/tree/main/skills/convert-word-to-md into .claude/skills/convert-word-to-md/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "convert-word-to-md", then confirm the skill loads.Claude Code copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$skill-installer install https://github.com/github/awesome-copilot/tree/main/skills/convert-word-to-mdType this inside Codex. $skill-installer <name> installs a curated skill from openai/skills. The installer writes to $CODEX_HOME/skills (default ~/.codex/skills). Restart Codex if the skill does not show up.
$ npx skills add github/awesome-copilot --skill convert-word-to-md -a codexProject install goes to .agents/skills/; add -g for ~/.codex/skills/.
$ gh skill install github/awesome-copilot convert-word-to-md --agent codexProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/github/awesome-copilot.git skills-src && mkdir -p .agents/skills && cp -r skills-src/skills/convert-word-to-md .agents/skills/convert-word-to-md && rm -rf skills-srcUse ~/.agents/skills/ instead of .agents/skills for a personal install.
Codex skills documentation · loads skills from .agents/skills/
Install the "convert-word-to-md" agent skill from https://github.com/github/awesome-copilot/tree/main/skills/convert-word-to-md into .agents/skills/convert-word-to-md/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "convert-word-to-md", then confirm the skill loads.Codex copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ npx skills add github/awesome-copilot --skill convert-word-to-md -a cursorProject install goes to .agents/skills/; add -g for ~/.cursor/skills/.
$ gh skill install github/awesome-copilot convert-word-to-md --agent cursorProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/github/awesome-copilot.git skills-src && mkdir -p .cursor/skills && cp -r skills-src/skills/convert-word-to-md .cursor/skills/convert-word-to-md && rm -rf skills-srcUse ~/.cursor/skills/ instead of .cursor/skills for a personal install.
Cursor skills documentation · loads skills from .cursor/skills/, .agents/skills/, .claude/skills/, .codex/skills/
Install the "convert-word-to-md" agent skill from https://github.com/github/awesome-copilot/tree/main/skills/convert-word-to-md into .cursor/skills/convert-word-to-md/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "convert-word-to-md", then confirm the skill loads.Cursor copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ gemini skills install https://github.com/github/awesome-copilot.git --path skills/convert-word-to-md--scope user (default) or --scope workspace; --path is the subfolder of the repo that holds the skill; --consent skips the security confirmation prompt.
$ npx skills add github/awesome-copilot --skill convert-word-to-md -a gemini-cliProject install goes to .agents/skills/; add -g for ~/.gemini/skills/.
$ gh skill install github/awesome-copilot convert-word-to-md --agent gemini-cliProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/github/awesome-copilot.git skills-src && mkdir -p .gemini/skills && cp -r skills-src/skills/convert-word-to-md .gemini/skills/convert-word-to-md && rm -rf skills-srcUse ~/.gemini/skills/ instead of .gemini/skills for a personal install, then run /skills reload.
Gemini CLI skills documentation · loads skills from .gemini/skills/, .agents/skills/
Install the "convert-word-to-md" agent skill from https://github.com/github/awesome-copilot/tree/main/skills/convert-word-to-md into .gemini/skills/convert-word-to-md/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "convert-word-to-md", then confirm the skill loads.Gemini CLI copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ gh skill install github/awesome-copilot convert-word-to-mdInstalls for Copilot at project scope by default; add --scope user for a personal install. Preview a skill first with gh skill preview. Needs GitHub CLI 2.90.0 or later (public preview).
$ npx skills add github/awesome-copilot --skill convert-word-to-md -a github-copilotProject install goes to .agents/skills/; add -g for ~/.copilot/skills/.
$ git clone --depth 1 https://github.com/github/awesome-copilot.git skills-src && mkdir -p .github/skills && cp -r skills-src/skills/convert-word-to-md .github/skills/convert-word-to-md && rm -rf skills-srcUse ~/.copilot/skills/ instead of .github/skills for a personal install. Commit .github/skills so cloud agent and code review can use it.
GitHub Copilot skills documentation · loads skills from .github/skills/, .claude/skills/, .agents/skills/
Install the "convert-word-to-md" agent skill from https://github.com/github/awesome-copilot/tree/main/skills/convert-word-to-md into .github/skills/convert-word-to-md/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "convert-word-to-md", then confirm the skill loads.GitHub Copilot copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ npx skills add github/awesome-copilot --skill convert-word-to-md -a opencodeOpenCode documents no install command of its own. Project install goes to .agents/skills/; add -g for ~/.config/opencode/skills/.
$ gh skill install github/awesome-copilot convert-word-to-md --agent opencodeProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/github/awesome-copilot.git skills-src && mkdir -p .opencode/skills && cp -r skills-src/skills/convert-word-to-md .opencode/skills/convert-word-to-md && rm -rf skills-srcUse ~/.config/opencode/skills/ instead of .opencode/skills for a personal install.
OpenCode skills documentation · loads skills from .opencode/skills/, .claude/skills/, .agents/skills/
Install the "convert-word-to-md" agent skill from https://github.com/github/awesome-copilot/tree/main/skills/convert-word-to-md into .opencode/skills/convert-word-to-md/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "convert-word-to-md", then confirm the skill loads.OpenCode copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
Facts
- Skill name
convert-word-to-md- GitHub stars
- 40k
- Token cost
- ~1.6k tokens
- SKILL.md length
- 711 words
- Files
- 4 (incl. scripts, references)
- Skills in repo
- 417
- Repo updated
- First seen
- Licence
- MIT
At a glance
Converts Word .docx files to Markdown with a bundled script before analysis, extracting embedded images and handling whole folders alongside the PDF and Excel converters.
- Summarizing or reviewing a Word document someone attached
- SKILL.md covers When to use this skill, Setup (once per environment), Usage and Deciding where output goes, plus 1 more section
- Runs Python scripts from its folder; calls python
- Pulling specific data out of a .docx report, contract or proposal
What it does
This skill turns Word `.docx` files into Markdown before the agent reads, summarizes, searches or extracts data from them, because a `.docx` is a zipped XML bundle that cannot be read reliably as plain text. The agent must always run the bundled `scripts/convert_word_to_md.py` first instead of opening the file directly or writing its own parser, and the skill also handles whole folders of Word files. Legacy `.doc` files are not supported; you are asked to re-save them as `.docx`.
The script builds on the MarkItDown package and writes a self-contained folder per document rather than a single loose file. MarkItDown only leaves a truncated placeholder for images, so the script extracts the real images from the `.docx` into an `img/` subfolder with numbered names, and no `img/` folder appears when a document has none. A one-time setup in `references/setup.md` confirms Python, pip and `markitdown` are installed, and the script points back to that file if `markitdown` is missing.
When a folder holds several supported types, this skill covers only `.docx`; the agent must also run the sibling skills `convert-pdf-to-md` and `convert-excel-to-md` in parallel so no file type is silently skipped. Commands are given for Windows PowerShell and for macOS and Linux.
When your agent uses it
- Summarizing or reviewing a Word document someone attached
- Pulling specific data out of a .docx report, contract or proposal
- Converting a folder of Word documents in one pass
- Comparing two Word documents by their text
Example prompts
- “Summarize the attached proposal.docx in five bullet points.”
- “Extract the pricing table from ./contracts/vendor-agreement.docx.”
- “Convert every Word file in ./reports to Markdown, and handle the PDFs and spreadsheets in that folder too.”
- “Compare the two resume versions in my Downloads folder and list what changed.”
Requirements
- Python and pip
- The `markitdown` package
What it can do on your machine
Read from SKILL.md and the folder at commit 727ff2e. 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 2 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 to Markdown Converter loads about 1.6k tokens when it runs, and up to ~2.2k if it reads all its reference files. Until then it costs about 234 tokens; SKILL.md has 711 words of instructions outside code blocks.
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 github/awesome-copilot at commit 727ff2e, republished under its MIT licence (© github). 711 words, ~1,592 tokens.
Download SKILL.mdSave it as
.claude/skills/convert-word-to-md/SKILL.md (or your agent's skills folder). This skill also uses 3 other files; get the full folder from GitHub.- name
- convert-word-to-md
- description
- Converts Word (.docx) documents into Markdown so their contents can be accurately analyzed, summarized, searched, or extracted from. Use this skill whenever the user shares, references, or asks about a .docx file — even if they don't say "convert" or "markdown" explicitly. This includes requests to "read", "summarize", "review", "extract data from", "compare", or "analyze" a Word document, resume, report, contract, or proposal. Always run the bundled conversion script to produce Markdown first; do not attempt to parse .docx content directly or write ad-hoc conversion code. Also use this skill for batch requests involving a whole folder of Word documents. IMPORTANT: When the user references a folder or set of documents containing multiple file types (.pdf, .docx, .xlsx), invoke ALL three sibling skills — convert-pdf-to-md, convert-word-to-md, and convert-excel-to-md — so no file type is silently skipped.
Convert Word to Markdown
When to use this skill
Trigger this skill any time there is a .docx file that needs to be
understood or processed — for example, a user attaches a Word document and
asks questions about it, wants a summary, wants specific data pulled out, or
wants multiple Word documents in a folder processed together. Word's native
.docx format is a zipped XML bundle that is not reliably readable as plain
text, so always convert it to Markdown first using the script in this
skill rather than trying to open or parse the file directly.
This skill only supports .docx. If asked to convert a legacy .doc file,
tell the user it isn't supported and ask them to re-save it as .docx
(Word: File > Save As > Word Document (.docx)) first.
Mixed file types: When the user references a folder or set of documents
containing multiple supported file types (.pdf, .docx, .xlsx), this
skill handles only .docx files. The agent MUST also invoke the sibling
skills in parallel:
convert-pdf-to-mdfor any.pdffilesconvert-excel-to-mdfor any.xlsxfiles
Never process a folder and silently skip a supported file type. All three skills must be invoked together when mixed types are present.
Setup (once per environment)
Before the first conversion in a given environment, follow
references/setup.md step by step to ensure Python,
pip, and the markitdown package are installed. Do this proactively rather
than guessing whether the environment is ready — the script itself will
also fail with a clear pointer back to that file if markitdown turns out
to be missing, so it's safe to just try the conversion first if you're
reasonably confident setup was already done.
Usage
The conversion script lives at scripts/convert_word_to_md.py.
Output structure: MarkItDown embeds images as a truncated data:image/png;base64... URI
placeholder (not real image data), so the script
extracts real images directly from the .docx and writes a self-contained
folder per document instead of a single loose .md file:
<name>/
img/
img001.<ext>
img002.<ext>
...
<name>.md (image references are relative: img/imgNNN.ext)If the document has no embedded images, no img/ folder is created.
Single file:
# Windows
python scripts\convert_word_to_md.py "C:\path\to\document.docx"# macOS / Linux
python scripts/convert_word_to_md.py "/path/to/document.docx"This creates a document\ folder next to the source file (containing
document.md and, if present, document\img\). To control the destination
folder explicitly:
python scripts\convert_word_to_md.py "C:\path\to\document.docx" -o "C:\path\to\output_folder"A folder of Word documents (batch mode):
python scripts\convert_word_to_md.py "C:\path\to\folder"Add --recursive to also include subfolders:
python scripts\convert_word_to_md.py "C:\path\to\folder" --recursiveEach .docx found gets its own <name>\ output folder next to it by
default. Pass -o "C:\path\to\output_parent" to collect all the generated
<name>\ folders under a separate parent directory instead (subfolder
structure is preserved when combined with --recursive).
After conversion, read the resulting .md file(s) to perform the actual
analysis the user asked for — the script's job is only to produce accurate
Markdown (and images), not to interpret the content.
Show full SKILL.md (268 more words)Show less
Deciding where output goes
Default — always output next to the source file. The <name>/ folder
is created in the same directory as the source .docx. This is the required
default for every case. Do NOT override it unless the user explicitly asks
for a different location.
Only use -o when the user explicitly provides an output path (e.g.,
"save the output to C:\output", "put the results in D:\work"). Do NOT
pass -o based on the agent's current working directory, the session state
folder, or any implied location.
If the source file path cannot be fully resolved — for example, the
user provides only a filename with no directory, or the path is ambiguous —
use ask_user to confirm the full absolute path before running the
conversion. Never guess or assume the directory.
Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
ModuleNotFoundError: No module named 'markitdown' / exit code 2 | MarkItDown not installed | Follow references/setup.md |
ERROR: Unsupported file type '.doc' / exit code 3 | Legacy .doc, not .docx | Ask the user to re-save as .docx |
ERROR: Input path not found / exit code 3 | Wrong path, or file moved | Confirm the correct path with the user |
FAILED <file> -> ... in batch output | That specific file is corrupt, password-protected, or otherwise unreadable | Report which file(s) failed; other files in the batch still succeed |
NOTE: skipped N non-.docx file(s) | Folder contains non-Word files | Expected — those files are intentionally ignored |
WARNING: found N image placeholder(s) ... but extracted M image file(s) | Mismatch between MarkItDown's placeholder count and images found in word/media/ (unusual/malformed docx) | Placeholders are left unreplaced rather than risk wrong images; inspect the source file's media manually if images are needed |
© github, MIT. 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 3 other files (scripts, references) in skills/convert-word-to-md of github/awesome-copilot.
- SKILL.md
- references/setup.md
- scripts/convert_word_to_md.py
- scripts/requirements.txt
Open the folder on GitHubat commit 727ff2e
Compare with similar skills
Word to Markdown Converter 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.
| Skill | Stars | Used in | Tokens | Auto-check | Licence | Repo updated |
|---|---|---|---|---|---|---|
| Word to Markdown Converter this skillgithub/awesome-copilot | 40k | — | ~1.6k | Automated safety check: Pass | MIT | |
| MarkitdownImCa0/just-laws | 781 | 14 repos | ~3.2k | Automated safety check: Notes | MIT | |
| Doc To Markdowndaymade/claude-code-skills | 1.4k | — | ~2.5k | Automated safety check: Pass | MIT | |
| Markdown Converterintellectronica/agent-skills | 295 | 4 repos | ~492 | Automated safety check: Pass | CC0-1.0 | |
| Summarizemitsuhiko/agent-stuff | 3.2k | — | ~524 | Automated safety check: Pass | Apache-2.0 | |
| Markdown ConverterTeam-Commonly/commonly | 1.4k | — | ~557 | Automated safety check: Pass | Apache-2.0 |
Similar skills
Doc To Markdown
daymade/claude-code-skills
Converts DOCX/PDF/PPTX and saved HTML/HTM to high-quality Markdown with automatic post-processing.
Markdown Converter
intellectronica/agent-skills
Convert documents and files to Markdown using markitdown. An agent skill from intellectronica/agent-skills.
Summarize
mitsuhiko/agent-stuff
Fetch a URL or convert a local file (PDF/DOCX/HTML/etc.) into Markdown using uvx markitdown, optionally it can summarize
Markdown Converter
Team-Commonly/commonly
Convert binary documents (PDF, DOCX, XLSX, PPTX, HTML, EPUB, images) to clean LLM-friendly Markdown using Microsoft's markitdown Python tool.
Huashu Markdown Publishing Pipeline
alchaincyf/huashu-md-html
Converts files and web pages into clean Markdown, then turns Markdown into polished HTML, Word, PDF and EPUB using four templates.
More from github/awesome-copilot
All 417 skills in this repo- Official
Acquire Codebase Knowledge
github/awesome-copilot
Maps an unfamiliar codebase into seven evidence-backed documents in docs/codebase/, using a scan script and templates, for onboarding or architecture write-ups.
- Official
Azure Architecture Autopilot
github/awesome-copilot
Designs Azure infrastructure from a natural-language description, or diagrams an existing resource group, then refines the design through conversation and deploys it with Bicep.
- Official
Draw.io Diagram Generator
github/awesome-copilot
Generates, edits and validates draw.io files with correct mxGraph XML, covering flowcharts, architecture, sequence, ER and UML class diagrams.
- Official
Credit Risk Data Cleaning
github/awesome-copilot
Cleans raw credit data and screens variables before loan modeling, dropping unstable, noisy or redundant features and writing an Excel report of every step.
- Official
Daily Focus Board
github/awesome-copilot
Builds a warm, browser-based daily focus board the user updates by talking to their agent, with Eisenhower priorities, a brain-dump box and kind not-today carryover.
- Official
Python Pypi Package Builder
github/awesome-copilot
End-to-end skill for building, testing, linting, versioning, and publishing a production-grade Python library to PyPI.
Related
Works with
Categories
Questions about Word to Markdown Converter
What does Word to Markdown Converter do?
Converts Word .docx files to Markdown with a bundled script before analysis, extracting embedded images and handling whole folders alongside the PDF and Excel converters. docx` is a zipped XML bundle that cannot be read reliably as plain text.py` first instead of opening the file directly or writing its own parser, and the skill also handles whole folders of Word files.
When should I use Word to Markdown Converter?
Word to Markdown Converter fits situations like: summarizing or reviewing a Word document someone attached; pulling specific data out of a .docx report, contract or proposal; converting a folder of Word documents in one pass; comparing two Word documents by their text.
How do I install Word to Markdown Converter in Claude Code?
Run `npx skills add github/awesome-copilot --skill convert-word-to-md -a claude-code`. Or copy the skill folder (skills/convert-word-to-md in github/awesome-copilot) into .claude/skills/convert-word-to-md in your project. Claude Code loads it when a task matches its description.
How do I install Word to Markdown Converter in Codex?
Run `npx skills add github/awesome-copilot --skill convert-word-to-md -a codex`. Or copy the skill folder (skills/convert-word-to-md in github/awesome-copilot) into .agents/skills/convert-word-to-md in your project. Codex loads it when a task matches its description.
Can I use Word to Markdown Converter 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 github/awesome-copilot --skill convert-word-to-md -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/convert-word-to-md, .gemini/skills/convert-word-to-md, .github/skills/convert-word-to-md and .opencode/skills/convert-word-to-md in your project.
What does Word to Markdown Converter need to run?
Going by SKILL.md and its folder, Word to Markdown Converter needs Python for the scripts in its folder and the command-line tools its instructions call (python). Our summary lists: Python and pip; The `markitdown` package.
Does Word to Markdown Converter 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 to Markdown Converter 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 to Markdown Converter use?
Word to Markdown Converter is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.
How many tokens does Word to Markdown Converter use?
About 1.6k tokens (SKILL.md is roughly 6.4k 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 573 tokens, read only when the agent opens those files.
What are the alternatives to Word to Markdown Converter?
Skills that share tags, products or a category with Word to Markdown Converter: Markitdown (ImCa0/just-laws, 781 stars), Doc To Markdown (daymade/claude-code-skills, 1.4k stars), Markdown Converter (intellectronica/agent-skills, 295 stars) and Summarize (mitsuhiko/agent-stuff, 3.2k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.
Who maintains Word to Markdown Converter?
github (a GitHub organization, an official publisher) maintains it in github/awesome-copilot, which has 39,748 GitHub stars. The repository holds 417 skills in this directory. The repository was last updated on October 7, 2026.
Source: github/awesome-copilot on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.