Skill v1.0.0

version: "1.0.0" 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.

1. 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:

``bash 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.

1. For a folder of files, use batch mode and share the printed summary table

with the user:

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

1. 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).

1. 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.

1. 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.