feat: add convert-excel-to-md, convert-pdf-to-md, and convert-word-to-md skills (#2294)

* feat: add convert-excel-to-md, convert-pdf-to-md, and convert-word-to-md skills Add three new agent skills that convert common document formats to Markdown using bundled Python scripts powered by MarkItDown: - convert-excel-to-md: Converts .xlsx workbooks to Markdown with per-sheet tables and embedded image extraction via a bundled Python script. - convert-pdf-to-md: Converts .pdf documents to Markdown with text/table extraction and embedded image extraction via PyMuPDF. - convert-word-to-md: Converts .docx documents to Markdown with proper image extraction replacing MarkItDown's base64 placeholders. Each skill includes: - SKILL.md with detailed usage instructions, output structure docs, and a troubleshooting table - scripts/ with the conversion Python script and requirements.txt - references/setup.md with environment setup instructions Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * fix: remove Markdown image syntax from convert-word-to-md SKILL.md The CI valid-refs linter flagged the literal Markdown image syntax containing a data URI as an invalid file reference. Replaced it with a plain text description of the placeholder format. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * fix: update pip install command to use scripts/requirements.txt for setup * fix: clarify installation instructions for requirements-file in setup documentation * fix: correct indentation in image extraction function * Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> * feat: add comprehensive documentation and setup instructions for convert-to-md skills * fix: add trailing slashes to skill paths in plugin.json * fix: reorder skills in plugin.json for consistency * fix: update plugin.json and README.md for clarity and consistency * feat: add convert-to-md plugin and update related documentation * Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> * fix: enhance conversion skills to handle mixed file types and improve error handling --------- Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
2026-07-18 19:51:50 +00:00 · 2026-07-16 07:06:49 +08:00
parent 733c8cd009
commit e4a1f57fd9
17 changed files with 1661 additions and 0 deletions
@@ -0,0 +1,71 @@
+# Environment Setup for convert-pdf-to-md
+
+Follow these steps exactly, in order, before running `scripts/convert_pdf_to_md.py`
+for the first time in a given environment. Don't skip steps or improvise
+alternatives — they're written to be deterministic and safe to re-run.
+
+## 1. Check Python is available (3.10+)
+
+```powershell
+python --version
+```
+
+- If this fails (command not found), install Python 3.10 or newer:
+  - Windows: `winget install --id Python.Python.3.12 -e`
+  - macOS: `brew install python@3.12`
+  - Linux (Debian/Ubuntu): `sudo apt-get update && sudo apt-get install -y python3 python3-pip python-is-python3`
+- If the reported version is older than 3.10, install a newer Python using
+  the same command above (MarkItDown requires 3.10+).
+
+## 2. Check pip is available
+
+```powershell
+python -m pip --version
+```
+
+- If this fails, bootstrap pip:
+
+```powershell
+python -m ensurepip --upgrade
+```
+
+## 3. Install MarkItDown with PDF support, plus PyMuPDF for image extraction
+
+Use the `scripts/requirements.txt` file bundled with this skill to install pinned,
+known-good versions of the dependencies:
+
+```powershell
+python -m pip install -r scripts/requirements.txt
+```
+
+This pulls in `markitdown[pdf]` and `pymupdf>=1.24.0`. PyMuPDF (imported as `fitz`)
+is required separately because MarkItDown's PDF
+converter only extracts text and tables — it has no support for embedded
+images at all, so this skill's script extracts them itself.
+
+## 4. Verify the install
+
+```powershell
+python -c "from markitdown import MarkItDown; import fitz; print('markitdown + pymupdf OK')"
+```
+
+Expect to see `markitdown + pymupdf OK` printed with no errors. If you see a
+`ModuleNotFoundError`, repeat step 3 — pip may be installing into a
+different Python environment than the one being invoked (check
+`python -m pip --version` shows the same path as `python --version`'s
+interpreter).
+
+## Notes
+
+- This setup only needs to be done once per environment/virtual environment,
+  not once per conversion.
+- `convert_pdf_to_md.py` itself also checks for `markitdown` and `fitz` at
+  startup and prints a pointer back to this file if either is missing, so
+  re-running setup is safe and idempotent.
+- Only `.pdf` is supported by this skill — it's MarkItDown's only PDF-family
+  format, so there's no legacy-format equivalent to worry about (unlike
+  Word's `.doc` or Excel's `.xls`).
+- Scanned/image-only PDFs (no embedded text layer) will produce little or
+  no text from MarkItDown, since it does not perform OCR. The images
+  themselves will still be extracted and appended, but the text body may be
+  empty or near-empty in that case — mention this to the user if it happens.