Converts PDF documents into Markdown files with extracted text, tables, and embedded images for easier analysis.
- GitHub stars
- 41,038
- Files
- 4
- Last commit
- Nov 11, 2026
- License
- MIT
- Allowed tools
- —
What does the convert-pdf-to-md skill do?
convert-pdf-to-md converts PDF documents into Markdown files with extracted text, tables, and embedded images for easier analysis.
Summary generated from the skill's SKILL.md.
About the convert-pdf-to-md skill
Transforming PDF documents into structured Markdown is the primary function of this skill, making it easier for agents to analyze, summarize, or search through complex files. It is designed for developers and users who need to process reports, invoices, contracts, or scanned papers. Instead of attempting to parse PDF layouts directly, the skill runs a conversion script that produces a Markdown file containing extracted text and tables.
To handle visual data, the tool uses PyMuPDF to extract embedded images into a dedicated subfolder. Because precise inline placement is not possible, these images are listed in a specific appendix section at the end of the Markdown file organized by page number. The skill supports both individual file processing and batch operations on entire folders, including recursive searches through subdirectories. When encountering mixed file types like Word or Excel documents in a folder, it is intended to work alongside sibling skills to ensure all data is converted without skipping files.
What an agent can do with it
- 1Summarize a PDF reportConvert a PDF document into Markdown so the agent can accurately summarize its contents.
- 2Batch process a folderProcess every PDF file within a specific directory and its subfolders at once.
- 3Extract tables and imagesPull text, tables, and embedded images from a document for detailed data extraction.
Written from the skill's SKILL.md. Every use case is checked against a quote from it.
How to install the convert-pdf-to-md skill
Each command copies the skill folder into the client's skills directory. Restart the client or start a new session to load it.Install the convert-pdf-to-md skill in Claude Code
~/.claude/skills/convert-pdf-to-md/SKILL.md
$ npx degit github/awesome-copilot/skills/convert-pdf-to-md ~/.claude/skills/convert-pdf-to-mdInstall the convert-pdf-to-md skill in Claude Code (project)
.claude/skills/convert-pdf-to-md/SKILL.md
$ npx degit github/awesome-copilot/skills/convert-pdf-to-md .claude/skills/convert-pdf-to-mdInstall the convert-pdf-to-md skill in Codex
~/.agents/skills/convert-pdf-to-md/SKILL.md
$ npx degit github/awesome-copilot/skills/convert-pdf-to-md ~/.agents/skills/convert-pdf-to-mdInstall the convert-pdf-to-md skill in Gemini CLI
~/.gemini/skills/convert-pdf-to-md/SKILL.md
$ npx degit github/awesome-copilot/skills/convert-pdf-to-md ~/.gemini/skills/convert-pdf-to-mdInstall the convert-pdf-to-md skill in Claude.ai
npx degit github/awesome-copilot/skills/convert-pdf-to-md convert-pdf-to-md && zip -r convert-pdf-to-md.zip convert-pdf-to-md # claude.ai → Customize → Skills → + → Create skill → Upload a skill → convert-pdf-to-md.zip
Automated checks
Ran Nov 15, 2026Full report →Passed our automated checks. That is not a security audit: read the scripts before you let an agent run them. How checks work
- Source repository linked and reachablegithub/awesome-copilot/skills/convert-pdf-to-md is public and reachablegithub.com/github/awesome-copilot/tree/HEAD/skills/convert-p ↗Pass
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit 2026-11-11github.com/github/awesome-copilot/commits ↗Pass
- No download-and-run or credential theft in scripts1 script read; no download-and-run, remote eval, base64 execution or credential uploadPass
- No hidden instructions in SKILL.mdNo override phrases, safeguard switches, credential requests or hidden charactersgithub.com/github/awesome-copilot/blob/HEAD/skills/convert-p ↗Pass
- Pre-approved tools are scopedNo pre-approved tools; the agent asks before using onegithub.com/github/awesome-copilot/blob/HEAD/skills/convert-p ↗Pass
- SKILL.md follows the Agent Skills formatValid name and description; says when to use it; 131 linesgithub.com/github/awesome-copilot/blob/HEAD/skills/convert-p ↗Pass
SKILL.md
View on GitHubConvert PDF to Markdown
When to use this skill
Trigger this skill any time there is a .pdf file that needs to be
understood or processed — for example, a user attaches a PDF and asks
questions about it, wants a summary, wants specific data or tables pulled
out, or wants multiple PDFs in a folder processed together. PDF is a
layout/print format, 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 .pdf — that's MarkItDown's only PDF-family
format, so there's no legacy format to worry about here (unlike Word's
.doc or Excel's .xls).
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 .pdf files. The agent MUST also invoke the sibling
skills in parallel:
convert-word-to-mdfor any.docxfilesconvert-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, markitdown, and pymupdf (for image extraction) 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 a
dependency 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_pdf_to_md.py.
Output structure: MarkItDown's PDF converter extracts text and tables only — it has no concept of embedded images at all. This script separately extracts real embedded images via PyMuPDF and writes a self-contained folder per document:
<name>/
img/
page001_img001.<ext>
page002_img001.<ext>
...
<name>.md
Because MarkItDown's PDF text does not preserve reliable per-page markers,
there's no safe way to know exactly where inline an image belongs. Rather
than risk misplacing images next to the wrong paragraph, the script appends
a ## Extracted Images section at the end of the Markdown, with a
### Page N subheading per page that has images — read this section
separately from the main body text. If the document has no embedded images,
no img/ folder or Extracted Images section is created.
Single file:
python scripts\convert_pdf_to_md.py "C:\path\to\document.pdf"
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_pdf_to_md.py "C:\path\to\document.pdf" -o "C:\path\to\output_folder"
A folder of PDFs (batch mode):
python scripts\convert_pdf_to_md.py "C:\path\to\folder"
Add --recursive to also include subfolders:
python scripts\convert_pdf_to_md.py "C:\path\to\folder" --recursive
Each .pdf 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.
Deciding where output goes
Default — always output next to the source file. The <name>/ folder
is created in the same directory as the source .pdf. 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' or 'fitz' / exit code 2 |
MarkItDown or PyMuPDF not installed | Follow references/setup.md |
ERROR: Unsupported file type '...' / exit code 3 |
Not a .pdf file |
Ask the user for the correct file, or if it's .doc/.docx/.xlsx, use the matching sibling skill instead |
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-.pdf file(s) |
Folder contains non-PDF files | Expected — those files are intentionally ignored |
| Markdown body is empty or near-empty despite images being extracted | The PDF is scanned/image-only with no embedded text layer; MarkItDown does not perform OCR | Tell the user OCR isn't supported — the extracted page images are still available for them to view |
| Images appear in an appendix instead of inline with the text | Deliberate limitation — MarkItDown's PDF text has no reliable per-page markers to place images inline | Expected behavior; cross-reference the ### Page N heading with the surrounding text context if needed |
Files in this skill
4convert-pdf-to-md skill questions
How do I install the convert-pdf-to-md skill in Claude Code?
Run npx degit github/awesome-copilot/skills/convert-pdf-to-md ~/.claude/skills/convert-pdf-to-md. Claude Code loads skills from ~/.claude/skills (all projects) or .claude/skills (one project) and uses a skill when its description matches the task.
Which clients can use the convert-pdf-to-md skill?
Any client that reads the Agent Skills format: Claude Code, Codex, Gemini CLI and claude.ai (upload as a ZIP). Scripts in the skill run only where the client allows code execution.
Does this skill support OCR for scanned PDFs?
No, MarkItDown does not perform OCR. If a PDF is scanned or image-only, the Markdown body may be empty, though extracted page images will still be available.
Where are the converted files saved by default?
The output folder is created in the same directory as the source PDF file.
How are images handled during conversion?
Images are extracted via PyMuPDF and placed in an 'img' folder. Because inline placement is unreliable, they are listed in a '## Extracted Images' section at the end of the Markdown file.
Can I convert a whole folder of PDFs at once?
Yes, you can run the script on a folder, and using the --recursive flag will include all subfolders.