MarkItDown Skill

OpenClaw agent skill for converting documents to Markdown. Documentation and utilities for Microsoft's MarkItDown library. Supports PDF, Word, PowerPoint, Excel, images (OCR), audio (transcription), HTML, YouTube.

Security Scan

The skill is internally consistent: it documents and wraps the publicly published MarkItDown CLI/Python package and provides a small batch helper; nothing in the skill's files requests unrelated credentials or hidden network endpoints.

Purpose & Capability

Name/description align with what is provided: documentation, examples, a small batch script, and a pip install spec for the markitdown CLI. The required binaries (python3, pip, markitdown) and the pip install of markitdown[all] are proportional to the stated purpose.

Instruction Scope

SKILL.md and the included docs stay on-topic (markitdown CLI/API usage). The batch script optionally imports the OpenAI client when an LLM model is requested and the docs reference using an Azure Document Intelligence endpoint (AZURE_DOCUMENT_INTELLIGENCE_KEY). Those LLM/DocInt integrations are optional, but they introduce network calls and use credentials that are not declared in requires.env — the script will attempt to create an OpenAI client if the --llm-model flag is used.

Install Mechanism

The install uses pip to install 'markitdown[all]' which is the expected distribution method. Pip installs execute package setup code and can pull many dependencies (the [all] extras), so installing in a virtualenv is recommended; no downloads from untrusted URLs or extract-from-arbitrary-URL patterns are present in the skill itself.

Credentials

The skill does not require any environment variables by default (none listed), which is fine. However, documentation references optional credentials (e.g., AZURE_DOCUMENT_INTELLIGENCE_KEY and implicit OpenAI credentials used by the openai client). These optional credentials are reasonable for the optional features, but they are not declared in requires.env — users should be aware enabling LLM or Azure features will use those secrets.

Persistence & Privilege

The skill does not request always:true, does not modify other skills or system-wide configs, and contains only a small helper script. It is user-invocable and may be invoked autonomously per platform defaults, which is expected.

Assessment

This skill appears to do what it says: documentation + a small batch conversion helper that relies on the markitdown pip package. Before installing: 1) Verify you're installing the official 'markitdown' package on PyPI (typosquatting is a general pip risk). 2) Install in a Python virtual environment to avoid affecting system packages (python -m venv .venv; source .venv/bin/activate). 3) Only install the extras you need (avoid 'markitdown[all]' if you only need PDFs) to reduce dependency surface. 4) If you enable LLM features (--llm-model) or Azure DocInt, know that those will make network calls and require credentials (OPENAI API key, AZURE_DOCUMENT_INTELLIGENCE_KEY); provide those only to trusted code and review usage. 5) If you need higher assurance, inspect the upstream markitdown PyPI package and its GitHub repo to confirm maintainership and release history before installing.

Documentation and utilities for converting documents to Markdown using Microsoft's 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

# 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:

pip install 'markitdown[all]'

Or install specific formats only:

pip install 'markitdown[pdf,docx,pptx]'

Common Patterns

Fetch Documentation

markitdown https://github.com/user/repo/blob/main/README.md -o readme.md

Convert PDF

markitdown document.pdf -o document.md

Batch Convert

# 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

from markitdown import MarkItDown

md = MarkItDown()
result = md.convert("document.pdf")
print(result.text_content)

Troubleshooting

"markitdown not found"

pip install 'markitdown[all]'

OCR Not Working

# 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 - Detailed examples
• reference.md - Full API reference
• Microsoft MarkItDown - Upstream library