to-markdown
Skill340 starsChanged 8 months agoMITView on GitHub
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".
- Installs packages
2 other projects use a version of this.
Adopted by
Most recently taken up by
- mckayqsnell/snell-skillstheir own version, first seen Nov 1, 2026
- bmad-labs/skillstheir own version, first seen Oct 13, 2026
Other versions2 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 2
- bmad-labs/skills★ 19same name
- mckayqsnell/snell-skills★ 2same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository94 other files it gives its agents.
- AGENTS.mdAGENTS.md
- adr-writerSkill
- agent-builderSkill
- animateSkill
- api-docs-generatorSkill
- appraiseSkill
- architecture-diagramSkill
- architecture-reviewerSkill
- arxiv-figuresSkill
- arxiv-packageSkill
- arxiv-preflightSkill
- benchmark-runnerSkill
- changelog-composerSkill
- chart-claritySkill
- citation-auditSkill
- codebase-advisorSkill
- code-refinerSkill
- competitive-analyzerSkill
- concept-to-imageSkill
- debug-investigatorSkill
- decision-mapSkill
- dependency-auditSkill
- devils-advocateSkill
- domain-modelingSkill
- engineering-retroSkill
- env-validatorSkill
- estimate-calibratorSkill
- feasibility-assessorSkill
- figure-rhetoricSkill
- figure-table-qualitySkill
- filesystemSkill
- githubSkill
- gpu-optimizerSkill
- handoffSkill
- html-presentationSkill
- html-videoSkill
- humanizeSkill
- idea-validatorSkill
- immuneSkill
- intakeSkill
- kg-builderSkill
- launch-videoSkill
- learning-workspaceSkill
- lightpanda-browserSkill
- linkedin-post-styleSkill
- literature-reviewSkill
- manuscript-provenanceSkill
- manuscript-reviewSkill
- manuscript-typographySkill
- market-analyzerSkill
- marp-slidesSkill
- mcp-to-skillSkill
- md-to-pdfSkill
- migration-risk-analyzerSkill
- milestone-runnerSkill
- module-deepeningSkill
- notebooklmSkill
- package-evaluatorSkill
- package-optimizerSkill
- paper-to-skillSkill
- The first 60 shown.
The file
We split this skill into the rules it gives an agent
10 rules. About 0 are common, 7 are distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈7
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 37
Do not use web_fetch or WebFetch for URLs — route through the fetch layer described in references/fetch.md to preserve the conversion …
- Very specific: line 62
If URL, run fetch layer first (see references/fetch.md).
- Distinctive: line 63
Run markitdown conversion on the local file or fetched content.
- Distinctive: line 65
Write output or return inline per output conventions below.
- Distinctive: line 77
Default: "convert this file" -> write a file.
- Distinctive: line 140
Never silently return empty Markdown.
- Distinctive: line 159
No paywall bypass. Document it, don't attempt it.
- Very specific: line 160
No Turndown integration built-in.
- Distinctive: line 161
No scheduled/batch crawling.
- Distinctive: line 162
No output format other than Markdown.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
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.
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.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

