Skip to content
Get packs

Guide · Agent skill

How to use the Convert PDF to Markdown agent skill

Updated · written with AI from the project's own documentation and checked against our catalogue data

The convert-pdf-to-md skill teaches an AI agent to turn a PDF into a Markdown text file before it reads the document. It is for people who regularly ask an agent to summarize reports, papers, invoices or contracts, or who want to process a whole folder of PDFs. By the end of this guide you will know what the skill does, how to install it, how to phrase requests so it triggers, and what it needs to run.

Convert PDF to Markdowngithub/awesome-copilot · MIT

Quick start

  1. 1Download the ZIP. Download the skill ZIP from the item page on this site.
  2. 2Unzip the skill. Unzip it into ~/.claude/skills/ for personal use, or into a project's .claude/skills/ folder.
  3. 3Or upload it in the Claude apps. In the Claude apps, go to Settings, then Capabilities, then Skills, and upload the ZIP.
  4. 4Check Python and pip. Run python --version and python -m pip --version. Python must be 3.10 or newer.
  5. 5Install the dependencies. Follow references/setup.md to install markitdown with PDF support and pymupdf, using the packages in scripts/requirements.txt.
  6. 6Ask for the analysis. Share a PDF and say what you want, such as a summary or specific data. The agent converts the PDF to Markdown first and then answers.

What an agent skill is and what this one does

An agent skill is a folder of instructions and optional scripts that an AI agent can load when a task matches it. This skill covers one job: when you share or mention a .pdf file, the agent first runs a bundled Python script that converts the PDF into Markdown, then reads that Markdown to answer your question.

PDF is a layout format, so its text is not reliably readable as plain text. Converting it first gives the agent cleaner text to work from. The skill is written to tell the agent not to parse the PDF directly or write its own extraction code.

  • Output for each PDF is a folder named after the file, containing a .md file and, if the PDF has embedded images, an img folder.
  • Embedded images are saved as files in img and listed in a Extracted Images section at the end of the Markdown, not placed inline.
  • The skill handles only .pdf files.

Install the skill in Claude

You can install the skill in one of three ways. Download the ZIP from the item page on this site, then either unzip it into your personal skills folder, ~/.claude/skills/, or into a project's .claude/skills/ folder.

Alternatively, upload the ZIP in the Claude apps under Settings, then Capabilities, then Skills.

  • Personal install: unzip into ~/.claude/skills/
  • Project install: unzip into the project's .claude/skills/ folder
  • Claude apps: Settings → Capabilities → Skills, then upload the ZIP

Set up Python and the required packages

The script needs Python 3.10 or newer, pip, the markitdown Python package (Microsoft MarkItDown with PDF support) and pymupdf (PyMuPDF), which is used to extract images. The skill's references/setup.md file lists the exact steps, and the packages are listed in scripts/requirements.txt.

Check your setup with the commands below. If Python is missing, setup.md gives install commands for Windows, macOS and Linux. The agent is told to run setup before the first conversion, and the script will point back to setup.md if a package is missing.

python --version python -m pip --version

Ask for what you want in plain language

You do not need to name the skill. The skill is written to trigger whenever you share, reference or ask about a .pdf file, including requests to read, summarize, review, compare, analyze or extract data from a report, paper, invoice, form, contract or scanned document.

For a folder with several file types, the skill description says the agent should also use the sibling skills convert-word-to-md for .docx files and convert-excel-to-md for .xlsx files. Those are separate skills and must be installed separately.

  • Summarize this PDF: C:\Reports\q3-review.pdf
  • Pull the line items and totals out of this invoice PDF.
  • Compare the methods in these two papers.
  • Process every PDF in the Contracts folder.

Run the conversion script manually

You can also run the script yourself. By default it writes output next to the source file. To choose a destination, pass -o with a folder path. For a whole folder, point the script at the folder, and add --recursive to include subfolders.

In batch mode, each PDF gets its own output folder. If a file fails, the script reports it and the other files still convert. Non-PDF files in the folder are skipped with a note.

  • Single file, default output next to the PDF
  • Single file with a chosen output folder: add -o
  • Whole folder: point at the folder
  • Include subfolders: add --recursive
python scripts\convert_pdf_to_md.py "C:\path\to\document.pdf" python scripts\convert_pdf_to_md.py "C:\path\to\document.pdf" -o "C:\path\to\output_folder" python scripts\convert_pdf_to_md.py "C:\path\to\folder" --recursive

Know the limits and safety notes

The skill does not do OCR. A scanned or image-only PDF has no text layer, so the Markdown body will be empty or nearly empty. The extracted page images may still be useful for viewing.

The script runs locally on the files you point it at, and output is written beside them unless you choose otherwise. The item is marked as using the network, and the skill notes that content from a document is sent to the agent's model for analysis. If a document is confidential, check what your agent setup sends before you share it.

  • Scanned or image-only PDFs will yield little or no text.
  • Images are placed in an appendix, not inline with the text.
  • Do not share sensitive documents unless you are comfortable with their contents being processed and sent to the agent's model.

Troubleshoot common errors

Most errors name the cause directly. A missing module error for markitdown or fitz usually means setup is incomplete. An unsupported file type error means the file is not a .pdf. An input path not found error means the path is wrong or the file has moved.

A FAILED line in batch output means that specific file is corrupt, password-protected or unreadable. The other files in the batch still succeed.

  • ModuleNotFoundError for markitdown or fitz: follow references/setup.md.
  • Unsupported file type: confirm the file is a .pdf, or use the matching sibling skill.
  • Input path not found: confirm the full path.
  • FAILED in batch output: report that file; others still succeed.

What people use it for

  • Summarizing a long research report or paper into key points.
  • Pulling line items, totals or dates out of an invoice or form.
  • Reviewing a contract for specific clauses after converting it to text.
  • Batch converting a folder of PDFs to Markdown for search or a RAG pipeline.
  • Comparing two PDF documents by reading their converted Markdown.

Frequently asked questions

Is the convert-pdf-to-md skill free?

The item is published under the MIT licence, which is a permissive open-source licence. The source does not state any price, so check the item page for current terms.

What do I need to install before using it?

You need Python 3.10 or newer, pip, the markitdown Python package with PDF support, and pymupdf for image extraction. The steps are in references/setup.md, and the packages are listed in scripts/requirements.txt.

How do I install the skill in Claude?

Download the ZIP from the item page, then unzip it into ~/.claude/skills/ or a project's .claude/skills/ folder. You can also upload the ZIP in the Claude apps under Settings, then Capabilities, then Skills.

Does it work on scanned PDFs?

Not well. The skill does not perform OCR, so a scanned PDF with no text layer will produce an empty or nearly empty Markdown body.

Can it convert a whole folder of PDFs?

Yes. Point the script at a folder for batch mode, and add --recursive to include subfolders. Each PDF gets its own output folder, and failed files are reported without stopping the rest.

Where do the converted files go?

By default, the output folder is created next to the source PDF. You can use -o to choose another location, and the skill only does this when you give an explicit path.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Use this skill if you often ask an AI agent to read, summarize or pull data from text-based PDFs, or if you need to convert a folder of them to Markdown. Pick something else if your PDFs are scanned images, since this skill does no OCR, or if you cannot send the document contents to your agent's model.

Download the skill