doc-format-converter

name

doc-format-converter

description

Use this skill whenever the user asks to convert a document or file from one format to another — Markdown, HTML, PDF, Word (.docx), PowerPoint (.pptx), Excel (.xlsx), CSV, or plain text (e.g. "turn this Word doc into a PDF", "make slides from this markdown", "save this page as markdown"). Only for producing a converted file as a deliverable. Do NOT use this skill to answer questions about a document's content — the analyzing-* skills handle that. Run the bundled scripts/convert.py instead of writing ad-hoc conversion code, BEFORE attempting any conversion yourself.

Convert documents between formats using the bundled scripts/convert.py. It works fully offline with libraries already present in the sandbox (markitdown, mammoth, markdownify, reportlab, python-docx, python-pptx, pdfplumber, beautifulsoup4, magika) and routes each conversion through the highest-fidelity pipeline available.

Division of labor with the analyzing-* skills

This skill produces files; the built-in analyzing-* skills answer questions. Route accordingly:

• "What does this PDF say?", "find X in this workbook", "summarize this deck" → use analyzing-pdf / analyzing-xlsx / analyzing-pptx etc., not this skill. In particular, never use convert.py as a substitute extraction path for PDF question-answering — analyzing-pdf owns that.
• "Give me this as a PDF/Word doc/slides/markdown file" → this skill.
• If the user asks content questions after a conversion, hand off to the matching analyzing-* skill on the original file rather than answering from this skill's intermediate output.
• Reuse their artifacts when present. If an analyzing-* preprocessor has already produced a converted.md for the source file, feed that to convert.py as Markdown input (convert.py converted.md --to pptx) instead of re-extracting the original — it is a high-quality extraction with page markers and pipe tables.

Instructions

1. Identify the input file and the target format the user wants. Targets: md, html, pdf, docx, pptx, txt. Inputs additionally include xlsx and csv.

2. Run the converter by the script's path inside this skill's folder — typically /app/skills/doc-format-converter/ — so it works regardless of the current working directory:

   python /app/skills/doc-format-converter/scripts/convert.py INPUT --to FORMAT [-o OUTPUT]
   

   It prints the output path on success. If -o is omitted, the output lands next to the input with the new extension.

3. For a folder of files, use batch mode and share the printed summary table with the user:

   python /app/skills/doc-format-converter/scripts/convert.py --batch DIR --to FORMAT [--out-dir DIR]
   

4. If the script reports an unsupported conversion, relay its message — it prints the full support matrix. Offer the nearest supported route (e.g. PDF → slides is unsupported; offer PDF → Markdown, let the user edit, then Markdown → PPTX).

5. If the script warns that a file's extension doesn't match its content (content sniffing via magika), tell the user; the converter proceeds using the detected content type.

6. Return the converted file to the user and briefly state which pipeline was used (e.g. "docx → HTML via mammoth").

Conversion notes

• Markdown is the universal intermediate: Office/PDF inputs are extracted with markitdown, then re-rendered. Some layout (columns, images, footnotes) is simplified — say so when converting layout-heavy documents.
• For scanned/image PDFs, this skill's pdf → md route extracts little or nothing. Run the analyzing-pdf preprocessor instead (its OCR pipeline is the better extractor) and feed its text artifact into this skill's renderers.
• PDF output registers a CJK-capable font automatically (bundled Noto CJK fonts, falling back to reportlab's built-in CID fonts), so Chinese, Japanese, and Korean text renders correctly.
• PPTX output builds one slide per #/## heading with body content as bullets, overflowing onto continuation slides — it is an outline deck, not finished design.
• pdf → pptx and pptx → pdf/docx are deliberately unsupported: the extraction is too lossy to present as a finished conversion.

Guardrails

• Never fabricate or "fill in" content the source file does not contain; if extraction returns nothing, report that instead of inventing text.
• Do not hand-write conversion code when convert.py supports the pair; only fall back to custom code if the script fails, and say that you did.
• Never claim a conversion succeeded without the script's success output.
• Verification test cases live in references/test-cases.md with fixtures in assets/samples/ — use them when the user asks to validate the skill.