Markitdown
jimmc414/Kosmos
Convert various file formats (PDF, Office documents, images, audio, web content, structured data) to Markdown optimized for LLM processing.
Convert files and office documents to Markdown. An agent skill from ImCa0/just-laws.
$ npx skills add ImCa0/just-laws --skill markitdown -a claude-codeProject install by default; add -g for ~/.claude/skills/.
$ gh skill install ImCa0/just-laws markitdown --agent claude-codeProject scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).
$ git clone --depth 1 https://github.com/ImCa0/just-laws.git skills-src && mkdir -p .claude/skills && cp -r skills-src/.agents/skills/markitdown .claude/skills/markitdown && rm -rf skills-srcUse ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.
Claude Code skills documentation · loads skills from .claude/skills/
Install the "markitdown" agent skill from https://github.com/ImCa0/just-laws/tree/master/.agents/skills/markitdown into .claude/skills/markitdown/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "markitdown", then confirm the skill loads.Claude Code copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$skill-installer install https://github.com/ImCa0/just-laws/tree/master/.agents/skills/markitdownType this inside Codex. $skill-installer <name> installs a curated skill from openai/skills. The installer writes to $CODEX_HOME/skills (default ~/.codex/skills). Restart Codex if the skill does not show up.
$ npx skills add ImCa0/just-laws --skill markitdown -a codexProject install goes to .agents/skills/; add -g for ~/.codex/skills/.
$ gh skill install ImCa0/just-laws markitdown --agent codexProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/ImCa0/just-laws.git skills-src && mkdir -p .agents/skills && cp -r skills-src/.agents/skills/markitdown .agents/skills/markitdown && rm -rf skills-srcUse ~/.agents/skills/ instead of .agents/skills for a personal install.
Codex skills documentation · loads skills from .agents/skills/
Install the "markitdown" agent skill from https://github.com/ImCa0/just-laws/tree/master/.agents/skills/markitdown into .agents/skills/markitdown/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "markitdown", then confirm the skill loads.Codex copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ npx skills add ImCa0/just-laws --skill markitdown -a cursorProject install goes to .agents/skills/; add -g for ~/.cursor/skills/.
$ gh skill install ImCa0/just-laws markitdown --agent cursorProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/ImCa0/just-laws.git skills-src && mkdir -p .cursor/skills && cp -r skills-src/.agents/skills/markitdown .cursor/skills/markitdown && rm -rf skills-srcUse ~/.cursor/skills/ instead of .cursor/skills for a personal install.
Cursor skills documentation · loads skills from .cursor/skills/, .agents/skills/, .claude/skills/, .codex/skills/
Install the "markitdown" agent skill from https://github.com/ImCa0/just-laws/tree/master/.agents/skills/markitdown into .cursor/skills/markitdown/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "markitdown", then confirm the skill loads.Cursor copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ gemini skills install https://github.com/ImCa0/just-laws.git --path .agents/skills/markitdown--scope user (default) or --scope workspace; --path is the subfolder of the repo that holds the skill; --consent skips the security confirmation prompt.
$ npx skills add ImCa0/just-laws --skill markitdown -a gemini-cliProject install goes to .agents/skills/; add -g for ~/.gemini/skills/.
$ gh skill install ImCa0/just-laws markitdown --agent gemini-cliProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/ImCa0/just-laws.git skills-src && mkdir -p .gemini/skills && cp -r skills-src/.agents/skills/markitdown .gemini/skills/markitdown && rm -rf skills-srcUse ~/.gemini/skills/ instead of .gemini/skills for a personal install, then run /skills reload.
Gemini CLI skills documentation · loads skills from .gemini/skills/, .agents/skills/
Install the "markitdown" agent skill from https://github.com/ImCa0/just-laws/tree/master/.agents/skills/markitdown into .gemini/skills/markitdown/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "markitdown", then confirm the skill loads.Gemini CLI copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ gh skill install ImCa0/just-laws markitdownInstalls for Copilot at project scope by default; add --scope user for a personal install. Preview a skill first with gh skill preview. Needs GitHub CLI 2.90.0 or later (public preview).
$ npx skills add ImCa0/just-laws --skill markitdown -a github-copilotProject install goes to .agents/skills/; add -g for ~/.copilot/skills/.
$ git clone --depth 1 https://github.com/ImCa0/just-laws.git skills-src && mkdir -p .github/skills && cp -r skills-src/.agents/skills/markitdown .github/skills/markitdown && rm -rf skills-srcUse ~/.copilot/skills/ instead of .github/skills for a personal install. Commit .github/skills so cloud agent and code review can use it.
GitHub Copilot skills documentation · loads skills from .github/skills/, .claude/skills/, .agents/skills/
Install the "markitdown" agent skill from https://github.com/ImCa0/just-laws/tree/master/.agents/skills/markitdown into .github/skills/markitdown/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "markitdown", then confirm the skill loads.GitHub Copilot copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ npx skills add ImCa0/just-laws --skill markitdown -a opencodeOpenCode documents no install command of its own. Project install goes to .agents/skills/; add -g for ~/.config/opencode/skills/.
$ gh skill install ImCa0/just-laws markitdown --agent opencodeProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/ImCa0/just-laws.git skills-src && mkdir -p .opencode/skills && cp -r skills-src/.agents/skills/markitdown .opencode/skills/markitdown && rm -rf skills-srcUse ~/.config/opencode/skills/ instead of .opencode/skills for a personal install.
OpenCode skills documentation · loads skills from .opencode/skills/, .claude/skills/, .agents/skills/
Install the "markitdown" agent skill from https://github.com/ImCa0/just-laws/tree/master/.agents/skills/markitdown into .opencode/skills/markitdown/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "markitdown", then confirm the skill loads.OpenCode copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
markitdownConvert files and office documents to Markdown. An agent skill from ImCa0/just-laws.
Markitdown is an agent skill from ImCa0/just-laws. Convert files and office documents to Markdown. Supports PDF, DOCX, PPTX, XLSX, images (with OCR), audio (with transcription), HTML, CSV, JSON, XML, ZIP, YouTube URLs, EPubs and more.
Its SKILL.md is about 3.2k tokens, which your agent loads only when the skill is triggered. The skill folder holds 15 other files, including scripts, reference files and assets (for example `INSTALLATION_GUIDE.md`, `OPENROUTER_INTEGRATION.md` and `QUICK_REFERENCE.md`).
It sits in Documents & Office, covering Document parsing, PowerPoint presentations and Transcription. It works with MarkItDown, Microsoft PowerPoint, Microsoft Excel and YouTube. The repository describes itself as: 一个简洁、便捷的中国法律文库 | A Simple and Convenient Laws Library of China. The licence is MIT.
12 steps, taken from the step headings in SKILL.md.
Read from SKILL.md and the folder at commit b947e4e. It shows what the files ask for, not the result of running them.
Pre-approves these tools, so the agent can use them without asking each time:
ReadWriteEditBashFrom allowed-tools in the SKILL.md frontmatter.
Ships 3 files in scripts/ (Python), which the agent can run.
Shell commands in SKILL.md call:
markitdownpipdockerpythongitbrewapt-getFrom the folder's file list and the shell code blocks in SKILL.md.
Hosts in commands or code, which the agent is likely to contact:
openrouter.aigithub.comyoutube.comAlso links to:
pypi.orgFrom URLs in SKILL.md, links to its own repository left out.
Names no API keys, tokens, secrets or passwords.
From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.
Markitdown loads about 3.2k tokens when it runs, and up to ~7.7k if it reads all its reference files. Until then it costs about 49 tokens; SKILL.md has 601 words of instructions outside code blocks.
Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.
The automated check noted patterns worth knowing about, such as sudo or a known installer.
sudo apt-get install tesseract-ocrallowed-tools: Read, Write, Edit, BashAutomated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); the scripts in this folder are not scanned.
The full file from ImCa0/just-laws at commit b947e4e, republished under its MIT licence (© ImCa0). 601 words, ~3,160 tokens.
.claude/skills/markitdown/SKILL.md (or your agent's skills folder). This skill also uses 12 other files; get the full folder from GitHub.MarkItDown is a Python tool developed by Microsoft for converting various file formats to Markdown. It's particularly useful for converting documents into LLM-friendly text format, as Markdown is token-efficient and well-understood by modern language models.
Key Benefits:
When creating documents with this skill, always consider adding scientific diagrams and schematics to enhance visual communication.
If your document does not already contain schematics or diagrams:
For new documents: Scientific schematics should be generated by default to visually represent key concepts, workflows, architectures, or relationships described in the text.
How to generate schematics:
python scripts/generate_schematic.py "your diagram description" -o figures/output.pngThe AI will automatically:
When to add schematics:
For detailed guidance on creating schematics, refer to the scientific-schematics skill documentation.
| Format | Description | Notes |
|---|---|---|
| Portable Document Format | Full text extraction | |
| DOCX | Microsoft Word | Tables, formatting preserved |
| PPTX | PowerPoint | Slides with notes |
| XLSX | Excel spreadsheets | Tables and data |
| Images | JPEG, PNG, GIF, WebP | EXIF metadata + OCR |
| Audio | WAV, MP3 | Metadata + transcription |
| HTML | Web pages | Clean conversion |
| CSV | Comma-separated values | Table format |
| JSON | JSON data | Structured representation |
| XML | XML documents | Structured format |
| ZIP | Archive files | Iterates contents |
| EPUB | E-books | Full text extraction |
| YouTube | Video URLs | Fetch transcriptions |
# Install with all features
pip install 'markitdown[all]'
# Or from source
git clone https://github.com/microsoft/markitdown.git
cd markitdown
pip install -e 'packages/markitdown[all]'# Basic conversion
markitdown document.pdf > output.md
# Specify output file
markitdown document.pdf -o output.md
# Pipe content
cat document.pdf | markitdown > output.md
# Enable plugins
markitdown --list-plugins # List available plugins
markitdown --use-plugins document.pdf -o output.mdfrom markitdown import MarkItDown
# Basic usage
md = MarkItDown()
result = md.convert("document.pdf")
print(result.text_content)
# Convert from stream
with open("document.pdf", "rb") as f:
result = md.convert_stream(f, file_extension=".pdf")
print(result.text_content)Use LLMs via OpenRouter to generate detailed image descriptions (for PPTX and image files):
from markitdown import MarkItDown
from openai import OpenAI
# Initialize OpenRouter client (OpenAI-compatible API)
client = OpenAI(
api_key="your-openrouter-api-key",
base_url="https://openrouter.ai/api/v1"
)
md = MarkItDown(
llm_client=client,
llm_model="anthropic/claude-sonnet-4.5", # recommended for scientific vision
llm_prompt="Describe this image in detail for scientific documentation"
)
result = md.convert("presentation.pptx")
print(result.text_content)For enhanced PDF conversion with Microsoft Document Intelligence:
# Command line
markitdown document.pdf -o output.md -d -e "<document_intelligence_endpoint>"# Python API
from markitdown import MarkItDown
md = MarkItDown(docintel_endpoint="<document_intelligence_endpoint>")
result = md.convert("complex_document.pdf")
print(result.text_content)MarkItDown supports 3rd-party plugins for extending functionality:
# List installed plugins
markitdown --list-plugins
# Enable plugins
markitdown --use-plugins file.pdf -o output.mdFind plugins on GitHub with hashtag: #markitdown-plugin
Control which file formats you support:
# Install specific formats
pip install 'markitdown[pdf, docx, pptx]'
# All available options:
# [all] - All optional dependencies
# [pptx] - PowerPoint files
# [docx] - Word documents
# [xlsx] - Excel spreadsheets
# [xls] - Older Excel files
# [pdf] - PDF documents
# [outlook] - Outlook messages
# [az-doc-intel] - Azure Document Intelligence
# [audio-transcription] - WAV and MP3 transcription
# [youtube-transcription] - YouTube video transcriptionfrom markitdown import MarkItDown
md = MarkItDown()
# Convert PDF paper
result = md.convert("research_paper.pdf")
with open("paper.md", "w") as f:
f.write(result.text_content)from markitdown import MarkItDown
md = MarkItDown()
result = md.convert("data.xlsx")
# Result will be in Markdown table format
print(result.text_content)from markitdown import MarkItDown
import os
from pathlib import Path
md = MarkItDown()
# Process all PDFs in a directory
pdf_dir = Path("papers/")
output_dir = Path("markdown_output/")
output_dir.mkdir(exist_ok=True)
for pdf_file in pdf_dir.glob("*.pdf"):
result = md.convert(str(pdf_file))
output_file = output_dir / f"{pdf_file.stem}.md"
output_file.write_text(result.text_content)
print(f"Converted: {pdf_file.name}")from markitdown import MarkItDown
from openai import OpenAI
# Use OpenRouter for access to multiple AI models
client = OpenAI(
api_key="your-openrouter-api-key",
base_url="https://openrouter.ai/api/v1"
)
md = MarkItDown(
llm_client=client,
llm_model="anthropic/claude-sonnet-4.5", # recommended for presentations
llm_prompt="Describe this slide image in detail, focusing on key visual elements and data"
)
result = md.convert("presentation.pptx")
with open("presentation.md", "w") as f:
f.write(result.text_content)from markitdown import MarkItDown
from pathlib import Path
md = MarkItDown()
# Files to convert
files = [
"document.pdf",
"spreadsheet.xlsx",
"presentation.pptx",
"notes.docx"
]
for file in files:
try:
result = md.convert(file)
output = Path(file).stem + ".md"
with open(output, "w") as f:
f.write(result.text_content)
print(f"✓ Converted {file}")
except Exception as e:
print(f"✗ Error converting {file}: {e}")from markitdown import MarkItDown
md = MarkItDown()
# Convert YouTube video to transcript
result = md.convert("https://www.youtube.com/watch?v=VIDEO_ID")
print(result.text_content)# Build image
docker build -t markitdown:latest .
# Run conversion
docker run --rm -i markitdown:latest < ~/document.pdf > output.mdMarkItDown()from markitdown import MarkItDown
md = MarkItDown()
try:
result = md.convert("document.pdf")
print(result.text_content)
except FileNotFoundError:
print("File not found")
except Exception as e:
print(f"Conversion error: {e}")from markitdown import MarkItDown
md = MarkItDown()
# For large files, use streaming
with open("large_file.pdf", "rb") as f:
result = md.convert_stream(f, file_extension=".pdf")
# Process in chunks or save directly
with open("output.md", "w") as out:
out.write(result.text_content)Markdown output is already token-efficient, but you can:
from markitdown import MarkItDown
import re
md = MarkItDown()
result = md.convert("document.pdf")
# Clean up extra whitespace
clean_text = re.sub(r'\n{3,}', '\n\n', result.text_content)
clean_text = clean_text.strip()
print(clean_text)from markitdown import MarkItDown
from pathlib import Path
md = MarkItDown()
# Convert all papers in literature folder
papers_dir = Path("literature/pdfs")
output_dir = Path("literature/markdown")
output_dir.mkdir(exist_ok=True)
for paper in papers_dir.glob("*.pdf"):
result = md.convert(str(paper))
# Save with metadata
output_file = output_dir / f"{paper.stem}.md"
content = f"# {paper.stem}\n\n"
content += f"**Source**: {paper.name}\n\n"
content += "---\n\n"
content += result.text_content
output_file.write_text(content)
# For AI-enhanced conversion with figures
from openai import OpenAI
client = OpenAI(
api_key="your-openrouter-api-key",
base_url="https://openrouter.ai/api/v1"
)
md_ai = MarkItDown(
llm_client=client,
llm_model="anthropic/claude-sonnet-4.5",
llm_prompt="Describe scientific figures with technical precision"
)from markitdown import MarkItDown
import re
md = MarkItDown()
result = md.convert("data_tables.xlsx")
# Markdown tables can be parsed or used directly
print(result.text_content)Missing dependencies: Install feature-specific packages
pip install 'markitdown[pdf]' # For PDF supportBinary file errors: Ensure files are opened in binary mode
with open("file.pdf", "rb") as f: # Note the "rb"
result = md.convert_stream(f, file_extension=".pdf")OCR not working: Install tesseract
# macOS
brew install tesseract
# Ubuntu
sudo apt-get install tesseract-ocrreferences/api_reference.md for complete API documentationreferences/file_formats.md for format-specific detailsscripts/batch_convert.py for automation examplesscripts/convert_with_ai.py for AI-enhanced conversionspackages/markitdown-sample-plugin© ImCa0, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file
SKILL.md and 12 other files (scripts, references, assets) in .agents/skills/markitdown of ImCa0/just-laws.
Open the folder on GitHubat commit b947e4e
We found 19 copies of this SKILL.md (exact, near-identical or edited) in other folders, from 14 other GitHub owners. This page covers the copy in ImCa0/just-laws, which our catalogue first saw on October 7, 2026.
Markitdown next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.
| Skill | Stars | Used in | Tokens | Auto-check | Licence | Repo updated |
|---|---|---|---|---|---|---|
| Markitdown this skillImCa0/just-laws | 781 | 14 repos | ~3.2k | Automated safety check: Notes | MIT | |
| Markitdownjimmc414/Kosmos | 594 | 2 repos | ~1.7k | Automated safety check: Pass | None | |
| Markdown Converterintellectronica/agent-skills | 295 | 4 repos | ~492 | Automated safety check: Pass | CC0-1.0 | |
| To MarkdownMathews-Tom/armory | 328 | — | ~2k | Automated safety check: Pass | MIT | |
| Markdown ConverterTeam-Commonly/commonly | 1.4k | — | ~557 | Automated safety check: Pass | Apache-2.0 | |
| Document Converterwentorai/Research-Claw | 858 | — | ~1.3k | Automated safety check: Pass | Custom licence |
jimmc414/Kosmos
Convert various file formats (PDF, Office documents, images, audio, web content, structured data) to Markdown optimized for LLM processing.
intellectronica/agent-skills
Convert documents and files to Markdown using markitdown. An agent skill from intellectronica/agent-skills.
Mathews-Tom/armory
Convert any file or URL to clean Markdown: PDF, DOCX, XLSX, PPTX, HTML, images (OCR), audio, CSV, YouTube.
Team-Commonly/commonly
Convert binary documents (PDF, DOCX, XLSX, PPTX, HTML, EPUB, images) to clean LLM-friendly Markdown using Microsoft's markitdown Python tool.
wentorai/Research-Claw
Convert Office documents (PPTX, DOCX, XLSX, PDF, HTML, CSV, JSON, XML, images) to Markdown using Microsoft MarkItDown.
BlackBeltTechnology/pi-agent-dashboard
Convert documents bidirectionally via the pi-doc-engine facade: ingest PDF/DOCX/PPTX/XLSX to provenance-stamped Markdown (with OCR), and produce templated DOCX/PDF from Markdown with diagrams, TOC…
ImCa0/just-laws
默认法律收录与更新流程:将 .temp/lawsmd 中的法律 Markdown 规范化为 Just Laws VuePress 站点交付件,可配对读取 Word 原件,同步 category、sidebar 与 LAWSPROGRESS.md;更新已有法律时识别当前、未来和历史版本,维护 versions.json、多版本页面及生效日轮换。
ImCa0/just-laws
已弃用的旧法律手工收录入口;默认改用 law-pipeline。
Categories
Convert files and office documents to Markdown. An agent skill from ImCa0/just-laws. Markitdown is an agent skill from ImCa0/just-laws. Convert files and office documents to Markdown.
Markitdown fits situations like: tasks that involve Document parsing; tasks that involve PowerPoint presentations; tasks that involve Transcription.
Run `npx skills add ImCa0/just-laws --skill markitdown -a claude-code`. Or copy the skill folder (.agents/skills/markitdown in ImCa0/just-laws) into .claude/skills/markitdown in your project. Claude Code loads it when a task matches its description.
Run `npx skills add ImCa0/just-laws --skill markitdown -a codex`. Or copy the skill folder (.agents/skills/markitdown in ImCa0/just-laws) into .agents/skills/markitdown in your project. Codex loads it when a task matches its description.
Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add ImCa0/just-laws --skill markitdown -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/markitdown, .gemini/skills/markitdown, .github/skills/markitdown and .opencode/skills/markitdown in your project.
Going by SKILL.md and its folder, Markitdown needs Python for the scripts in its folder and the command-line tools its instructions call (markitdown, pip, docker, python, git and brew). Our summary lists: Python 3; Docker. Its frontmatter pre-approves these tools: Read, Write, Edit, Bash.
SKILL.md names 4 domains. In commands or code: openrouter.ai, github.com and youtube.com; the agent is likely to contact these when it follows the instructions. As links in the text: pypi.org. This is read from the text; nothing was executed.
Our automated static check of SKILL.md found notes only (runs commands with sudo; pre-approves every shell command (allowed-tools: bash)), nothing it rates as a warning. It is not a guarantee. The check reads SKILL.md only: the scripts in the folder are not scanned, so read them before running anything.
Markitdown is published under the MIT licence (declared in SKILL.md). It allows redistribution, so the full SKILL.md is shown on this page.
About 3.2k tokens (SKILL.md is roughly 13k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full. Its references folder adds about 4.5k tokens, read only when the agent opens those files.
Skills that share tags, products or a category with Markitdown: Markitdown (jimmc414/Kosmos, 594 stars), Markdown Converter (intellectronica/agent-skills, 295 stars), To Markdown (Mathews-Tom/armory, 328 stars) and Markdown Converter (Team-Commonly/commonly, 1.4k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.
ImCa0 (a GitHub user) maintains it in ImCa0/just-laws, which has 781 GitHub stars. The repository holds 3 skills in this directory. The repository was last updated on October 7, 2026.
Source: ImCa0/just-laws on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.