Skip to content
Get packs

Guide · Agent skill

How to use the Markdown Converter agent skill

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

The markdown-converter skill teaches an AI agent to turn common files such as PDFs, Word and PowerPoint documents, spreadsheets, web pages, images, audio recordings and YouTube links into plain Markdown text. This guide is for readers who have not used agent skills before. By the end you will know how to install the skill, ask for a conversion in plain language, and know which settings and privacy trade-offs matter.

Markdown Convertersteipete/agent-scripts · MIT

Quick start

  1. 1Get uv. Make sure uv is installed so the uvx command is available. The skill cannot run without it.
  2. 2Download the skill ZIP. Download the markdown-converter ZIP from this page. It contains SKILL.md.
  3. 3Unzip into a skills folder. Unzip it into ~/.claude/skills/ for personal use, or into .claude/skills/ in a project. Alternatively, upload the ZIP under Settings → Capabilities → Skills in the Claude apps.
  4. 4Ask for a conversion. Name the file or YouTube URL and say what you want, such as a saved .md file. The agent runs uvx --from "markitdown[all]" markitdown.
  5. 5Check the result. Open the output and compare headings, tables and key figures with the original file.

What does the markdown-converter skill make the agent do?

The skill gives the agent a repeatable way to convert files to Markdown, a plain text format that is easy to read, search and pass to other tools. Once installed, the agent can answer questions about a document's contents by converting it first rather than guessing.

It runs the open-source markitdown tool through uvx, so you do not need to install markitdown by hand first. The source says the output preserves document structure such as headings, tables, lists and links.

  • Documents: PDF, Word (.docx), PowerPoint (.pptx), Excel (.xlsx, .xls)
  • Web and data: HTML, CSV, JSON, XML
  • Media: images (EXIF and OCR), audio (EXIF and transcription)
  • Other: ZIP files (iterates contents), YouTube URLs, EPub

How do you install the markdown-converter skill?

Download the skill ZIP from this page. The skill is a folder containing SKILL.md. Then choose one of two routes.

For Claude Code, unzip the skill into your personal skills folder at ~/.claude/skills/, or into a project's .claude/skills/ folder if you want it only for that project. In the Claude apps, you can instead upload the ZIP under Settings → Capabilities → Skills.

  • Personal install: ~/.claude/skills/
  • Project install: .claude/skills/ inside your project

What does the skill need before it runs?

The skill needs uv, which provides the uvx command. It also needs internet access the first time it runs, because the markitdown[all] package is fetched at runtime. If you work offline or on a machine without uv, the skill will not work until those are available.

The Azure Document Intelligence option is optional. It needs an Azure Document Intelligence resource and an endpoint URL.

  • uv (provides the uvx command)
  • Internet access for the first run to fetch markitdown[all]
  • Optional: Azure Document Intelligence resource and endpoint URL for the -d option

How do you trigger the skill with a natural request?

You do not need to type the commands yourself. Ask the agent in plain language, naming the file or link and what you want back. Be specific about the output, for example whether you want a saved .md file or the answer in the chat.

Under the hood, the agent runs commands like the ones below. Basic conversion prints to stdout, -o saves to a file, and stdin input works with a pipe.

  • Try: "Convert report.docx to Markdown and save it as report.md."
  • Try: "Read scan.pdf and tell me the main deadlines in it."
  • Try: "Turn this YouTube link into Markdown text so I can search the transcript."
uvx --from "markitdown[all]" markitdown input.pdf -o output.md

What are the most useful options?

The skill documents several options. Hints help when the input is piped in, because stdin has no file name to read the type from. The -c option fixes text files where charset detection picks the wrong encoding.

  • -o OUTPUT: write to an output file
  • -x EXTENSION: hint the file extension (for stdin)
  • -m MIME_TYPE: hint the MIME type
  • -c CHARSET: hint the charset, e.g. UTF-8
  • -d: use Azure Document Intelligence
  • -e ENDPOINT: Document Intelligence endpoint
  • --use-plugins: enable third-party plugins
  • --list-plugins: show installed plugins
cat document | uvx --from "markitdown[all]" markitdown -x .pdf > output.md

What are the privacy and safety notes?

This skill runs scripts and uses the network. The -d option uploads the file to Microsoft's cloud through Azure Document Intelligence. YouTube and audio features may also reach outside services. Do not use the skill on sensitive or confidential files unless you are comfortable with that.

Markdown also has limits. It loses formatting, and complex PDFs or scans may extract imperfectly. For those cases the skill suggests trying -d with Azure Document Intelligence, which means accepting the upload trade-off.

  • Files sent with -d go to Azure Document Intelligence in the cloud
  • YouTube and audio features may contact external services
  • Pixel-perfect layout is not preserved

What are good tips for better results?

The first run is slower because dependencies are cached and then reused, so later runs are faster. If a text file comes out garbled, pass the known charset with -c, such as UTF-8. When you need reliable text rather than a visual copy, ask the agent to save the output to a .md file and check the important parts against the original.

  • Expect a slower first run while dependencies are cached
  • Pass -c UTF-8 (or the known charset) if text is garbled
  • Use -x or -m when converting piped input
  • Check tables and complex PDFs against the original

What people use it for

  • Turn a Word report into a .md file that can be searched or committed to a repository.
  • Extract the text of a PDF so an AI assistant can answer questions about it.
  • Convert an Excel spreadsheet or CSV into Markdown tables for documentation.
  • Build a pipeline that ingests PowerPoint decks into Markdown for search or LLM context.
  • Get a text transcript of an audio recording or the text from a scanned image.

Frequently asked questions

Is the markdown-converter skill free?

The skill is published under the MIT licence, as stated on this page. The markitdown tool it runs is described in the source as open source. Check the licence files of the tools you use for their exact terms.

Do I need to install markitdown before using this skill?

No. The skill runs markitdown through uvx with the markitdown[all] package, so nothing has to be installed by hand first. The package is fetched on the first run, which requires internet access.

What do I need to run the markdown converter skill?

You need uv, which provides the uvx command, and internet access for the first run. The Azure Document Intelligence resource and endpoint URL are only needed for the optional -d option.

How do I install an agent skill like this one?

Download the ZIP and unzip it into ~/.claude/skills/ for personal use or a project's .claude/skills/ folder. In the Claude apps, upload the ZIP under Settings → Capabilities → Skills.

Can the skill convert scanned PDFs and images?

The skill lists image support with EXIF and OCR, and says PDFs can be extracted with the -d option using Azure Document Intelligence for better results on complex PDFs. Scans may still extract imperfectly, so check the output.

Is it safe to convert confidential documents with this skill?

Use caution. The -d option uploads the file to Microsoft's cloud, and YouTube and audio features may reach outside services. For sensitive files, avoid those options and check what each feature sends before you run it.

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

This skill suits people who need text from PDFs, Office files, spreadsheets, web pages or recordings in a form an AI assistant or pipeline can use, and who can run uv with internet access. Skip it for confidential files you do not want sent to external services, or for jobs that need pixel-perfect layout, since Markdown drops formatting and complex PDFs may extract imperfectly.

Download the skill