Agent-Skills.md

Agent Skills: convert-to-md

Convert documents to Markdown. PDFs go through the LlamaParse API (best quality, costs credits, tier selectable) or a local PyMuPDF engine (free, offline, no API key); other formats (DOCX, PPTX, XLSX, HTML, EPUB) are converted locally with markitdown.

UncategorizedID: garg-aayush/tutorials/convert-to-md

Repository

garg-aayush/tutorials
garg-aayushLicense: Apache-2.0
93

Install this agent skill to your local

pnpm dlx add-skill https://github.com/garg-aayush/handbook/tree/HEAD/.claude/skills/convert-to-md

Skill Files

Browse the full folder contents for convert-to-md.

Download Skill

Loading file tree…

.claude/skills/convert-to-md/SKILL.md

Skill Metadata

Name
convert-to-md
Description
Convert documents to Markdown. PDFs go through the LlamaParse API (best quality, costs credits, tier selectable) or a local PyMuPDF engine (free, offline, no API key); other formats (DOCX, PPTX, XLSX, HTML, EPUB) are converted locally with markitdown.

convert-to-md

Convert documents to Markdown. The bundled PDF scripts carry PEP 723 inline metadata, so uv handles the Python environment automatically; no venv needed.

Choosing an engine

  • PDF, best quality (parse_pdf.py): default for PDFs. Strongest on scanned pages, tables, multi-column, and complex layouts. Needs LLAMA_CLOUD_API_KEY and consumes credits.
  • PDF, local (parse_pdf_local.py): use when the user says "free", "local", "offline", "without the API", when the document is sensitive and must not leave the machine, or when credits are a concern. Good on digitally-born PDFs; weaker on scans (no OCR) and complex layouts.
  • Non-PDF formats (markitdown): DOCX, PPTX, XLSX, HTML, EPUB, and more, converted locally. Basic conversion quality; fine for text-centric documents.

Preconditions

LlamaParse engine only: LLAMA_CLOUD_API_KEY must be set. It is exported from ~/.zshrc, which the shell inherits automatically. If the script reports a missing key, ask the user to check that export. The local engines need nothing.

How to run

# PDF via LlamaParse (default for PDFs)
uv run ${CLAUDE_SKILL_DIR}/scripts/parse_pdf.py <inputs...> [flags]

# PDF locally, free, offline
uv run ${CLAUDE_SKILL_DIR}/scripts/parse_pdf_local.py <inputs...> [--out DIR] [--images]

# Non-PDF formats
uvx markitdown input.docx -o output.md

Inputs (PDF scripts)

  • Single file: .../parse_pdf.py /path/to/file.pdf
  • Glob: .../parse_pdf.py ~/Downloads/*.pdf
  • Directory (recursive): .../parse_pdf.py ./pdf/

markitdown takes one input file per call; loop over files for batches.

Flags (LlamaParse engine)

  • --out DIR: write markdown into DIR (default: alongside each input PDF).
  • --tier: fast (1 credit/page), cost_effective (3, default), agentic (10), agentic_plus (45). Escalate above cost_effective only when the user asks for higher quality or a complex document parses poorly.
  • --images: also download embedded images to <stem>_images/ next to the markdown. Use only when the user asks for images.
  • --layout: request structured layout boxes (+3 credits/page). Use only when the user explicitly asks for layout or bounding-box data; it does NOT improve markdown quality.

Defaults to apply when the user is vague

  • If the working project has separate pdf/ and md/ directories, default to --out ./md.
  • Otherwise omit --out so the markdown lands next to the source file.
  • Do not pass --layout or --images unless asked.

Cost notes (LlamaParse engine)

  • Free plan: 10,000 credits/month. Cost-effective = 3 credits/page, roughly 3,300 pages/month free.
  • Adding --layout costs +3 credits/page on top of the tier.
  • --images itself is free; it just downloads what was extracted.
  • The local engines cost nothing regardless of volume.

Known quirk

With cost-effective tier + --images, some markdown image references use placeholder names (e.g. page_1_image_1_v2.jpg) that don't always match the extracted image files (e.g. img_p1_2.png). Tell the user this if they care about exact in-markdown linking; the workaround is rerunning with --tier agentic.

After running

  • Confirm the output path(s) and, for the LlamaParse engine, the page count printed by the script.
  • If --images was used, confirm the image directory and file count.
  • Do not auto-open the markdown unless the user asks.