claude-skills/skills/using-markitdown/SKILL.md

name, version, description

name	version	description
using-markitdown	1.0.1	Use when capturing external content into a markdown-based knowledge base, wiki `raw/` directory, or any pipeline that must preserve the source's full text — for web pages, PDFs, DOCX/PPTX/XLSX, EPUB, CSV/JSON/XML, ZIP archives, images (with OCR/EXIF), audio (with transcription), or YouTube URLs. Also use when WebFetch returned an LLM-summarized version but the raw content is what's needed.

using-markitdown

Convert almost any path or URL to plain markdown using Microsoft's markitdown CLI (v0.1.6, on PATH). Returns raw textual content, not an LLM summary.

Tool

markitdown <path|url>            # → markdown to stdout
markitdown <path|url> -o out.md  # → write markdown to a file
cat file.pdf | markitdown        # → read from stdin (use -x/-m to hint the format)

The positional argument accepts a local file path (host path, normal slashes) or an http:// / https:// URL. The CLI runs natively, so it sees your full host filesystem — no Docker mount, no file:// URI translation, no path rewriting.

Useful flags: -o <file> (write to a file instead of stdout), -x <ext> / -m <mime> (format hint when reading from stdin).

Local files

Pass the host path directly — relative or absolute, with native separators:

markitdown C:\Users\vitya\modular\heart-and-mask\.wiki\raw\foo.html -o foo.md

No mount caveats: the CLI is a normal local process. The old Docker -v mount translation and /c:/Users/... [Errno 2] symptom no longer apply.

Filenames. Non-ASCII filenames (Cyrillic, etc.) still travel better as Latin kebab-case through downstream wiki/ingest steps. Rename to Latin kebab-case before saving the output, per .wiki/CLAUDE.md naming rules.

When to use

• Filling a wiki's raw/ directory from a URL or local PDF/DOCX.
• Datasheets, papers, blog posts, GitHub READMEs, Obsidian Web Clipper outputs, KiCad netlist exports — anything where the source text matters and lossy summarization would break later ingest steps.
• Any time the next step is "save the source verbatim before summarizing".

When NOT to use

• You only need a summary or an answer about a page → use WebFetch (cheaper, runs through a small model, returns prose).
• The URI is GitHub/PR/issue/release content → use gh CLI (richer metadata, structured output).
• The URI is private/authenticated (GDocs, Confluence, Jira, Slack, Notion, share.google/* sign-in walls) → markitdown receives the public-facing fallback page (sign-in screen, cookie banner) and returns that as markdown. Verify the result is real content before saving.
• The URI is a browser-rendered web page the user is already viewing → ask the user to capture it via Obsidian Web Clipper (browser extension, runs Readability extraction client-side) and drop the resulting .md into raw/. Web Clipper output is dramatically cleaner than markitdown's HTML pass — no nav chrome, no sidebar history, no cookie banners — plus it carries YAML frontmatter (title / source URL / date) out of the box. Reserves markitdown for things browsers can't easily save (PDF, DOCX, PPTX, XLSX, EPUB, local files). Note: rename the resulting file to Latin kebab-case before ingest (Web Clipper preserves the page <title> verbatim, often non-ASCII).

Pattern: ingest a remote source into a wiki

1. markitdown "https://example.com/foo.pdf" -o .wiki/raw/<slug>.md   (kebab-case, Latin only)
2. Inspect the head of the result. If it looks like a sign-in/cookie/consent page, abort — ask the user for an alternative (manual save, paste, authenticated source).
3. Register the new file in .wiki/raw/README.md.
4. Hand off to the wiki ingest workflow (creates sources/<slug>.md summary + entity/concept updates).

For a huge (book-length) document, write straight to a file with -o and summarize from the saved file — do not pipe the whole markdown through working context.

Common gotchas

Symptom	Cause	Fix
Output is a Google/Microsoft sign-in page in some random language	URI behind auth wall	Ask user to export the content manually (Save as PDF, copy-paste) and put it in raw/
Output is mostly nav/cookie banner text	Site is JS-rendered or anti-bot	Try the cached or print URL; or ask user for HTML export
Output lacks images / diagrams	Markdown is text-only by design	Save the original asset separately under raw/assets/; reference it from the sources/ summary
markitdown: command not found	CLI not on PATH	Confirm with markitdown --version (expect markitdown 0.1.6); install with pip install markitdown[all] if missing
Huge output (book-length)	Whole document converted in one call	Use -o <file> to save raw, then summarize from the saved file — do not hold the entire markdown in working context

Quick contrast with WebFetch and Web Clipper

	markitdown	WebFetch	Obsidian Web Clipper
Returns	raw markdown of the source	LLM answer about the source	Readability-extracted markdown with YAML frontmatter
Use for	PDF / DOCX / non-browser-friendly	one-shot Q&A	any browser-viewable web page
Auth-aware	no	no	yes (uses the user's logged-in browser session)
Chrome / nav stripped	partial (still verbose)	n/a (model picks signal)	yes (clean)
Handles PDFs / DOCX	yes	text-only HTML extraction	no (web pages only)
Who triggers it	Claude	Claude	the user (manual click)