markitdown-skill — Claude Code skill: what it does, how to install
markitdown-skill is a Claude Code skill that converts documents and URLs to Markdown via the markitdown CLI. It extracts text from PDFs, runs OCR on images and transcribes audio files.
Apache-2.0 ★ 108 updated 2026-11-17
npx skills add cjh-solver/MathModeling-Skills-Arsenal --skill markitdown-skill -a claude-codeWhat markitdown-skill does
The skill transforms PDF, Word, PowerPoint, Excel, HTML, YouTube links and web pages into clean Markdown text. It keeps document hierarchies intact, retaining headings, lists, tables and EXIF image metadata.
The repository contains usage guides and a scripts/batch_convert.py helper for bulk file processing. The actual parsing runs through Microsoft's markitdown CLI package or its Python module.
Execution requires Python 3, pip and the package installed via pip install 'markitdown[all]'. Image OCR functionality depends on Tesseract OCR installed on the host system.
What it helps with
- convert Excel spreadsheets and PowerPoint decks to Markdown
- extract structured text from PDF and Word files
- perform OCR text extraction on image files
- transcribe speech from audio recordings or YouTube links
- batch convert document folders using a Python script
Example prompts for the agent
- Convert document.pdf to Markdown and write output to output.md
- Scrape https://example.com/docs and save the content as docs.md
- Run batch conversion on all PDFs in docs/ and output to markdown/
How to install markitdown-skill
1Skills CLI (Vercel)
npx skills add cjh-solver/MathModeling-Skills-Arsenal --skill markitdown-skill -a claude-code2Manually: put the files in place
~/.claude/skills/markitdown-skill/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/markitdown-skill/
1Skills CLI (Vercel)
npx skills add cjh-solver/MathModeling-Skills-Arsenal --skill markitdown-skill -a codex2Manually: put the files in place
.agents/skills/markitdown-skill/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add cjh-solver/MathModeling-Skills-Arsenal --skill markitdown-skill -a cursor2Manually: put the files in place
.cursor/skills/markitdown-skill/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install cjh-solver/MathModeling-Skills-Arsenal skills/05-toolkit/markitdown-skill2Manually: put the files in place
.github/skills/markitdown-skill/SKILL.md1Skills CLI (Vercel)
npx skills add cjh-solver/MathModeling-Skills-Arsenal --skill markitdown-skill -a gemini-cli2Platform CLI
gemini skills install https://github.com/cjh-solver/MathModeling-Skills-Arsenal --path skills/05-toolkit/markitdown-skillManually: put the files in place
.devin/skills/markitdown-skill/SKILL.mdThe legacy .windsurf/skills/ path still works
Claude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about markitdown-skill
How to install markitdown-skill in Claude Code?
Run npx skills add cjh-solver/MathModeling-Skills-Arsenal --skill markitdown-skill -a claude-code. The definition is placed in ~/.claude/skills/markitdown-skill/SKILL.md.
What does markitdown-skill do?
It gives the agent instructions and utilities to convert office documents, images, audio and web links into Markdown using Microsoft's MarkItDown tool.
What is required to run markitdown-skill?
The host system needs Python 3, pip and the Python package via pip install 'markitdown[all]'. Image OCR requires system-level Tesseract OCR.
Source text
SKILL.md · Apache-2.0
---
name: markitdown-skill
description: "Convert documents to Markdown using Microsoft's MarkItDown CLI (`markitdown`). Supports PDF, Word, PowerPoint, Excel, images (OCR), audio (transcription), HTML, YouTube, and URLs. Use when a user wants to convert a file or URL to Markdown, extract text from PDFs/images, transcribe audio/video, or batch-convert documents."
description_zh: "文档转 Markdown(PDF/Word/PPT/图片OCR/音频转写/网页)"
description_en: "Convert documents to Markdown (PDF, Word, PPT, images, audio, URLs)"
version: 1.0.1
homepage: https://github.com/microsoft/markitdown
allowed-tools: Read,Write,Bash,Glob
metadata:
clawdbot:
emoji: "\U0001F4C4"
requires:
bins:
- python3
- pip
- markitdown
install:
- package-manager: pip
command: "pip install 'markitdown[all]'"
display_name: "markitdown-skill"
display_name_en: "markitdown-skill"
visibility: "public"
icon: "https://codebuddy-platform-1258344699.cos.accelerate.myqcloud.com/public/45edac6b-2078-4678-89f3-6f9800cf5e5f/avatar/skill/au_78915a1e-864.png"
---
# MarkItDown Skill
Documentation and utilities for converting documents to Markdown using Microsoft's [MarkItDown](https://github.com/microsoft/markitdown) library.
> **Note:** This skill provides documentation and a batch script. The actual conversion is done by the `markitdown` CLI/library installed via pip.
## When to Use
**Use markitdown for:**
- 📄 Fetching documentation (README, API docs)
- 🌐 Converting web pages to markdown
- 📝 Document analysis (PDFs, Word, PowerPoint)
- 🎬 YouTube transcripts
- 🖼️ Image text extraction (OCR)
- 🎤 Audio transcription
## Quick Start
```bash
# Convert file to markdown
markitdown document.pdf -o output.md
# Convert URL
markitdown https://example.com/docs -o docs.md
```
## Supported Formats
| Format | Features |
|--------|----------|
| PDF | Text extraction, structure |
| Word (.docx) | Headings, lists, tables |
| PowerPoint | Slides, text |
| Excel | Tables, sheets |
| Images | OCR + EXIF metadata |
| Audio | Speech transcription |
| HTML | Structure preservation |
| YouTube | Video transcription |
## Installation
The skill requires Microsoft's `markitdown` CLI:
```bash
pip install 'markitdown[all]'
```
Or install specific formats only:
```bash
pip install 'markitdown[pdf,docx,pptx]'
```
## Common Patterns
### Fetch Documentation
```bash
markitdown https://github.com/user/repo/blob/main/README.md -o readme.md
```
### Convert PDF
```bash
markitdown document.pdf -o document.md
```
### Batch Convert
```bash
# Using included script
python ~/.openclaw/skills/markitdown/scripts/batch_convert.py docs/*.pdf -o markdown/ -v
# Or shell loop
for file in docs/*.pdf; do
markitdown "$file" -o "${file%.pdf}.md"
done
```
## Python API
```python
from markitdown import MarkItDown
md = MarkItDown()
result = md.convert("document.pdf")
print(result.text_content)
```
## Troubleshooting
### "markitdown not found"
```bash
pip install 'markitdown[all]'
```
### OCR Not Working
```bash
# Ubuntu/Debian
sudo apt-get install tesseract-ocr
# macOS
brew install tesseract
```
## What This Skill Provides
| Component | Source |
|-----------|--------|
| `markitdown` CLI | Microsoft's pip package |
| `markitdown` Python API | Microsoft's pip package |
| `scripts/batch_convert.py` | This skill (utility) |
| Documentation | This skill |
## See Also
- [USAGE-GUIDE.md](references/USAGE-GUIDE.md) - Detailed examples
- [reference.md](references/reference.md) - Full API reference
- [Microsoft MarkItDown](https://github.com/microsoft/markitdown) - Upstream library
© cjh-solver · Apache-2.0 · cjh-solver/MathModeling-Skills-Arsenal