# Markwatch

> Converts documents (PDF, DOCX, PPTX, XLSX, XLS, CSV, HTML, images, and anything else MarkItDown supports) into a Markdown file sitting right next to the original, without touching or deleting the source. Use this whenever the user wants to read, search, summarize, or otherwise work with the text content of a non-Markdown file, wants to convert a document to Markdown, or hands you a file path/attachment whose extension isn't .md and asks you to look at it. Handles installing the markitdown CLI on first use automatically — don't try to install it or shell out to markitdown yourself.

- Skill: `zurmely/markwatch` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add zurmely/markwatch`
- Raw SKILL.md: https://api.skillmd.com/api/skills/zurmely/markwatch/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: Zurmely (https://skillmd.com/u/zurmely)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/zurmely/markwatch

---


# MarkWatch conversion skill

Companion to the MarkWatch VS Code extension (see the repo's `AGENTS.md`): same
non-destructive conversion, same output naming, but for agent/CLI contexts
instead of the editor.

## When to use this

Any time you need the text/content of a file that isn't already Markdown or
plain text — a `.docx`, `.pdf`, `.pptx`, `.xlsx`/`.xls`, `.csv`, `.html`, an
image, etc. — convert it first, then read the resulting `.md` file. Don't try
to parse binary formats yourself or write your own extraction code.

## How to use it

Run the bundled script with the file path(s) as arguments. It does everything
in one shot — checks for `markitdown`, installs it if missing, skips files
that are already converted and up to date, runs the conversion, and prints one
status line per file. Don't reason through the install/convert steps yourself
or write shell commands to replicate this — that's what the script is for.

```bash
python3 <skill_dir>/scripts/convert.py path/to/report.docx [more files...]
```

Output is one line per file, prefixed `OK`, `SKIP`, or `FAIL`:

```
OK report.docx -> report.docx.md
SKIP notes.docx.md: up to date
FAIL broken.pdf: <markitdown's error>
```

The converted file is always `<original name>.<original extension>.md` next to
the source (e.g. `report.docx` → `report.docx.md`), matching the extension's
naming exactly. Exit code is `0` if everything converted or was skipped as
up-to-date, `1` if any file failed.

After it prints `OK` or a pre-existing `SKIP`, read the `.md` file (it's the
same path as the source with `.md` appended) to get the content.

## Notes

- First run on a machine without `markitdown` installed will take longer (it
  installs via `uv tool install`, falling back to `pipx`, then `pip3 --user`)
  — this only happens once.
- The source file is never modified or deleted; only the `.md` sibling is written.
- Safe to call on a batch of files in one invocation — pass them all as
  separate arguments rather than looping and invoking the script per file.