markdown-tools_skill

Overview

This skill converts documents to high-quality Markdown using a dual-mode, multi-tool orchestration. I provide Quick Mode for fast, good-quality conversions and Heavy Mode for slower, highest-quality output that merges results from multiple tools. It handles PDFs, DOCX, PPTX (and some XLSX workflows), image extraction, and conversion validation.

How this skill works

The skill runs one or more conversion tools (pymupdf4llm, markitdown, pandoc) and parses each output into segments like headings, tables, images, lists, and paragraphs. In Quick Mode it uses the single best tool for speed; in Heavy Mode it runs tools in parallel, scores segments for completeness and structure, then intelligently merges the best segment versions into a single Markdown output. Additional scripts extract images with metadata, validate conversion quality, and allow manual merge/analysis.

When to use it

• Convert PDFs, DOCX, or PPTX to Markdown for publishing or editing.
• Extract images and metadata from PDFs for reuse or asset management.
• Produce final, publication-ready Markdown using Heavy Mode when layout and tables must be exact.
• Quick drafts and fast previews where speed matters more than perfect fidelity.
• Validate or audit conversion quality with automated metrics and an HTML report.

Best practices

• Start with Quick Mode to evaluate baseline output, then run Heavy Mode for final deliverables.
• Install and enable the recommended tools for each format (pymupdf4llm, markitdown, pandoc) to maximize Heavy Mode coverage.
• Run image extraction separately when you need original assets or higher-resolution images.
• Use the validation script after conversion to check text/table/image retention and address weak segments.
• When merging outputs manually, enable verbose attribution to see which tool produced each segment.

Example use cases

• Convert a multipage research PDF into editable, structured Markdown with extracted figures and captions.
• Migrate a DOCX report to Markdown while preserving headings, tables, and inline images for a static site generator.
• Create a Markdown handout from a PPTX slideshow, extracting slide images and speaker notes.
• Batch process technical docs: run Quick Mode for drafts, then Heavy Mode for final merges and validation.
• Generate an HTML validation report to certify conversion quality for archival or compliance workflows.