Markitdown
ImCa0/just-laws
Convert files and office documents to Markdown. An agent skill from ImCa0/just-laws.
Convert any file or URL to clean Markdown: PDF, DOCX, XLSX, PPTX, HTML, images (OCR), audio, CSV, YouTube.
Install To Markdown
$ npx skills add Mathews-Tom/armory --skill to-markdown -a claude-codeProject install by default; add -g for ~/.claude/skills/.
$ gh skill install Mathews-Tom/armory to-markdown --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/Mathews-Tom/armory.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills/to-markdown .claude/skills/to-markdown && 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 "to-markdown" agent skill from https://github.com/Mathews-Tom/armory/tree/main/skills/to-markdown into .claude/skills/to-markdown/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "to-markdown", 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/Mathews-Tom/armory/tree/main/skills/to-markdownType 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 Mathews-Tom/armory --skill to-markdown -a codexProject install goes to .agents/skills/; add -g for ~/.codex/skills/.
$ gh skill install Mathews-Tom/armory to-markdown --agent codexProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/Mathews-Tom/armory.git skills-src && mkdir -p .agents/skills && cp -r skills-src/skills/to-markdown .agents/skills/to-markdown && rm -rf skills-srcUse ~/.agents/skills/ instead of .agents/skills for a personal install.
Codex skills documentation · loads skills from .agents/skills/
Install the "to-markdown" agent skill from https://github.com/Mathews-Tom/armory/tree/main/skills/to-markdown into .agents/skills/to-markdown/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "to-markdown", 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 Mathews-Tom/armory --skill to-markdown -a cursorProject install goes to .agents/skills/; add -g for ~/.cursor/skills/.
$ gh skill install Mathews-Tom/armory to-markdown --agent cursorProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/Mathews-Tom/armory.git skills-src && mkdir -p .cursor/skills && cp -r skills-src/skills/to-markdown .cursor/skills/to-markdown && 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 "to-markdown" agent skill from https://github.com/Mathews-Tom/armory/tree/main/skills/to-markdown into .cursor/skills/to-markdown/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "to-markdown", 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/Mathews-Tom/armory.git --path skills/to-markdown--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 Mathews-Tom/armory --skill to-markdown -a gemini-cliProject install goes to .agents/skills/; add -g for ~/.gemini/skills/.
$ gh skill install Mathews-Tom/armory to-markdown --agent gemini-cliProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/Mathews-Tom/armory.git skills-src && mkdir -p .gemini/skills && cp -r skills-src/skills/to-markdown .gemini/skills/to-markdown && 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 "to-markdown" agent skill from https://github.com/Mathews-Tom/armory/tree/main/skills/to-markdown into .gemini/skills/to-markdown/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "to-markdown", 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 Mathews-Tom/armory to-markdownInstalls 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 Mathews-Tom/armory --skill to-markdown -a github-copilotProject install goes to .agents/skills/; add -g for ~/.copilot/skills/.
$ git clone --depth 1 https://github.com/Mathews-Tom/armory.git skills-src && mkdir -p .github/skills && cp -r skills-src/skills/to-markdown .github/skills/to-markdown && 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 "to-markdown" agent skill from https://github.com/Mathews-Tom/armory/tree/main/skills/to-markdown into .github/skills/to-markdown/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "to-markdown", 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 Mathews-Tom/armory --skill to-markdown -a opencodeOpenCode documents no install command of its own. Project install goes to .agents/skills/; add -g for ~/.config/opencode/skills/.
$ gh skill install Mathews-Tom/armory to-markdown --agent opencodeProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/Mathews-Tom/armory.git skills-src && mkdir -p .opencode/skills && cp -r skills-src/skills/to-markdown .opencode/skills/to-markdown && 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 "to-markdown" agent skill from https://github.com/Mathews-Tom/armory/tree/main/skills/to-markdown into .opencode/skills/to-markdown/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "to-markdown", 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.
Facts
- Skill name
to-markdown- GitHub stars
- 328
- Token cost
- ~2k tokens
- SKILL.md length
- 722 words
- Files
- 5 (incl. references)
- Skills in repo
- 80
- Repo updated
- First seen
- Licence
- MIT
At a glance
Convert any file or URL to clean Markdown: PDF, DOCX, XLSX, PPTX, HTML, images (OCR), audio, CSV, YouTube.
- Works in 3 steps: Ensure dependencies → Convert → Workflow
- : convert to markdown
- SKILL.md covers Reference Files, Decision Tree, Core Conversion Workflow and Output Conventions, plus 5 more sections
- Calls uv
What it does
To Markdown is an agent skill from Mathews-Tom/armory. Convert any file or URL to clean Markdown: PDF, DOCX, XLSX, PPTX, HTML, images (OCR), audio, CSV, YouTube. Optimised for LLM pipelines. Triggers on: "convert to markdown", "extract text from PDF", "parse this document", "ingest for RAG".
Its SKILL.md is about 2k tokens, which your agent loads only when the skill is triggered. The skill folder holds 6 other files, including reference files (for example `evals/cases.yaml`, `references/fetch.md` and `references/formats.md`).
It sits in Documents & Office, covering Document parsing, Markdown and Word documents. It works with Microsoft Excel, Microsoft PowerPoint, Microsoft Word and YouTube. The repository describes itself as: Curated, production-grade skills for AI coding agents. Battle-tested workflows for developers who use AI seriously. The licence is MIT.
When your agent uses it
- : convert to markdown
- Extract text from PDF
- Parse this document
Example prompts
- “convert to markdown”
- “extract text from PDF”
- “parse this document”
- “/to-markdown”
Requirements
- Python 3
- Node.js
Workflow steps
3 steps, taken from the step headings in SKILL.md.
What it can do on your machine
Read from SKILL.md and the folder at commit 4594fb7. It shows what the files ask for, not the result of running them.
Tool permissions
Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.
From allowed-tools in the SKILL.md frontmatter.
Runs code
Shell commands in SKILL.md call:
uv
From the folder's file list and the shell code blocks in SKILL.md.
Network
Links to these hosts (documentation or services it may open):
github.com
From URLs in SKILL.md, links to its own repository left out.
Credentials
Names no API keys, tokens, secrets or passwords.
From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.
Context cost
To Markdown loads about 2k tokens when it runs, and up to ~4.1k if it reads all its reference files. Until then it costs about 62 tokens; SKILL.md has 722 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.
Safety
Auto-check passed
The automated check found no risky patterns in SKILL.md.
Automated 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); files beside SKILL.md are not scanned.
SKILL.md
The full file from Mathews-Tom/armory at commit 4594fb7, republished under its MIT licence (© Mathews-Tom). 722 words, ~2,038 tokens.
Download SKILL.mdSave it as
.claude/skills/to-markdown/SKILL.md (or your agent's skills folder). This skill also uses 4 other files; get the full folder from GitHub.- name
- to-markdown
- description
- Convert any file or URL to clean Markdown: PDF, DOCX, XLSX, PPTX, HTML, images (OCR), audio, CSV, YouTube. Optimised for LLM pipelines. Triggers on: "convert to markdown", "extract text from PDF", "parse this document", "ingest for RAG".
- metadata.version
- 1.0.1
- metadata.category
- visualization
- metadata.tags
- conversion, markdown, document-ingestion, pdf
- metadata.difficulty
- beginner
To Markdown
Convert any file or URL to clean Markdown using MarkItDown as the conversion engine, with a lightweight fetch layer for URLs.
Reference Files
| File | Purpose |
|---|---|
references/formats.md | Per-format handling notes, internal engines, known gaps |
references/fetch.md | URL fetch layer: trafilatura + Playwright strategies |
references/install.md | Dependency install guide for all variants |
Decision Tree
Determine the input type before touching any tool:
Input type?
Local file path -> markitdown directly
URL
YouTube URL -> markitdown directly (transcript extraction built-in)
Static page -> trafilatura fetch -> markitdown on HTML result
JS-rendered / auth -> Playwright fetch -> markitdown on result
Pasted HTML string -> markitdown directly on stringDo not use web_fetch or WebFetch for URLs — route through the fetch layer described in references/fetch.md to preserve the conversion pipeline.
Core Conversion Workflow
Step 1: Ensure dependencies
uv pip show markitdown || uv pip install 'markitdown[all]' trafilaturaSee references/install.md for selective installs and full dependency table.
Step 2: Convert
from markitdown import MarkItDown
md = MarkItDown(enable_plugins=False)
result = md.convert("path/to/file.pdf")
print(result.text_content)Step 3: Workflow
- Detect input type (file path, URL, raw HTML).
- If URL, run fetch layer first (see
references/fetch.md). - Run markitdown conversion on the local file or fetched content.
- Post-process if needed (strip boilerplate, trim to main content).
- Write output or return inline per output conventions below.
Output Conventions
| Context | Output behaviour |
|---|---|
| Single file, user wants file | Write <input_stem>.md to same directory |
| Single file, inline request | Return Markdown in conversation |
| Batch (multiple files) | Write each to <stem>.md, summarise what was produced |
| URL | Write <slug>.md to current directory or return inline |
| Piped into another workflow | Return result.text_content string only |
Default: "convert this file" -> write a file. "Read this" or "what does this say" -> return inline.
Output Example
Source (two-column PDF with a table):
Annual Report 2024 Financial Highlights
Revenue grew 12% year-over-year... | Metric | 2023 | 2024 |
| Revenue | $4.2B | $4.7B |
| EBITDA | $1.1B | $1.3B |Converted Markdown:
# Annual Report 2024
Revenue grew 12% year-over-year...
## Financial Highlights
| Metric | 2023 | 2024 |
| ------- | ----- | ----- |
| Revenue | $4.2B | $4.7B |
| EBITDA | $1.1B | $1.3B |Multi-column layouts merge into linear flow. Tables are preserved as Markdown tables. Headings are inferred from font size/weight.
LLM Image Description (opt-in)
Markitdown supports an llm_client for image description in PPTX and image files. Never enable by default — it incurs cost, latency, and unexpected API calls. Prompt the user first: "This file contains images. Do you want me to use Claude to describe them? This will make additional API calls."
import anthropic
from markitdown import MarkItDown
client = anthropic.Anthropic()
md = MarkItDown(llm_client=client, llm_model="claude-sonnet-4-6")
result = md.convert("presentation.pptx")Opus 4.7 vision ceiling: Opus 4.7 accepts images up to 2,576 pixels on the long edge (~3.75 MP), roughly 3× prior Claude models. When routing image-heavy documents through
llm_model="claude-opus-4-7", retain higher-resolution source images rather than pre-downsampling — text in screenshots and diagrams that previously required OCR may now be readable directly.
Error Handling
| Severity | Condition | Action |
|---|---|---|
| Terminal | Unsupported format (no converter exists) | Report to user immediately; do not retry |
| Terminal | Password-protected Office file | Report to user; no programmatic workaround |
| Terminal | File not found / path invalid | Report exact path; ask user to verify |
| Recover | Empty output from PDF | Likely scanned — escalate to OCR path in references/formats.md |
| Recover | Missing optional dependency (e.g. playwright) | Install the dependency, then retry the conversion |
| Recover | URL fetch returns paywall page | Report fetch limitation; do not retry or attempt bypass |
| Recover | trafilatura returns empty | Escalate to Playwright fetch strategy per references/fetch.md |
result = md.convert(path)
if not result.text_content.strip():
raise ValueError(f"No text extracted from {path}. See references/formats.md for OCR options.")Never silently return empty Markdown. Surface the failure with the severity and a pointer to the relevant reference file.
Show full SKILL.md (262 more words)Show less
Known Gaps and Escalation
- HTML fidelity: markitdown uses
html2textinternally — complex layouts lose structure. For high-fidelity HTML conversion where DOM structure matters, suggest Turndown via Node subprocess. - Hard paywalls: The fetch layer returns the regwall page, not the content. This is a fetch limitation, not a conversion problem.
- Scanned PDFs (image-only, no text layer): markitdown returns near-empty output. Escalate to OCR workflow (Azure Document Intelligence or Tesseract). See
references/formats.md. - Protected Office files: Password-protected DOCX/XLSX will fail. Inform the user.
Calibration Rules
- Converted output must contain at least 10 words per page of source document. Below this threshold, treat as empty extraction and escalate per the error handling table.
- Tables in the source must appear as Markdown tables in the output — if a table is present in the original but missing in the conversion, flag it to the user.
- Heading hierarchy from the source document must be preserved (H1 > H2 > H3). Flat output with no headings from a structured document indicates a conversion quality issue.
- For URL conversions, output must not contain navigation elements, cookie banners, or footer boilerplate. If present, re-run through trafilatura with
include_tables=Trueto strip boilerplate. - Multi-sheet XLSX must produce one clearly labeled section per sheet. Missing sheets indicate a partial conversion — report which sheets were extracted.
Limitations
- No paywall bypass. Document it, don't attempt it.
- No Turndown integration built-in. Different runtime (Node.js).
- No scheduled/batch crawling. One conversion per invocation.
- No output format other than Markdown.
- Auto-generated YouTube captions may contain errors for technical terms.
- Scanned PDFs require external OCR — markitdown alone returns empty output.
© Mathews-Tom, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file
Files
SKILL.md and 4 other files (references) in skills/to-markdown of Mathews-Tom/armory.
- SKILL.md
- evals/cases.yaml
- references/fetch.md
- references/formats.md
- references/install.md
Open the folder on GitHubat commit 4594fb7
Compare with similar skills
To Markdown 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 |
|---|---|---|---|---|---|---|
| To Markdown this skillMathews-Tom/armory | 328 | — | ~2k | Automated safety check: Pass | MIT | |
| MarkitdownImCa0/just-laws | 782 | 14 repos | ~3.2k | Automated safety check: Notes | MIT | |
| Markdown Converterintellectronica/agent-skills | 295 | 4 repos | ~492 | Automated safety check: Pass | CC0-1.0 | |
| Markitdownjimmc414/Kosmos | 595 | 2 repos | ~1.7k | Automated safety check: Pass | None | |
| Document Converterwentorai/Research-Claw | 858 | — | ~1.3k | Automated safety check: Pass | Custom licence | |
| Learniurykrieger/claude-bedrock | 105 | — | ~6.5k | Automated safety check: Notes | MIT |
Similar skills
Markdown Converter
intellectronica/agent-skills
Convert documents and files to Markdown using markitdown. An agent skill from intellectronica/agent-skills.
Markitdown
jimmc414/Kosmos
Convert various file formats (PDF, Office documents, images, audio, web content, structured data) to Markdown optimized for LLM processing.
Document Converter
wentorai/Research-Claw
Convert Office documents (PPTX, DOCX, XLSX, PDF, HTML, CSV, JSON, XML, images) to Markdown using Microsoft MarkItDown.
Learn
iurykrieger/claude-bedrock
Ingests an external data source into the Second Brain. An agent skill from iurykrieger/claude-bedrock.
Teach
ccplugins/awesome-claude-code-plugins
Teaches the Second Brain to recognize a new external data source.
More from Mathews-Tom/armory
All 80 skills in this repoArchitecture Reviewer
Mathews-Tom/armory
Architecture reviews across 7 dimensions (structural, scalability, enterprise readiness, performance, security, ops, data) with scored reports.
Concept To Image
Mathews-Tom/armory
Turn concepts into static HTML visuals exported as PNG or SVG files via HTML/CSS/SVG.
Watch
Mathews-Tom/armory
A skill your agent uses when analyzing an existing video URL or local recording: "watch this video", "analyze youtube video", "summarize this video", "youtube transcript", "find this moment", "what…
Code Refiner
Mathews-Tom/armory
Deep code simplification and refactoring preserving behavior across Python, Go, TypeScript, Rust.
Concept To Video
Mathews-Tom/armory
Turn concepts into animated explainer videos using Manim (Python) with MP4/GIF output, audio overlay, multi-scene composition.
Decision Map
Mathews-Tom/armory
Maps the unresolved architecture, policy, and scope decisions that must be answered before planning can start: one durable decision ticket per question on the issue tracker, typed and blocker-linked…
Related
Categories
Questions about To Markdown
What does To Markdown do?
Convert any file or URL to clean Markdown: PDF, DOCX, XLSX, PPTX, HTML, images (OCR), audio, CSV, YouTube. To Markdown is an agent skill from Mathews-Tom/armory. Convert any file or URL to clean Markdown: PDF, DOCX, XLSX, PPTX, HTML, images (OCR), audio, CSV, YouTube.
When should I use To Markdown?
To Markdown fits situations like: : convert to markdown; extract text from PDF; parse this document.
How do I install To Markdown in Claude Code?
Run `npx skills add Mathews-Tom/armory --skill to-markdown -a claude-code`. Or copy the skill folder (skills/to-markdown in Mathews-Tom/armory) into .claude/skills/to-markdown in your project. Claude Code loads it when a task matches its description.
How do I install To Markdown in Codex?
Run `npx skills add Mathews-Tom/armory --skill to-markdown -a codex`. Or copy the skill folder (skills/to-markdown in Mathews-Tom/armory) into .agents/skills/to-markdown in your project. Codex loads it when a task matches its description.
Can I use To Markdown in Cursor, Gemini CLI or GitHub Copilot?
Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add Mathews-Tom/armory --skill to-markdown -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/to-markdown, .gemini/skills/to-markdown, .github/skills/to-markdown and .opencode/skills/to-markdown in your project.
What does To Markdown need to run?
Going by SKILL.md and its folder, To Markdown needs the command-line tools its instructions call (uv). Our summary lists: Python 3; Node.js.
Does To Markdown access the network?
SKILL.md names 1 domain. As links in the text: github.com. This is read from the text; nothing was executed.
Is To Markdown safe to install?
Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.
What licence does To Markdown use?
To Markdown is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.
How many tokens does To Markdown use?
About 2k tokens (SKILL.md is roughly 8.2k 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 2k tokens, read only when the agent opens those files.
What are the alternatives to To Markdown?
Skills that share tags, products or a category with To Markdown: Markitdown (ImCa0/just-laws, 782 stars), Markdown Converter (intellectronica/agent-skills, 295 stars), Markitdown (jimmc414/Kosmos, 595 stars) and Document Converter (wentorai/Research-Claw, 858 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.
Who maintains To Markdown?
Mathews-Tom (a GitHub user) maintains it in Mathews-Tom/armory, which has 328 GitHub stars. The repository holds 80 skills in this directory. The repository was last updated on October 6, 2026.
Source: Mathews-Tom/armory on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.